SUGAIN - apply various types of gain to display traces

sugain <stdin >stdout [optional parameters]

Required parameters:
none (no-op)

Optional parameters:
panel=0 =1 gain whole data set (vs. trace by trace)
tpow=0.0 multiply data by t^tpow
epow=0.0 multiply data by exp(epow*t)
gpow=1.0 take signed gpowth power of scaled data
agc=0 flag; 1 = do automatic gain control
gagc=0 flag; 1 = ... with gaussian taper
wagc=0.5 agc window in seconds (use if agc=1 or gagc=1)
trap=none zero any value whose magnitude exceeds trapval
clip=none clip any value whose magnitude exceeds clipval
qclip=1.0 clip by quantile on absolute values on trace
qbal=0 flag; 1 = balance traces by qclip and scale
pbal=0 flag; 1 = bal traces by dividing by rms value
mbal=0 flag; 1 = bal traces by subtracting the mean
scale=1.0 multiply data by overall scale factor
bias=0.0 bias data by adding an overall bias value
jon=0 flag; 1 means tpow=2, gpow=.5, qclip=.95
verbose=0 verbose = 1 echoes info

tmpdir= if non-empty, use the value as a directory path
prefix for storing temporary files; else if the
the CWP_TMPDIR environment variable is set use
its value for the path; else use tmpfile()

Operation order:

out(t) = scale * BAL{CLIP[AGC{[t^tpow * exp(epow * t) * ( in(t)-bias )]^gpow}]}

Notes:
The jon flag selects the parameter choices discussed in
Claerbout's Imaging the Earth, pp 233-236.

Extremely large/small values may be lost during agc. Windowing
these off and applying a scale in a preliminary pass through
sugain may help.

Sugain only applies gain to traces with tr.mark=0. Use sushw,
suchw, suedit, or suxedit to mark traces you do not want gained.
See the selfdocs of sushw, suchw, suedit, and suxedit for more
information about setting header fields. Use "sukeyword mark
for more information about the mark header field.


Credits:
SEP: Jon Claerbout
CWP: Jack K. Cohen, Brian Sumner, Dave Hale

Note: Have assumed tr.deltr >= 0 in tpow routine.

Technical Reference:
Jon's second book, pages 233-236.

Trace header fields accessed: ns, dt, delrt, mark