Documentation:system/main

Let us improve self-documentation of Madagascar programs!

Listed below are selfdocs for programs in system/main (generated with sfdoc). Please edit the descriptions to make them more complete and/or easier to understand.

sfadd

Add, multiply, or divide RSF datasets.
sfadd > out.rsf scale= add= sqrt= abs= log= exp= mode= [< file0.rsf] file1.rsf file2.rsf ...
The various operations, if selected, occur in the following order: (1) Take absolute value, abs= (2) Add a scalar, add= (3) Take the natural logarithm, log= (4) Take the square root, sqrt= (5) Multiply by a scalar, scale= (6) Compute the base-e exponential, exp= (7) Add, multiply, or divide the data sets, mode= sfadd operates on integer, float, or complex data, but all the input and output files must be of the same data type. An alternative to sfadd is sfmath, which is more versatile, but may be less efficient.
bools	abs=		If true take absolute value [nin]
floats	add=		Scalar values to add to each dataset [nin]
bools	exp=		If true compute exponential [nin]
bools	log=		If true take logarithm [nin]
string	mode=		'a' means add (default), 'p' or 'm' means multiply, 'd' means divide
floats	scale=		Scalar values to multiply each dataset with [nin]
bools	sqrt=		If true take square root [nin]

sfattr

Display dataset attributes.
sfattr < in.rsf lval=2 want=
Sample output from "sfspike n1=100 | sfbandpass fhi=60 | sfattr" ******************************************* rms = 0.992354 mean = 0.987576 2-norm = 9.92354 variance = 0.00955481 std dev = 0.0977487 max = 1.12735 at 97 min = 0.151392 at 100 nonzero samples = 100 total samples = 100 ******************************************* rms = sqrt[ sum(data^2) / n ] mean = sum(data) / n norm = sum(abs(data)^lval)^(1/lval) variance = [ sum(data^2) - n*mean^2 ] / [ n-1 ] standard deviation = sqrt [ variance ]
int	lval=2		norm option, lval is a non-negative integer, computes the vector lval-norm
string	want=		'all'(default), 'rms', 'mean', 'norm', 'var', 'std', 'max', 'min', 'nonzero', 'samples', 'short' want= 'rms' displays the root mean square want= 'norm' displays the square norm, otherwise specified by lval. want= 'var' displays the variance want= 'std' displays the standard deviation want= 'nonzero' displays number of nonzero samples want= 'samples' displays total number of samples want= 'short' displays a short one-line version

sfcat

Concatenate datasets.
sfcat > out.rsf order= space= axis=3 nspace=(int) (ni/(20*nin) + 1) o= d= [<file0.rsf] file1.rsf file2.rsf ...
sfmerge inserts additional space between merged data.
int	axis=3		Axis being merged
float	d=		axis sampling
int	nspace=(int) (ni/(20*nin) + 1)		if space=y, number of traces to insert
float	o=		axis origin
ints	order=		concatenation order [nin]
bool	space=	[y/n]	Insert additional space. y is default for sfmerge, n is default for sfcat

sfcconjgrad

Generic conjugate-gradient solver for linear inversion with complex data
sfcconjgrad < dat.rsf mod=mod.rsf > to.rsf < from.rsf > out.rsf niter=1
file	mod=		auxiliary input file name
int	niter=1		number of iterations

sfcdottest

Generic dot-product test for complex linear operators with adjoints
sfcdottest mod=mod.rsf dat=dat.rsf > pip.rsf
file	dat=		auxiliary input file name
file	mod=		auxiliary input file name

sfcmplx

Create a complex dataset from its real and imaginary parts.
sfcmplx < real.rsf > cmplx.rsf real.rsf imag.rsf
There has to be only two input files specified and no additional parameters.

sfconjgrad

Generic conjugate-gradient solver for linear inversion
sfconjgrad < dat.rsf mod=mod.rsf > to.rsf < from.rsf > out.rsf niter=1
file	mod=		auxiliary input file name
int	niter=1		number of iterations

sfcp

Copy or move a dataset.
sfcp < in.rsf > out.rsf in.rsf out.rsf
sfcp - copy, sfmv - move. Mimics standard Unix commands.

sfcut

Zero a portion of the dataset.
sfcut < in.rsf > out.rsf verb=n j#=(1,...) d#=(d1,d2,...) f#=(0,...) min#=(o1,o2,,...) n#=(0,...) max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)
Reverse of window.
float	d#=(d1,d2,...)		sampling in #-th dimension
largeint	f#=(0,...)		window start in #-th dimension
int	j#=(1,...)		jump in #-th dimension
float	max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)		maximum in #-th dimension
float	min#=(o1,o2,,...)		minimum in #-th dimension
int	n#=(0,...)		window size in #-th dimension
bool	verb=n	[y/n]	Verbosity flag

sfdd

Convert between different formats.
sfdd < in.rsf > out.rsf trunc=n line=8 ibm=n form= type= format=
string	form=		ascii, native, xdr
string	format=		Element format (for conversion to ASCII)
bool	ibm=n	[y/n]	Special case - assume integers actually represent IBM floats
int	line=8		Number of numbers per line (for conversion to ASCII)
bool	trunc=n	[y/n]	Truncate or round to nearest when converting from float to int/short
string	type=		int, float, complex, short

sfdisfil

Print out data values.
sfdisfil < in.rsf number=y col=0 format= header= trailer=
Alternatively, use sfdd and convert to ASCII form.
int	col=0		Number of columns. The default depends on the data type: 10 for int and char, 5 for float, 3 for complex
string	format=		Format for numbers (printf-style). The default depends on the data type: "%4d " for int and char, "%13.4g" for float, "%10.4g,%10.4gi" for complex
string	header=		Optional header string to output before data
bool	number=y	[y/n]	If number the elements
string	trailer=		Optional trailer string to output after data

sfdottest

Generic dot-product test for linear operators with adjoints
sfdottest mod=mod.rsf dat=dat.rsf > pip.rsf
file	dat=		auxiliary input file name
file	mod=		auxiliary input file name

sfget

Output parameters from the header.
sfget parform=y all=n par1 par2 ...
bool	all=n	[y/n]	If output all values.
bool	parform=y	[y/n]	If y, print out parameter=value. If n, print out value.

sfheadercut

Zero a portion of a dataset based on a header mask.
sfheadercut mask=head.rsf < in.rsf > out.rsf
The input data is a collection of traces n1xn2, mask is an integer array of size n2.
file	mask=		auxiliary input file name

sfheadersort

Sort a dataset according to a header key.
sfheadersort < in.rsf > out.rsf head=
string	head=		header file

sfheaderwindow

Window a dataset based on a header mask.
sfheaderwindow mask=head.rsf < in.rsf > out.rsf
The input data is a collection of traces n1xn2, mask is an integer array os size n2, windowed is n1xm2, where m2 is the number of nonzero elements in mask.
file	mask=		auxiliary input file name

sfin

Display basic information about RSF files.
sfin info=y check=2. trail=y [<file0.rsf] file1.rsf file2.rsf ...
n1,n2,... are data dimensions o1,o2,... are axis origins d1,d2,... are axis sampling intervals label1,label2,... are axis labels unit1,unit2,... are axis units
float	check=2.		Portion of the data (in Mb) to check for zero values.
bool	info=y	[y/n]	If n, only display the name of the data file.
bool	trail=y	[y/n]	If n, skip trailing dimensions of one

sfinterleave

Combine several datasets by interleaving.
sfinterleave > out.rsf axis=3 [< file0.rsf] file1.rsf file2.rsf ...
int	axis=3		Axis for interleaving

sfmask

Create a mask.
sfmask < in.rsf > out.rsf min= max= min= max=
Mask is an integer data with ones and zeros. Ones correspond to input values between min and max. The output can be used with sfheaderwindow.
int	max=		maximum header value
int	min=		minimum header value

sfmath

Mathematical operations on data files.
sfmath > out.rsf n#= d#=(1,1,...) o#=(0,0,...) label#= unit#= type= label= unit= output=
Known functions: cos, sin, tan, acos, asin, atan, cosh, sinh, tanh, acosh, asinh, atanh, exp, log, sqrt, abs, erf, erfc (for float data), arg, conj, real, imag (for complex data). sfmath will work on float or complex data, but all the input and output files must be of the same data type. An alternative to sfmath is sfadd, which may be more efficient, but is less versatile. Examples: sfmath x=file1.rsf y=file2.rsf power=file3.rsf output='sin((x+2*y)^power)' > out.rsf sfmath < file1.rsf tau=file2.rsf output='exp(tau*input)' > out.rsf sfmath n1=100 type=complex output="exp(I*x1)" > out.rsf Arguments which are not treated as variables in mathematical expressions: datapath=, type=, out= See also: sfheadermath.
float	d#=(1,1,...)		sampling on #-th axis
string	label=		data label
string	label#=		label on #-th axis
largeint	n#=		size of #-th axis
float	o#=(0,0,...)		origin on #-th axis
string	output=		Mathematical description of the output
string	type=		output data type [float,complex]
string	unit=		data unit
string	unit#=		unit on #-th axis

sfmpi

MPI wrapper for embarassingly parallel jobs.
sfmpi input=inp.rsf output=out.rsf split=ndim join=axis
string	input=		auxiliary input file name
int	join=axis		axis to join
file	output=		auxiliary output file name
int	split=ndim		axis to split

sfomp

OpenMP wrapper for embarassingly parallel jobs.
sfomp < inp.rsf > out.rsf split=ndim join=axis
int	join=axis		axis to join
int	split=ndim		axis to split

sfpad

Pad a dataset with zeros.
sfpad < in.rsf > out.rsf beg#=0 end#=0 n#=
n#out is equivalent to n#, both of them overwrite end#.
int	beg#=0		the number of zeros to add before the beginning of #-th axis
int	end#=0		the number of zeros to add after the end of #-th axis
int	n#=		the output length of #-th axis - padding at the end

sfput

Input parameters into a header.
sfput < in.rsf > out.rsf [parameter=value list]

sfreal

Extract real (sfreal) or imaginary (sfimag) part of a complex dataset.
sfreal < cmplx.rsf > real.rsf

sfreverse

Reverse one or more axes in the data hypercube.
sfreverse < in.rsf > out.rsf which=-1 verb=n memsize=sf_memsize() opt=
int	memsize=sf_memsize()		Max amount of RAM (in Mb) to be used
string	opt=		If y, change o and d parameters on the reversed axis; if i, don't change o and d
bool	verb=n	[y/n]	Verbosity flag
int	which=-1		Which axis to reverse. To reverse a given axis, start with 0, add 1 to number to reverse n1 dimension, add 2 to number to reverse n2 dimension, add 4 to number to reverse n3 dimension, etc. Thus, which=7 would reverse the first three dimensions, which=5 just n1 and n3, etc. which=0 will just pass the input on through unchanged.

sfrm

Remove RSF files together with their data.
sfrm file1.rsf [file2.rsf ...] [-i] [-v] [-f]
Mimics the standard Unix rm command. See also: sfmv, sfcp.

sfrotate

Rotate a portion of one or more axes in the data hypercube.
sfrotate < in.rsf > out.rsf verb=n memsize=sf_memsize() rot#=(0,0,...)
int	memsize=sf_memsize()		Max amount of RAM (in Mb) to be used
int	rot#=(0,0,...)		length of #-th axis that is moved to the end
bool	verb=n	[y/n]	Verbosity flag

sfrtoc

Convert real data to complex (by adding zero imaginary part).
sfrtoc < real.rsf > cmplx.rsf pair=n
See also: sfcmplx
bool	pair=n	[y/n]	y - use odd elements for real part and even ones for imaginary part

sfscale

Scale data.
sfscale < in.rsf > out.rsf axis=0 rscale=0. dscale=1.
To scale by a constant factor, you can also use sfmath.
int	axis=0		Scale by maximum in the dimensions up to this axis.
float	dscale=1.		Scale by this factor (works if rscale=0)
float	rscale=0.		Scale by this factor.

sfspike

Generate simple data: spikes, boxes, planes, constants.
sfspike < in.rsf > spike.rsf mag= nsp=1 k#=[0,...] l#=[k1,k2,...] p#=[0,...] n#= o#=[0,0,...] d#=[0.004,0.1,0.1,...] label#=[Time,Distance,Distance,...] unit#=[s,km,km,...] title=
Spike positioning is given in samples and starts with 1.
float	d#=[0.004,0.1,0.1,...]		sampling on #-th axis
ints	k#=[0,...]		spike starting position [nsp]
ints	l#=[k1,k2,...]		spike ending position [nsp]
string	label#=[Time,Distance,Distance,...]		label on #-th axis
floats	mag=		spike magnitudes [nsp]
int	n#=		size of #-th axis
int	nsp=1		Number of spikes
float	o#=[0,0,...]		origin on #-th axis
floats	p#=[0,...]		spike inclination (in samples) [nsp]
string	title=		title for plots
string	unit#=[s,km,km,...]		unit on #-th axis

sfspray

Extend a dataset by duplicating in the specified axis dimension.
sfspray < in.rsf > out.rsf axis=2 n= d= o= label= unit=
This operation is adjoint to sfstack.
int	axis=2		which axis to spray
float	d=		Sampling of the newly created dimension
string	label=		Label of the newly created dimension
int	n=		Size of the newly created dimension
float	o=		Origin of the newly created dimension
string	unit=		Units of the newly created dimension

sfstack

Stack a dataset over one of the dimensions.
sfstack < in.rsf > out.rsf scale= axis=2 rms=n norm=y min=n max=n prod=n
This operation is adjoint to sfspray.
int	axis=2		which axis to stack
bool	max=n	[y/n]	If y, find maximum instead of stack. Ignores rms and norm.
bool	min=n	[y/n]	If y, find minimum instead of stack. Ignores rms and norm.
bool	norm=y	[y/n]	If y, normalize by fold.
bool	prod=n	[y/n]	If y, find product instead of stack. Ignores rms and norm.
bool	rms=n	[y/n]	If y, compute the root-mean-square instead of stack.
floats	scale=		optionally scale before stacking [n2]

sftransp

Transpose two axes in a dataset.
sftransp < in.rsf > out.rsf memsize=sf_memsize() plane=
If you get a "Cannot allocate memory" error, give the program a memsize=1 command-line parameter to force out-of-core operation.
int	memsize=sf_memsize()		Max amount of RAM (in Mb) to be used
int	plane=		Two-digit number with axes to transpose. The default is 12

sfwindow

Window a portion of a dataset.
sfwindow < in.rsf > out.rsf verb=n squeeze=y j#=(1,...) d#=(d1,d2,...) f#=(0,...) min#=(o1,o2,,...) n#=(0,...) max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)
float	d#=(d1,d2,...)		sampling in #-th dimension
largeint	f#=(0,...)		window start in #-th dimension
int	j#=(1,...)		jump in #-th dimension
float	max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)		maximum in #-th dimension
float	min#=(o1,o2,,...)		minimum in #-th dimension
largeint	n#=(0,...)		window size in #-th dimension
bool	squeeze=y	[y/n]	if y, squeeze dimensions equal to 1 to the end
bool	verb=n	[y/n]	Verbosity flag