Editing Guide to RSF file format (section)

==Compatibility with other file formats==
It is possible to exchange RSF-formatted data with several other popular data formats.
===Compatibility with SEPlib===
RSF is mostly compatible with its predecessor, the SEPlib file format.
However, there are several significant differences:
  
#SEPlib programs typically use the element size (<tt>esize=</tt> parameter) to distinguish between different data types: <tt>esize=4</tt> corresponds to floating point data, while <tt>esize=8</tt> corresponds to complex data. The RSF type handling mechanism is different: data types are determined from the value of the <tt>data_format</tt> parameter. Madagascar computational programs typically output files with <tt>data_format="native_float"</tt> or <tt>native_complex</tt>.
#The default data form in SEPlib programs is typically XDR and not native as it is in RSF. Thus, to make a dataset created with SEPlib readable by Madagascar programs, you would typically need to add to the history file <tt>data_format="xdr_float"</tt> or <tt>data_format="xdr_complex"</tt> . <ref group="note">For SEPlib 6.5.3 and older: Note that xdr_complex is not a valid SEPlib value, so for datasets of complex numbers encoded as pairs of floats, a dataset cannot be at the same time valid in both SEPlib and Madagascar. A valid SEPlib dataset will have esize=8 and data_format="xdr_float", but sfin will show it as having "200% of expected" data. Adding data_format="xdr_complex" to such a dataset will make sfin work as expected, but SEPlib's In or In3d will give a segmentation fault because of an unknown data type. To patch SEPlib to accept <tt>native_complex</tt> and <tt>xdr_complex</tt> data, the following changes must be made:
* In <tt>$SEPSRC/seplib_base/lib/corelibs/sep/strformats.c</tt>:
** Add "xdr_complex" and "native_complex" to the str_fmt_names structure
** Set FMT_LENGTH to 15
* In <tt>$SEPSRC/seplib_base/lib/corelibs/include/strformats.h</tt>:
** Add preprocessor directives to define FMT_XDR_COMPLEX as 8 and FMT_NATIVE_COMPLEX as 9
** Set NUM_FMT to 10
</ref>
#It is possible to pipe the output of Madagascar programs to SEPlib: <pre>bash$ sfspike n1=1 | Attr want=min</pre> (output should be: <tt>minimum value = 1 at 1</tt>). However, piping the output of SEPlib programs to RSF (or, for that matter, any other non-SEPlib programs) will result in an unterminated process. For example, the command <pre> bash$ Spike n1=1 | sfattr want=min </pre> will hang. This is because SEPlib uses sockets for piping and expects a socket connection from the receiving program, while Madagascar passes data through regular Unix pipes. 
#SEP3D is an extension of SEPlib for operating with irregularly sampled data (Biondi et al., 1996<ref>Biondi, B., R. Clapp, and S. Crawley,  1996, SEPlib90: SEPlib for 3-D  prestack data, ''in'' SEP-92,  343--364. Stanford Exploration Project.</ref>). There is no equivalent of it in RSF for the reasons explained at the beginning of this guide. Operations with irregular datasets are supported using auxiliary input files representing the geometry information.

;Notes
<references group="note" />

===Reading and writing SEG-Y and SU files===
The SEG-Y format is based on the proposal of Barry et al. (1975<ref>[http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev0.pdf Barry, K. M., D. A. Cavers, and C. W. Kneale,  1975, Report on recommended standards for digital tape formats: Geophysics, '''40''', 344--352]</ref>).
It was revised in 2002<ref>See http://www.seg.org/SEGportalWEBproject/prod/SEG-Publications/Pub-Technical-Standards/Documents/seg_y_rev1.pdf</ref>. The
SU format is a modification of SEG-Y used in Seismic Unix
(Stockwell, 1997<ref>Stockwell, J. W.,  1997, Free software in education: A case study of  CWP/SU: Seismic Unix: The Leading Edge, '''16''', 1045--1049.</ref>).
To convert files from SEG-Y or SU format to RSF, use the <tt>sfsegyread</tt>
program. Let us first manufacture an example file using SU utilities
(Stockwell, 1999<ref>-------- 1999, The CWP/SU: Seismic Un*x package: Computers and  Geosciences, '''25''', 415--419.</ref>):
<pre>
bash$ suplane > plane.su
bash$ segyhdrs < plane.su | segywrite tape=plane.segy
</pre>
To convert it to RSF, use either
<pre>
bash$ sfsuread < plane.su tfile=tfile.rsf endian=0 > plane.rsf
</pre>
or
<pre>
bash$ sfsegyread < plane.segy tfile=tfile.rsf \
hfile=file.asc bfile=file.bin > plane.rsf
</pre>
The endian flag is needed if the SU file originated from a little-endian machine like a Linux PC.
Several files are generated. The standard output contains an RSF file with the
data (32 traces with 64 samples each):
<pre>
bash$ sfin plane.rsf
plane.rsf:
    in="/tmp/plane.rsf@"
    esize=4 type=float form=native
    n1=64          d1=0.004       o1=0
    n2=32          d2=?           o2=?
        2048 elements 8192 bytes
</pre>
The contents of this file are displayed in the figure.
[[Image:plane.png|frame|center|The output of suplane, converted to RSF and
displayed with <tt>sfwiggle</tt>.]]
The <tt>tfile</tt> is an RSF integer-type file with the trace headers (32
headers with 71 traces each):
<pre>
bash$ sfin tfile.rsf
tfile.rsf:
    in="/tmp/tfile.rsf@"
    esize=4 type=int form=native
    n1=71          d1=?           o1=?
    n2=32          d2=?           o2=?
        2272 elements 9088 bytes
</pre>
The contents of trace headers can be quickly examined with the 
<tt>sfheaderattr</tt> program.
The <tt>file.asc</tt> is the ASCII header file for the whole record.
<pre>
bash$ head -c 242 file.asc
C      This tape was made at the
C                                                                              
C      Center for Wave Phenomena                         
</pre>
The  <tt>file.bin</tt> is the binary header file.

To convert files back from RSF to SEG-Y or SU, use the <tt>sfsegywrite</tt>
program and reverse the input and output:
<pre>
bash$ sfsuwrite > plane.su tfile=tfile.rsf endian=0 < plane.rsf
</pre>
or
<pre>
bash$ sfsegywrite > plane.segy tfile=tfile.rsf \
hfile=file.asc bfile=file.bin < plane.rsf
</pre>

If <tt>hfile=</tt> and <tt>bfile=</tt> are not supplied to <tt>sfsegywrite</tt>, the corresponding headers will be generated on the fly. The trace header file can be generated with <tt>sfsegyheader</tt>. Here is an example:
<pre>
bash$ sfheadermath < plane.rsf output=N+1 | sfdd type=int > tracl.rsf
bash$ sfsegyheader < plane.rsf tracl=tracl.rsf > tfile.rsf
bash$ sfsegywrite  < plane.rsf tfile=tfile.rsf > plane.segy
</pre>

====Unusual trace header keys====
Sometimes, SEG-Y files deviate from the standard by creating additional
trace header keys. If, for example, you find out that the SEG-Y file
contains an additional trace header key stored in bytes 225-226, you can either remap one of the standard two-byte keys
<pre>
bash&#36; sfsegyread < file.segy tfile=tfile.rsf gut=224 > file.rsf
</pre>
or create a new key
<pre>
bash&#36; sfsegyread < file.segy tfile=tfile.rsf \
key1=mykey key1_len=2 mykey=224 > file.rsf
</pre>
Any number of additional keys can be created this way.

===Reading and writing ASCII files===
Reading and writing ASCII files can be accomplished with the <tt>sfdd</tt>
program. For example, let us take an ASCII file with numbers
<pre>
bash$ cat file.asc
1.0 1.5 3.0
4.8 9.1 7.3
</pre>
Converting it to RSF is as simple as
<pre>
bash$ echo in=file.asc n1=3 n2=2 data_format=ascii_float > file.rsf
bash$ sfin file.rsf
file.rsf:
    in="file.asc"
    esize=0 type=float form=ascii
    n1=3           d1=?           o1=?
    n2=2           d2=?           o2=?
        6 elements
</pre>
For more efficient input/output operations, it might be advantageous to
convert the data type to native binary, as follows:
<pre>
bash$ echo in=file.asc n1=3 n2=2 data_format=ascii_float | \
sfdd form=native > file.rsf
bash$ sfin file.rsf
file.rsf:
    in="/tmp/file.rsf@"
    esize=4 type=float form=native
    n1=3           d1=?           o1=?
    n2=2           d2=?           o2=?
        6 elements 24 bytes
</pre>
Converting from RSF to ASCII is equally simple:
<pre>
bash$ sfdd form=ascii --out=file.asc < file.rsf > /dev/null
bash$ cat file.asc
1 1.5 3 4.8 9.1 7.3
</pre>
You can use the <tt>line=</tt> and <tt>format=</tt> parameters in
<tt>sfdd</tt> to control the ASCII formatting:
<pre>
bash$ sfdd form=ascii --out=file.asc \
line=3 format="%3.1f " < file.rsf > /dev/null
bash$ cat file.asc
1.0 1.5 3.0
4.8 9.1 7.3
</pre>
An alternative is to use <tt>sfdisfil</tt>.
<pre>
bash$ sfdisfil > file.asc col=3 format="%3.1f " number=n < file.rsf
bash$ cat file.asc
1.0 1.5 3.0
4.8 9.1 7.3
</pre>

===Reading and writing CSV files===
CSV (Comma-separated values) is a particular example of an ASCII
format, where commas separate values on different rows or
other symbols. To convert from CSV to RSF, you can use the
<tt>sfcsv2rsf</tt> utility.
For example, let us take an ASCII file with numbers separated by commas
<pre>
bash&#36; cat file.csv
1.0,1.5,3.0
4.8,9.1,7.3
</pre>
Converting it to RSF:
<pre>
bash&#36; sfcsv2rsf < file.csv > file.rsf
bash&#36; sfin file.rsf
file.rsf:
    in="/tmp/file.rsf@"
    esize=4 type=float form=native 
    n1=3           d1=1           o1=0          label1="unknown" unit1="unknown" 
    n2=2           d2=1           o2=0          label2="unknown" unit2="unknown" 
	6 elements 24 bytes
</pre>
To convert from RSF to CSV, we can use formatting parameters in <tt>sfdd</tt>:
<pre>
bash&#36; sfdd form=ascii --out=file.csv \
line=3 strip=1 format="%3.1f," < file.rsf >/dev/null
bash&#36; cat file.csv
1.0,1.5,3.0
4.8,9.1,7.3
</pre>
Some CSV files contain headers with definitions for different columns.
<pre>
bash&#36; cat file.csv
height,width,weight
1.0,1.5,3.0
4.8,9.1,7.3
</pre>
To read a file like that, use <tt>header=</tt> parameter in <tt>sfcsv2rsf</tt>, as follows:
<pre>
bash&#36; sfcsv2rsf < file.csv header=y > file.rsf
</pre>
After that, different columns can be accessed by keywords.
<pre>
bash&#36; < file.rsf sfheaderattr segy=n
3 headers, 2 traces
*******************************************************************************
     key                    min                       max                 mean
-------------------------------------------------------------------------------
height      0              1 @ 0                   4.8 @ 1                 2.9
width       1            1.5 @ 0                   9.1 @ 1                 5.3
weight      2              3 @ 0                   7.3 @ 1                5.15
*******************************************************************************
</pre>

===Reading LAS files===
LAS (Log ASCII Standard) is a text format used for storing
well-logging data (Heslop et al., 1999<ref>Heslop, K., J. Karst, S. Prensky, D. Schmitt, et al.,  1999, Log ASCII  standard LAS version 3.0: The Log Analyst, 40.</ref>). LAS files can be converted to the RSF format using
<tt>sflas2rsf</tt> utility.
Let us try an example file from one of the SEG tutorials:
<pre>
bash&#36; tutorials=https://raw.githubusercontent.com/seg/tutorials-2014/master
bash&#36; wget &#36;tutorials/1406_Make_a_synthetic/L-30.las
</pre>
Converting to RSF, we can detect 15 different logs:
<pre>
bash&#36; sflas2rsf L-30.las L-30.rsf
(base) sergey@DESKTOP-80QRDA0:~/all/fomels/nnint&#36; sfin L-30.rsf
L-30.rsf:
    in="/home/sergey/RSFROOT/data/L-30.rsf@"
    esize=4 type=float form=native
    n1=15          d1=?           o1=?
    n2=25621       d2=0.5         o2=1140
        384315 elements 1537260 bytes
</pre>
Individual logs are accessible by their keys and can be used in programs like <tt>sfheadermath</tt>.
<pre>
bash&#36; < L-30.rsf sfheaderattr segy=n desc=y
15 headers, 25621 traces
*******************************************************************************
     key                    min                       max                 mean
-------------------------------------------------------------------------------
DEPTH       0           1140 @ 0                 13950 @ 25620            7545
[Depth]
CALD        1           -999 @ 0                19.811 @ 3909         -140.356
[Caliper Caliper - Density]
CALS        2           -999 @ 0                 14.84 @ 23096         7.43849
[Caliper Caliper - Sonic]
DEPT        3           1140 @ 0                 13950 @ 25620            7545
[Depth]
DRHO        4           -999 @ 0                 0.254 @ 23667         -149.67
[Drho Delta Rho]
DT          5           -999 @ 0               199.263 @ 1462          90.0167
[Sonic Delta-T]
GRD         6           -999 @ 0               178.416 @ 21788        -100.952
[GammaRay Gamma Ray - Density]
GRS         7           -999 @ 0               140.148 @ 23376         53.8002
[GammaRay Gamma Ray - Sonic]
ILD         8           -999 @ 0               2022.95 @ 20            34.5917
[DeepRes Deep Induction Standard Processed Resistivity]
ILM         9           -999 @ 0               2196.26 @ 20661         40.5595
[MedRes Medium Induction Standard Processed Resistivity]
LL8        10           -999 @ 0               2097.76 @ 20213         35.6343
[ShalRes Latero-Log 8]
NPHILS     11           -999 @ 0                  0.45 @ 23039        -776.522
[Neutron Neutron Porosity - Ls Mtx]
NPHISS     12           -999 @ 0                 0.615 @ 5215         -373.244
[Neutron Neutron Porosity - Ss Mtx]
RHOB       13           -999 @ 0                 2.811 @ 23941        -147.773
[Density Bulk Density]
SP         14           -999 @ 0               -19.065 @ 20570        -105.029
[SP Spontaneous Potential]
*******************************************************************************
bash&#36; < L-30.rsf sfheadermath output=RHOB segy=n > RHOB.rsf
bash&#36; < RHOB.rsf sfwindow min2=4000 max2=13000 | sfgraph title=Density
</pre>

[[Image:rhob.png|frame|center|Density log.]]