Editing Package overview (section)

==How to find your way around Madagascar==

Start by checking the [[Reproducible_Documents|list of reproducible papers]]. If any of these papers look close to your interests, follow the links until you find a figure with a "wrench" button under it [[Image:configure.png]]. Click on the wrench, and it will open a computational recipe used for generating the figure (the <tt>SConstruct</tt> file). 
<syntaxhighlight lang="python">
from rsf.proj import *
Flow('rose',None,
     '''
     math n1=629 d1=0.01 o1=0 n2=40 d2=1 o2=5 
     output="x2*(8+sin(6*x1+x2/10))" |
     rtoc |
     math output="input*exp(I*x1)"
     ''')
Result('rose',
       'graph title=Rose screenratio=1 wantaxis=n')
End()
</syntaxhighlight>
You can copy this recipe to your computer or find it already in the "book" subtree under the Madagascar source directory. For example, the recipe at https://ahay.org/RSF/book/rsf/rsf/sfmath.html also exists in the file <tt>RSFSRC/book/rsf/rsf/sfmath/SConstruct</tt>. After copying or locating the appropriate <tt>SConstruct</tt> file,
run
<pre>
scons view
</pre>
on the command line to generate all the figures in the selected project and to display them on your screen. For example, try
<pre>
bash$ cd RSFSRC/book/rsf/rsf/sfmath
bash$ scons view
</pre>
where <tt>bash$</tt> stands for the Unix prompt and <tt>RSFSRC</tt> stands for the Madagascar source directory. The output should look like
<pre>
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
/RSFROOT/bin/sfmath n1=629 d1=0.01 o1=0 n2=40 d2=1 o2=5 output="x2*(8+sin(6*x1+x2/10))" | /RSFROOT/bin/sfrtoc | 
/RSFROOT/bin/sfmath output="input*exp(I*x1)" > rose.rsf
< rose.rsf /RSFROOT/bin/sfgraph title=Rose screenratio=1 wantaxis=n > Fig/rose.vpl
/RSFROOT/bin/sfpen Fig/rose.vpl
scons: done building targets.
</pre>
with a picture appearing on your screen.
[[Image:rose.png|frame|center]]
If there are several figures in the recipe, you can run
<pre>
scons figurename.view
</pre>
(e.g. <tt>scons rose.view</tt>) to display individual figures. To remove all files that <tt>scons view</tt> generated, run
<pre>
scons -c view
</pre>
If you want to know in advance what commands will be executed to generate the figures, try
<pre>
scons -n view
</pre>
You can output this command to a file
<pre>
scons -n -Q view > script.sh
</pre>
and use <tt>script.sh</tt> as a shell script. If you are to modify the data processing recipe (changing parameters or trying new data), working with SCons is more powerful and convenient than running shell scripts.

A computational recipe puts together individual commands through Unix pipes and SCons rules. These commands act like Lego blocks for creating complex data analysis constructions. In the example above, three "blocks" are used: <tt>sfmath</tt>, <tt>sfrtoc</tt>, and <tt>sfgraph</tt>. To find out what a particular command is doing, follow the links from the bottom of the web page: https://ahay.org/RSF/book/rsf/rsf/sfmath.html .
Alternatively, run the command without arguments on the command line. Running
<pre>
bash$ sfrtoc
</pre>
produces something like
<pre>
NAME
        sfrtoc
DESCRIPTION
        Convert real data to complex (by adding zero imaginary part).
SYNOPSIS
        sfrtoc < real.rsf > cmplx.rsf
COMMENTS   
        See also: sfcmplx
USED IN
        bei/ft1/plane4
        bei/ft1/autocor
        bei/ft1/brad
        [...]
SOURCE
        user/main/rtoc.c
DOCUMENTATION
        https://ahay.org/wiki/Guide_to_madagascar_programs#sfrtoc
</pre>

The <b>DOCUMENTATION</b> section links to more detailed documentation on the web. The most helpful part is the <b>USED IN</b> section, which points to more examples of using the program. As an exercise, change the directory to <tt>RSFSRC/book/bei/ft1/plane4</tt> or any other example directory, examine the <tt>SConstruct</tt> file and run <tt>scons view</tt>. Alternatively, look at https://ahay.org/RSF/book/bei/ft1/plane4.html .

Want to find a program by keywords? Try <tt>sfdoc -k</tt>.
<pre>
bash$ sfdoc -k complex
sfsort: Sort a float/complex vector by absolute values.
sfrtoc: Convert real data to complex (by adding zero imaginary part).
sfjacobi2: Find eigenvalues of a general complex matrix by Jacobi-like iteration. 
sfboolcmp: Element-wise boolean comparison of values. For int/float/complex datasets.
sfcmatmult: Simple matrix multiplication for complex matrices 
sfimag: Extract real (sfreal) or imaginary (sfimag) part of a complex dataset. 
sfthr: Threshold float/complex inputs given a constant/varying threshold level.
sfcpef: 1-D prediction-error filter estimation from complex data 
sfroots: Find roots of a complex polynomial. 
sfreal: Extract real (sfreal) or imaginary (sfimag) part of a complex dataset. 
sfcmplx: Create a complex dataset from its real and imaginary parts.
sfsin: Simple operations with complex sinusoids 
sfcdottest: Generic dot-product test for complex linear operators with adjoints 
sfcconjgrad: Generic conjugate-gradient solver for linear inversion with complex data
</pre>

Individual components of the Madagascar environment are described in more detail below.