Editing Guide to RSF file format (section)

==Principles==
The main design principle behind the RSF data format is [http://en.wikipedia.org/wiki/KISS_principle KISS] ("Keep It
Short and Simple"). The RSF format is borrowed from the SEPlib data format
initially designed at the Stanford Exploration Project
(Claerbout, 1991<ref>Claerbout, J. F.,  1991, Introduction to Seplib and SEP utility software,  ''in'' SEP-70,  413--436. Stanford Exploration Project.</ref>). The format is made as simple as possible for maximum convenience, transparency, and flexibility.
According to the Unix tradition, standard file formats should be in a readable
textual form to be easily examined and processed with universal
tools. Raymond (2004<ref>Raymond, E. S.,  2004, The art of UNIX programming: Addison-Wesley.</ref>) writes:
<blockquote>
To design a perfect anti-Unix, make all file formats binary and opaque and
require heavyweight tools to read and edit them.
</blockquote>
<blockquote>
If you feel an urge to design a complex binary file format or a complex
binary application protocol, it is generally wise to lie down until the
feeling passes.
</blockquote>
Storing large-scale datasets in a text format may not be economical. RSF
chooses the next best thing: it allows data values to be stored in a binary
format but puts all data attributes in text files that humans can read
and processed with universal text-processing utilities.
===Example===
Let us first create some synthetic RSF data.
<pre>
bash$ sfmath n1=1000 output='sin(0.5*x1)' > sin.rsf
</pre>
Open and read the file <tt>sin.rsf</tt>.
<pre>
bash$ cat sin.rsf
sfmath  rsf/rsf/rsftour:        fomels@egl      Sun Jul 31 07:18:48 2005

        o1=0
        data_format="native_float"
        esize=4
        in="/tmp/sin.rsf@"
        x1=0
        d1=1
        n1=1000
</pre>
The file contains nine lines with simple, readable text. The first line
shows the name of the program, the working directory, the user, and
computer that created the file and the time it was created (that
information is recorded for accounting purposes). Other lines contain
parameter-value pairs separated by the "=" sign. The "in"
parameter points to the location of the binary data. Before we discuss the meaning of parameters in more detail, let us plot the data.
<pre>
bash$ < sin.rsf  sfwiggle title='One Trace' | sfpen
</pre>
You should see a plot similar to the figure below on your screen.
[[Image:sin1.png|frame|center|An example sinusoid plot.]]
Suppose you want to reformat the data so that instead of one trace of a thousand samples, it contains twenty traces with fifty samples each. Try
running
<pre>
bash$ < sin.rsf sed 's/n1=1000/n1=50 n2=20/' > sin10.rsf 
bash$ < sin10.rsf sfwiggle title=Traces | sfpen
</pre>
or (using pipes)
<pre>
bash$ < sin.rsf sed 's/n1=1000/n1=50 n2=20/' | sfwiggle title=Traces | sfpen
</pre>
On your screen, you should see a plot similar to the figure below:
[[Image:sin2.png|frame|center|An example sinusoid plot, with data reformatted to twenty traces.]]
What happened? We used <tt>sed</tt>, a standard Unix line editing utility, to
change the parameters describing the data dimensions. Because of the
simplicity of this operation, there is no need to create specialized data
formatting tools or to make the <tt>sfwiggle</tt> program accept additional
formatting parameters. Other general-purpose Unix tools that can be applied on
RSF files include <tt>cat</tt>, <tt>echo</tt>, <tt>grep</tt>, etc. 
An alternative way to obtain the previous result is to run
<pre>
bash$ ( cat sin.rsf; echo n1=50 n2=20 ) > sin10.rsf 
bash$ < sin10.rsf sfwiggle title=Traces | sfpen
</pre>
In this case, the <tt>cat</tt> utility copies the contents of the
previous file, and the <tt>echo</tt> utility appends a new line "<tt>n1=50
n2=20</tt>". A new value of the <tt>n1</tt> parameter overwrites the old value
of <tt>n1=1000</tt>, and we achieve the same result as before.
Of course, one could also edit the file by hand with one of the general-purpose text editors. For recording the history of data processing, it is
usually preferable to be able to process files with non-interactive tools.