Editing
Guide to RSF file format
(section)
Jump to navigation
Jump to search
Warning:
You are not logged in. Your IP address will be publicly visible if you make any edits. If you
log in
or
create an account
, your edits will be attributed to your username, along with other benefits.
Anti-spam check. Do
not
fill this in!
==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 originally 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, common file formats should be in a readable textual form so that they can 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 can be read by humans 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> On your screen, you should see a plot similar to the figure below. [[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 simply copies the contents of the previous file, and the <tt>echo</tt> utility appends 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.
Summary:
Please note that all contributions to Madagascar are considered to be released under the GNU Free Documentation License 1.3 or later (see
My wiki:Copyrights
for details). If you do not want your writing to be edited mercilessly and redistributed at will, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource.
Do not submit copyrighted work without permission!
Cancel
Editing help
(opens in new window)
Navigation menu
Personal tools
English
Not logged in
Talk
Contributions
Create account
Log in
Namespaces
Page
Discussion
English
Views
Read
Edit
View history
More
Search
Getting Madagascar
download
Installation
GitHub repository
SEGTeX
Introduction
Package overview
Tutorial
Hands-on tour
Reproducible documents
Hall of Fame
User Documentation
List of programs
Common programs
Popular programs
The RSF file format
Reproducibility with SCons
Developer documentation
Adding programs
Contributing programs
API demo: clipping data
API demo: explicit finite differences
Community
Conferences
User mailing list
Developer mailing list
GitHub organization
LinkedIn group
Development blog
Twitter
Slack
Tools
What links here
Related changes
Special pages
Page information