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!
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
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
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:
which brings up the self-documentation, which looks something like the following:
Window a portion of a dataset.
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,,...)
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
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
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: http://reproducibility.org/wiki/Guide_to_madagascar_programs
- Interacting with files