Tutorial - Users 1 - Command line interface

Madagascar is designed to be used from the command line. Programmers create Madagascar programs (prefixed with the sf designation) that read and write Madagascar files. These programs are designed to be as general as possible, each one operates on any dataset provided in RSF format, provided you also provide the correct parameters and have the right type of data for the program. Thus, each Madagascar program can be used in even ways that the original developer may not have foreseen, which makes your life easier as a user!

Command line interface

Madagascar programs follow the standard UNIX conventions for reading and writing RSF files to and from STDIN and STDOUT. This is also the same convention that SeismicUnix uses, so for those of you who are SU fans, this should be an easy conversion.

For example: the program sfattr allows us to get attributes about an RSF file (mean, standard deviation, min, max, etc.) To get the attributes for a pre-computed file, we might use:

sfattr < junk.rsf

which outputs:

    rms =       1.41316 
   mean =      0.999667 
 2-norm =       357.503 

variance = 0.997693

std dev =      0.998846 
    max =       5.05567 at 36 8 27 
    min =      -3.59936 at 18 9 6 

nonzero samples = 64000

 total samples = 64000 

For an example of reading and writing an RSF file I'm going to demonstrate the use of sfwindow which is a program that allows us to select portions of an RSF file. When sfwindow is used without any additional parameters, we are able to make a copy of a file with a different filename. For example:

sfwindow < junk.rsf > junk2.rsf

gives us two files, junk.rsf and junk2.rsf which are identical but not the same file.

In addition to specifying files to read in and out on the command line we can specify the parameters for each program that are necessary for it to run, or to produce the desired result. The general format for specifying parameters on the command line is key=val, where key is the name of the parameter that you want to set, and val is the value of the parameter. There are four (4) different types of values that are acceptable: int, float, boolean, or string. Going back to the window program, we can specify the number of traces or pieces of the file that we want to keep like:

sfwindow < junk.rsf n1=10 > junk-win.rsf

Self-documentation

Of course, we can specify as many parameters as we'd like on the command line. To figure out which parameters are needed for a specific program, just type the name of the program with no input files our output files on the command line as follows:

sfwindow

which brings up the self-documentation, which looks something like the following:

NAME

       sfwindow

DESCRIPTION

       Window a portion of a dataset. 

SYNOPSIS

       sfwindow < in.rsf > out.rsf verb=n squeeze=y j#=(1,...) d#=(d1,d2,...) f#=(0,...) min#=(o1,o2,,...) n#=(0,...) max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)

PARAMETERS

       float   d#=(d1,d2,...)  sampling in #-th dimension 
       largeint f#=(0,...)     window start in #-th dimension 
       int     j#=(1,...)      jump in #-th dimension 
       float   max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)   maximum in #-th dimension 
       float   min#=(o1,o2,,...)       minimum in #-th dimension 
       largeint n#=(0,...)     window size in #-th dimension 
       bool    squeeze=y [y/n] if y, squeeze dimensions equal to 1 to the end 
       bool    verb=n [y/n]    Verbosity flag

USED IN

       bei/dpmv/krchdmo
       bei/dpmv/matt
       bei/dwnc/sigmoid
       bei/fdm/kjartjac
       bei/fld/cube
       bei/fld/shotmovie
       bei/fld/synmarine
       bei/fld/yc
       bei/ft1/autocor

The self-documentation tells us the function of the program, as well as the parameters that are available to be specified. The parameter format is type - name=default value [options] and then a short description of the parameter. File parameters request a name of a file. For example: file=junk.rsf

Piping

Sometimes we want to chain multiple commands together without writing intermediate Madagascar RSF files in the process. Fortunately, we can do this using another standard UNIX construct, Pipes. Pipes allow us to connect the standard output from one Madagascar program to the standard input to another program without first writing to a file. For example we could do the following without pipes:

sfwindow < junk.rsf > junk-win.rsf sftransp < junk-win.rsf > junk2.rsf

Or we could do the equivalent using pipes on one line:

sfwindow < junk.rsf | sftransp > junk2.rsf

Pipes simply make these statements more compact, and allow us to reduce the number of files that we need to save to disk. If you're doing something many times over, then pipes will make your life significantly easier. I highly recommend that you use pipes! Also, you should know that you can chain as many commands together as necessary using Pipes.

Note: Madagascar uses a trick to make sure that you can send as much data as you want through the pipes because a conventional UNIX pipe has a maximum amount of data that can be sent through it. To avoid this limitation, Madagascar writes the data to temporary files before sending it through a pipe.

Commonly used programs

Here's a short list of commonly used programs, their usage:

sfwindow - window out portions of a dataset sftransp - transpose the axes of a dataset sfin - see the shape of a file (axes) sfattr - common attributes of files sfspike - create files sfmath - basic mathematical operations (add subtract multiply) sfadd - like sfmath but easier to use sfgrey - raster plots sfgraph - line plots sfwiggle - wiggle plots

For more information see Program guide.