Editing Guide to madagascar programs (section)

==sfspike==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generate simple data: spikes, boxes, planes, constants. 
|-
! colspan="4" | sfspike < in.rsf > spike.rsf mag= nsp=1 k#=[0,...] l#=[k1,k2,...] p#=[0,...] n#= o#=[0,0,...] d#=[0.004,0.1,0.1,...] label#=[Time,Distance,Distance,...] unit#=[s,km,km,...] title=
|-
|  colspan="4" | <br>Spike positioning is given in samples and starts with 1.
|-
| ''float  '' || '''d#=[0.004,0.1,0.1,...]''' ||   || 	sampling on #-th axis
|-
| ''ints   '' || '''k#=[0,...]''' ||   || 	spike starting position  [nsp]
|-
| ''ints   '' || '''l#=[k1,k2,...]''' ||   || 	spike ending position  [nsp]
|-
| ''string '' || '''label#=[Time,Distance,Distance,...]''' ||   || 	label on #-th axis
|-
| ''floats '' || '''mag=''' ||   || 	spike magnitudes  [nsp]
|-
| ''int    '' || '''n#=''' ||   || 	size of #-th axis
|-
| ''int    '' || '''nsp=1''' ||   || 	Number of spikes
|-
| ''float  '' || '''o#=[0,0,...]''' ||   || 	origin on #-th axis
|-
| ''floats '' || '''p#=[0,...]''' ||   || 	spike inclination (in samples)  [nsp]
|-
| ''string '' || '''title=''' ||   || 	title for plots
|-
| ''string '' || '''unit#=[s,km,km,...]''' ||   || 	unit on #-th axis
|}


<tt>sfspike</tt> takes no input and generates an output with
"spikes". It is an easy way to create data. Here is an example:
<pre>
bash&#36; sfspike n1=5 n2=3 k1=4 k2=1 | sfdisfil
   0:             0            0            0            1            0
   5:             0            0            0            0            0
  10:             0            0            0            0            0
</pre>
The spike location is specified by parameters <tt>k1=4</tt> and
<tt>k2=1</tt>. Note that the locations are numbered starting from 1. 
If one of the parameters is omitted or given the value of zero, the 
spike in the corresponding direction becomes a plane:
<pre>
bash&#36; sfspike n1=5 n2=3 k1=4 | sfdisfil   
   0:             0            0            0            1            0
   5:             0            0            0            1            0
  10:             0            0            0            1            0

</pre>
If no spike parameters are given, the whole dataset is filled with ones:
<pre>
bash&#36; sfspike n1=5 n2=3 | sfdisfil
   0:             1            1            1            1            1
   5:             1            1            1            1            1
  10:             1            1            1            1            1
</pre>
To create several spikes, use the <tt>nsp=</tt> parameter and give a comma-separated list of values to <tt>k#=</tt> arguments:
<pre>
bash&#36; sfspike n1=5 n2=3 nsp=3 k1=1,3,4 k2=1,2,3 | sfdisfil
   0:             1            0            0            0            0
   5:             0            0            1            0            0
  10:             0            0            0            1            0
</pre>
If the number of values in the list is smaller than <tt>nsp</tt>, the
last value gets repeated, and the spikes add on top of each other,
creating larger amplitudes:
<pre>
bash&#36; sfspike n1=5 n2=3 nsp=3 k1=1,3 k2=1,2 | sfdisfil
   0:             1            0            0            0            0
   5:             0            0            2            0            0
  10:             0            0            0            0            0
</pre>
The magnitude of the spikes can be controlled explicitly with the
<tt>mag=</tt> parameter:
<pre>
bash&#36; sfspike n1=5 n2=3 nsp=3 k1=1,3,4 k2=1,2,3 mag=1,4,2 | sfdisfil
   0:             1            0            0            0            0
   5:             0            0            4            0            0
  10:             0            0            0            2            0
</pre>
You can create boxes instead of spikes by using <tt>l#=</tt>
parameters:
<pre>
bash&#36; sfspike n1=5 n2=3 k1=2 l1=4 k2=2 mag=8 | sfdisfil
   0:             0            0            0            0            0
   5:             0            8            8            8            0
  10:             0            0            0            0            0
</pre>
In this case, <tt>k1=2</tt> specifies the box start, and <tt>l1=4</tt>
specifies the box end.
Finally, multi-dimensional planes can be given an inclination by using <tt>p#=</tt> parameters:
<pre>
bash&#36; sfspike n1=5 n2=3 k1=2 p2=1 | sfdisfil
   0:             0            1            0            0            0
   5:             0            0            1            0            0
  10:             0            0            0            1            0
</pre>
Note that <tt>sfspike</tt> interprets the <tt>p#=</tt> parameters in stepout from sample to sample, not in terms of axes units (i.e. s/m). 

More than one p parameter can be specified. In this case, a (hyper) plane will be created.

When the inclination value is not integer, simple linear interpolation is used:
<pre>
bash&#36; sfspike n1=5 n2=3 k1=2 p2=0.7 | sfdisfil
   0:             0            1            0            0            0
   5:             0          0.3          0.7            0            0
  10:             0            0          0.6          0.4            0
</pre>
<tt>sfspike</tt> supplies default dimensions and labels to all axes:
<pre>
bash&#36; sfspike n1=5 n2=3 n3=4 > spike.rsf
bash&#36; sfin spike.rsf
spike.rsf:
    in="/var/tmp/spike.rsf@"
    esize=4 type=float form=native 
    n1=5           d1=0.004       o1=0          label1="Time" unit1="s" 
    n2=3           d2=0.1         o2=0          label2="Distance" unit2="km" 
    n3=4           d3=0.1         o3=0          label3="Distance" unit3="km" 
	60 elements 240 bytes
</pre>
As you can see, the first axis is assumed to be time, with sampling of
<math>0.004</math> seconds. All other axes are assumed to be distance, with
sampling of <math>0.1</math> kilometers. All these parameters can be changed on
the command line.
<pre>
bash&#36; sfspike n1=5 n2=3 n3=4 label3=Offset unit3=ft d3=20 > spike.rsf
bash&#36; sfin spike.rsf
spike.rsf:
    in="/var/tmp/spike.rsf@"
    esize=4 type=float form=native 
    n1=5           d1=0.004       o1=0          label1="Time" unit1="s" 
    n2=3           d2=0.1         o2=0          label2="Distance" unit2="km" 
    n3=4           d3=20          o3=0          label3="Offset" unit3="ft" 
	60 elements 240 bytes
</pre>