Editing Guide to RSF file format (section)

==Header and Data files==
A simple way to check the layout of an RSF file is with the <tt>sfin</tt>
program.
<pre>
bash$ sfin sin10.rsf
sin10.rsf:
    in="/tmp/sin.rsf@"
    esize=4 type=float form=native
    n1=50          d1=1           o1=0
    n2=20          d2=?           o2=?
        1000 elements 4000 bytes
</pre>
The program reports the following information: the location of the data file
(<tt>/tmp/sin.rsf\@</tt>), the element size (4 bytes), the element
type (floating point), the element form (native), the hypercube dimensions
(<math>50 \times 20</math>), axis scaling (1 and unspecified), and axis origin (0 and
unspecified). It also checks the total number of elements and bytes in the
data file.
Let us examine this information in detail. First, we can verify that the data
file exists and contains the specified number of bytes:
<pre>
bash$ ls -l /tmp/sin.rsf@
-rw-r--r--  1 sergey users 4000 2004-10-04 00:35 /tmp/sin.rsf@
</pre>
4000 bytes in this file are required to store <math>50 \times 20</math> floating-point
4-byte numbers in a binary form. Thus, the data file contains only the
raw data in a contiguous binary form.
===Datapath===
How did the RSF program (<tt>sfmath</tt>) decide where to put the data file?
In the order of priority, the rules for selecting the data file name and the
data file directory are as follows:
  
#Check <tt>--out=</tt> parameter on the command line. The parameter specifies the output data file location explicitly. 
#Specify the path and the file name separately.    
#*The rules for the path selection are:   
#*#Check <tt>datapath=</tt> parameter on the command line. The parameter specifies a string to prepend to the file name. The string may contain the file directory. 
#*#Check <tt>DATAPATH</tt> environmental variable. It has the same meaning as the parameter specified with <tt>datapath=</tt>. 
#*#Check for <tt>.datapath</tt> file in the current directory. The file may contain a line  <pre> datapath=/path/to_file/ </pre> or <pre> machine_name datapath=/path/to_file/ </pre> if you intend to use different paths on different platforms. 
#*#Check for <tt>.datapath</tt> file in the user's home directory. 
#*#Put the data file in the current directory (similar to <tt>datapath=./</tt>). 
#*: 
#*The rules for the filename selection are:   
#*#If the output RSF file is in the current directory, the name of the data file is made by appending \@. 
#*#If the output file is not in the current directory or is created temporarily by a program, the name is made by appending random characters to the program's name and selected to be unique. 

Examples:

<pre>
bash$ sfspike n1=10 --out=test1 > spike.rsf 
bash$ grep in spike.rsf         
in="test1" 
</pre> 

<pre>
bash$ sfspike n1=10 datapath=/tmp/ > spike.rsf 
bash$ grep in spike.rsf         
in="/tmp/spike.rsf@" 
</pre> 

<pre>
bash$ DATAPATH=/tmp/ sfspike n1=10 > spike.rsf 
bash$ grep in spike.rsf         
in="/tmp/spike.rsf@" 
</pre> 

<pre>
bash$ sfspike n1=10 datapath=/tmp/ > /tmp/spike.rsf 
bash$ grep in /tmp/spike.rsf 
in="/tmp/sfspikejcARVf" 
</pre> 

====Packing header and data together====
While the header and data files are separated by default, it is also possible
to pack them together into one file. To do that, specify the program's
"<tt>--out</tt>" parameter as <tt>--out=stdout</tt>. Example:
<pre>
bash$ sfspike n1=10 --out=stdout > spike.rsf
bash$ grep in spike.rsf
Binary file spike.rsf matches
bash$ sfin spike.rsf
spike.rsf:
    in="stdin"
    esize=4 type=float form=native
    n1=10          d1=0.004       o1=0          label1="Time" unit1="s"
        10 elements 40 bytes
bash$ ls -l spike.rsf
-rw-r--r--  1 sergey users 196 2004-11-10 21:39 spike.rsf
</pre>
If you examine the contents of <tt>spike.rsf</tt>, you will find that it
starts with the text header information, followed by special
symbols, followed by binary data. 
Packing headers and data together may not be a good idea for data processing, but it works well for storing data: it is easier to move the packed file
around than to move two different files (header and binary) together while
remembering to preserve their connection. Packing the header and data together is also the current mechanism used to push RSF files through Unix pipes.

===Type===
The data stored with RSF can have different types: character, unsigned
character, integer, floating point, or complex. By default, single precision
is used for numbers (<tt>int</tt> and <tt>float</tt> data types in the C
programming language), but double precision and other
integer types (<tt>short</tt> and <tt>long</tt>) are also
supported. The number of bytes required to represent these
numbers may depend on the platform.
===Form===
The data stored with RSF can also be in different forms: ASCII, native
binary, and XDR binary. Native binary is often used by default. It is the
binary format employed by the machine running the application. On
Linux-running PC, the native binary format will typically correspond to the
so-called little-endian byte ordering. On some other platforms, it might be
big-endian ordering. XDR is a binary format designed by Sun for exchanging
files over the network. It typically corresponds to big-endian byte ordering. It
is more efficient to process RSF files in the native binary format, but storing the corresponding file in an XDR format might be a good idea if you intend to access data from different platforms. RSF also allows for an ASCII
(plain text) form of data files. 
Conversion between different types and forms is accomplished with
<tt>sfdd</tt> program. Here are some examples. First, let us create synthetic data.
<pre>
bash$ sfmath n1=10 output='10*sin(0.5*x1)' > sin.rsf
bash$ sfin sin.rsf
sin.rsf:
    in="/tmp/sin.rsf@"
    esize=4 type=float form=native
    n1=10          d1=1           o1=0
        10 elements 40 bytes
bash$ < sin.rsf sfdisfil
   0:             0        4.794        8.415        9.975        9.093
   5:         5.985        1.411       -3.508       -7.568       -9.775
</pre>
Converting the data to the integer type:
<pre>
bash$ < sin.rsf sfdd type=int > isin.rsf
bash$ sfin isin.rsf
isin.rsf:
    in="/tmp/isin.rsf@"
    esize=4 type=int form=native
    n1=10          d1=1           o1=0
        10 elements 40 bytes
bash$ < isin.rsf sfdisfil
   0:    0    4    8    9    9    5    1   -3   -7   -9
</pre>
Converting the data to the ASCII form:
<pre>
bash$ < sin.rsf sfdd form=ascii > asin.rsf
bash$ < asin.rsf sfdisfil
   0:             0        4.794        8.415        9.975        9.093
   5:         5.985        1.411       -3.508       -7.568       -9.775
bash$ sfin asin.rsf
asin.rsf:
    in="/tmp/asin.rsf@"
    esize=0 type=float form=ascii
    n1=10          d1=1           o1=0
        10 elements
bash$ cat /tmp/asin.rsf@
0 4.79426 8.41471 9.97495 9.09297 5.98472 1.4112 -3.50783
-7.56803 -9.7753
</pre>

===Hypercube===
While RSF stores binary data in a contiguous 1-D array, the conceptual
data model is a multidimensional hypercube. By convention, the
dimensions of the cube are defined with parameters <tt>n1</tt>,
<tt>n2</tt>, <tt>n3</tt>, etc. The fastest axis is <tt>n1</tt>.
Additionally, the grid sampling can be given by parameters
<tt>d1</tt>, <tt>d2</tt>, <tt>d3</tt>, etc. The axes origins are given
by parameters <tt>o1</tt>, <tt>o2</tt>, <tt>o3</tt>, etc. Optionally,
you can also supply the axis label strings: <tt>label1</tt>,
<tt>label2</tt>, <tt>label3</tt>, etc., and axis units strings:
<tt>unit1</tt>, <tt>unit2</tt>, <tt>unit3</tt>, etc.