Users

SConstructs and commands

SCons scripts are called SConstructs. In order to use SCons, you must create an SConstruct in the local directory where you want to work. Since SCons is written in Python, an SConstruct is simply a text file written using Python syntax. If you don't know Python, you can still use SCons, because the syntax is simple.

First, a primer on Python syntax. In SConstructs we are going to deal with Python functions and strings. Python functions are simple, and should be familiar to anyone who has used a programming language. For example, calling a Python function, foo, looks like:

One argument - foo(1).
Many arguments - foo(1,2,3,4,5,123)

Python functions can take many arguments, and arguments of different types, but the syntax is the same. Python strings are also very similar to other programming languages. In Python anything inside double quotes is automatically considered to be a string, and not a variable declaration. However, Python also supports a few notations to indicate strings (or long strings) as shown below:

"this is a string"
'this is a string'
"""this is a string"""
'''this is a string'''

Somtimes in Python you will need to nest a string within a string. To do use one of the string representations for the outer string, and use a different one for the inner string. For example:

"""sfgraph title="my plot" """  OR
''' sfgraph title="my plot" ''' OR
'   sfgraph title="my plot" '

Fundamentally, Madagascar's data-processing SConstructs are composed of only four commands: Fetch, Flow, Plot and Result. The main command is Flow. A Flow creates a relationship between the input file, the output file, and the processing command used to create the output file from the input file. The syntax for a Flow is:

Flow(output file,input file,command)

where, target and source are file names (strings), and command is a string that contains the Madagascar program to be used, along with the command line parameters needed for that program to run. For example:

Flow("spike1","spike","scale dscale=4.0")

creates a dependency relationship between the output file 'spike1' and the input file 'spike'. The dependency indicates that 'spike1' cannot be created without 'spike' and that if 'spike' changes then 'spike1' also changes. The relationship in this case is that 'spike1' should be 'spike' scaled by four times. The equivalent command on the command line would be:

< spike.rsf sfscale dscale=4.0 > spike1.rsf

Note: the file names of the input and output files do not need to include '.rsf' on the end of the files as SCons automatically adds the suffix to all of our file names.

Now that we can create relationships between files using Flows, we can create an SConstruct to do all of our data processing using SCons. However, we often want to visualize the results of our processing in order to quality control the results. In order to create Plots (or other visualizations) in Madagascar we have two additional SCons commands: Plot and Result. Plot and Result tell SCons how to use Madagascar's plotting programs to create visualizations of files on the fly after they have been computed. The syntax for both Plot and Result is as follows:

Plot(input file, command)
OR
Result(input file, command)

In both cases, the Plot or Result command tells SCons to build a VPLOT file with same file name as the input file (with the .vpl suffix instead) from the input file using the command provided. For example, if we want to make a graph of a file we could use:

Plot("spike1","sfgraph pclip=100")

Behind the scenes, SCons establishes that we want to use "spike1.rsf" to create a Plot called "spike1.vpl" using sfgraph. The equivalent command line operation is:

< spike1.rsf sfgraph pclip=100 > spike1.vpl

Result can be used in the same way as Plot, illustrated above.

At this point, you might be asking yourself, what's the difference between Plot and Result? The answer is that Plot creates all VPLOT files in the local directory, whereas Result creates its VPLOT files in a subdirectory called Fig. Fig is a location used to store Plots that we want to later use when creating papers using L^ATEX. By default, you should use Plot when creating visualizations. Only use Result when you want to save something to be used in a paper. Note: since the VPLOTs from Plot and Result are placed in different locations you can use both Plot and Result for a single RSF file, but create two different plots for the same file.

Users