Editing Guide to madagascar programs (section)

==sfheadersort==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Sort a dataset according to a header key. 
|-
! colspan="4" | sfheadersort < in.rsf > out.rsf head=
|-
| ''string '' || '''head=''' ||   || 	header file
|}


<tt>sfheadersort</tt> is used to sort traces in the input file
according to trace header information. 
Here is an example of using
<tt>sfheadersort</tt> for randomly shuffling traces in the input
file. First, let us create an input file with seven traces:
<pre>
bash$ sfmath n1=5 n2=7 output=x2+1 > input.rsf
bash$ < input.rsf sfdisfil
   0:             1            1            1            1            1
   5:             2            2            2            2            2
  10:             3            3            3            3            3
  15:             4            4            4            4            4
  20:             5            5            5            5            5
  25:             6            6            6            6            6
  30:             7            7            7            7            7 
</pre>
Next, we can create a random file with seven header values using
<tt>sfnoise</tt>.
<pre>
bash$ sfspike n1=7 | sfnoise rep=y type=n > random.rsf
bash$ < random.rsf sfdisfil
   0:       0.05256      -0.2879       0.1487       0.4097       0.1548
   5:        0.4501       0.2836
</pre>
If you reproduce this example, your numbers will most likely be different,
because, in the absence of <tt>seed=</tt> parameter, <tt>sfnoise</tt>
uses a random seed value to generate pseudo-random numbers. Finally, we
apply <tt>sfheadersort</tt> to shuffle the input traces.
<pre>
bash$ < input.rsf sfheadersort head=random.rsf > output.rsf
bash$ < output.rsf sfdisfil
   0:             2            2            2            2            2
   5:             1            1            1            1            1
  10:             3            3            3            3            3
  15:             5            5            5            5            5
  20:             7            7            7            7            7
  25:             4            4            4            4            4
  30:             6            6            6            6            6
</pre>
As expected, the order of traces in the output file corresponds to the
order of values in the header. Thanks to the separation between
headers and data, the operation of <tt>sfheadersort</tt> is optimally
efficient. It first sorts the headers and only then accesses the data,
reading each data trace only once.