Madagascar tutorial

First steps

You can skip this section if you are already familiar with Madagascar.

If these are your first experience, let us start with simple steps.

1. Create a new directory and change to it.

   bash$ mkdir first
   bash$ cd first
   

2. Let us create some data. Run

   bash$ sfmath n1=501 d1=0.004 output=1.5+x1 > vel.rsf
   

3. Run

   bash$ file vel.rsf
   

   to verify that vel.rsf is a ASCII text file. Examine the contents of the file by running

   bash$ cat vel.rsf
   

   Find a string starting with in=. It should point to the location of the binary file containing the actual data.
4. A more convenient way to check the file parameters is running

   bash$ sfin vel.rsf
   

   Verify that the reported binary file size in bytes corresponds to the number of elements multiplied by the size of one element (4 bytes for a single-precision floating-point number).
5. To inspect data elements one by one, run

   bash$ < vel.rsf sfdisfil | more
   

   What is the minimum and maximum value?
6. A more convenient way to check the data statistics is by running

   bash$ < vel.rsf sfattr
   

   Note that you can run any of the Madagascar programs (sfmath, sfin, sfdisfil, sfattr) on the command line without parameters to display their brief documentation. For examine, run

   bash$ sfattr
   

   to figure out what parameter to give to this program to display only the maximum value of the input data.
7. Now let us display the data on the screen. Run

   bash$ < vel.rsf sfgraph wanttitle=n \
   label1=Time unit1=s label2=Velocity unit2=km/s | sfpen
   

8. Suppose we want the time axis in the display to run vertically. Run

   bash$ sfgraph
   

   without parameters to figure out which parameter transposes the axes. Generate a new graph.
9. Running all commands on the command line can be tedious, especially for complex processing flows. The preferred way to control processing flows in Madagascar is by using the SCons utility. Create a file called SConstruct using your favorite editor, for example

   bash$ gedit SConstruct &
   

   Your first SConstruct may contain the following lines: The SConstruct file is written in the Python language. The first line tells SCons to load all commands from the rsf.proj module, which contains the definitions of Flow and Plot commands. Note that Python uses triple quotes for strings that span multiple lines.
10. To see what commands SCons is going to execute without actually executing them, run

    bash$ scons -nQ
    

    Note that you can save the output of this command in a Shell script. Running processing flows with SCons scripts rather than Shell scripts is, however, a more powerful method, as we shall see next.
11. Run

    bash$ scons
    

    to build the targets specified in SConstruct: files vel.rsf and vel.vpl. The second file is a figure in Vplot binary format. You can display it on the screen by running

    bash$ sfpen vel.vpl
    

12. Edit the SConstruct file to modify the number of samples (n1= parameter.) Then run

    bash$ scons
    

    again to rebuild the targets.
13. Now edit the SConstruct file to change wanttitle=n parameter to give your figure a title, for example title="My Velocity". Run

    bash$ scons
    

    and observe that, this time, SCons does not rebuild all the targets but only the target (vel.vpl file) affected by the parameter change. This behavior makes SCons particularly convenient for working with complex workflows and conducting experiments, which require repeated changes of parameters.

Madagascar tutorial