ssh1d
ssh1d generates a statistically defined one-dimensional fractional
perturbation field or applies it multiplicatively to selected model fields
in multiparameter one-dimensional tables or NetCDF series. The perturbation
field can be tapered using similar functionality as in merge1d.
Synopsis
gmt ssh1d [-A model] -Tmin/max/inc -Dstddev [statistics] -Goutput
Behavior
The default model is von Karman, which is the noted preference for
geophysical applications. Gaussian, exponential, and uncorrelated white
noise are also available. -D is the fractional standard deviation, -C
is the correlation length, and -U is the Hurst exponent, which is required
for the von Karman model. The generated realization is adjusted to zero mean
and the requested sample standard deviation before tapering. Spectral padding
is one correlation length by default and may be changed or disabled with -Q.
Without -A, -T defines a regular output axis and -F names one or
more heterogeneity fields. Text and NetCDF output are supported. With -A,
the input may be a regular text table whose first column is the coordinate, or
a NetCDF file. -F must name all selected data fields, and each finite model
value is changed according to
Input +x and +v transforms are applied before generation and
application. Their uppercase forms set target-unit metadata. Input scaling
does not reorder samples, and the transformed coordinate must be regular and
increasing. In application mode, -T resamples within the transformed input
domain using the method selected by -S. The +g modifier bridges
internal missing runs, optionally up to a maximum gap measured in transformed
coordinate units. Without +g, separate valid runs are interpolated
independently and gaps remain missing.
-Z scales the output coordinate and selected fields after application and
may set final unit metadata. It also does not reorder samples, so a negative
output axis scale can restore a descending coordinate convention. Missing
values remain NaN, and valid values are not clipped.
-L restricts the support to an interval. -W applies any BLEND window
inside it, with independent beginning and ending taper ratios. Tapering occurs
after statistical normalization, so the localized field is not renormalized.
The +w modifier adds the shared taper as weight in NetCDF output or as
the final column of text output. Its NetCDF long_name is
heterogeneity taper weight and its units are 1.
Usage
gmt ssh1d [gq] 6.5.0 [64-bit] - Generate or apply one-dimensional small-scale heterogeneities in
tables and multiparameter NetCDF series
usage: gmt ssh1d [<model.txt|model.nc>[+x<sx>][+X<unit>][+v<scales>][+V<units>][+n<missing>]] [-A]
-G<output> [-F<fields>] -D[<field>/]<sigma> [-C[<field>/]<length>] [-U[<field>/]<hurst>]
[-L<lo>/<hi>] [-M<v|g|e|w>] [-Q<seed>[+i][+n|+p<factor>]] [-T<min>/<max>/<inc>] [-S<a|c|e|l|n|⏎
…s<p>>[+g[<maxgap>]]] [-W[<window>][+r<r1/r2>][+w]] [-Z[+x<sx>][+X<unit>][+v<scales>][+V<units>]]
[-V[q|e|w|t|i|c|d]] [-di<nodata>[+c<col>]]
REQUIRED ARGUMENTS:
-G<output>
Write the output. In synthetic mode, .nc, .nc4, and .cdf file extensions select NetCDF. Any
other name, including -, writes a text table. Application mode preserves the input format: a
text model produces a text table and a NetCDF model produces NetCDF.
-D[<field>/]<sigma>
Set the shared or field-specific fractional standard deviation. Sigma must be greater than
zero and is expressed as a fraction of the model value rather than in percent. Every output
field needs either a shared value or a field-specific value. For example, -D0.05 gives every
field a standard deviation of 5 percent. Repeat -D with a field name to override the shared
value. -D0.05 -Dvp/0.03 -Dvs/0.08 uses 3 percent for vp, 8 percent for vs, and 5 percent for
every other selected field.
OPTIONAL ARGUMENTS:
-A
Apply the generated heterogeneity to one input model as model*(1+epsilon). Missing model
values remain missing. Without -A, write the heterogeneity field itself. Application mode
requires one input model and -F.
<model.txt|model.nc>[+x<sx>][+X<unit>][+v<scales>][+V<units>][+n<missing>]
Supply one text or NetCDF model in application mode. A text table's first column is the
coordinate and all remaining columns are model fields. NetCDF variables selected by -F must
share one coordinate. NetCDF packing and missing-value metadata are decoded first. Use +n to
identify an additional input missing-value sentinel, +x to scale the coordinate, +X to set its
working unit, +v to scale selected fields, and +V to set their working units. One +v or +V
entry is broadcast. Otherwise entries follow -F order. Scaling does not reorder coordinates or
data. The transformed coordinate must be regular and increasing. For example,
model.nc+x0.001+Xkm+v0.001,0.001+Vkm/s,km/s converts the coordinate from m to km and vp and vs
from m/s to km/s when used with -Fvp,vs.
-C[<field>/]<length>
Set the shared or field-specific correlation length in transformed coordinate units. Length
must be greater than zero and is required for von Karman, Gaussian, and exponential models.
White noise does not use a correlation length. For example, -C10 uses a length of 10 for every
field, while -C10 -Cvs/5 uses 5 for vs and 10 for the remaining fields.
-F<field1,field2,...>
Set field names and their order. In synthetic mode, omitting -F creates one field named
heterogeneity. -Fvp,vs creates NetCDF variables vp_heterogeneity and vs_heterogeneity. In
application mode, -F is required. Its entries select exact NetCDF variable names, or name
every text data column in column order. For example, a text table containing x, vp, vs, and
rho uses -Fvp,vs,rho. Field-specific -D, -C, and -U options and +v, +V, and output -Z value
lists use this same order and these same names.
-U[<field>/]<hurst>
Set the shared or field-specific Hurst exponent for the von Karman model. The value must be
greater than zero and less than one. The default exponent is 0.15. Gaussian, exponential, and
white models do not use this option. For example, -U0.3 applies 0.3 to every field, while
-U0.3 -Uvs/0.7 uses 0.7 for vs.
-L<lo>/<hi>
Restrict the taper support to an interval in transformed coordinate units. The interval must
lie inside the working domain and lo must be less than hi. Without -L, -W tapers over the
complete domain. For example, -L20/80 limits the heterogeneity to that interval.
-M<v|g|e|w>
Select the statistical model: von Karman (v), Gaussian (g), exponential (e), or white noise
(w). Von Karman is the default. White noise does not require -C, and only von Karman uses -U.
For example, -Mg selects the Gaussian model.
-Q<seed>[+i][+n|+p<factor>]
Control random-number generation and spectral padding. The default seed is 1, and multiple
fields use the same underlying realization. Append +i to derive an independent realization for
each field. The default padding is one maximum correlation length at each edge. +n disables
padding and +p<factor> changes that multiple. For example, -Q42+i+p2 uses seed 42, independent
fields, and padding of two correlation lengths.
-T<min>/<max>/<inc>
Set a regular increasing working axis with min < max and inc > 0. Synthetic mode requires -T.
In application mode, -T optionally subsets or resamples within the transformed input domain.
Otherwise the transformed input axis is unchanged. Option -S controls the interpolation. For
example, -T0/100/0.1 creates 1001 nodes.
-S<a|c|e|l|n|s<p>>[+g[<maxgap>]]
Choose Akima (a), cubic spline (c), step-up (e), linear (l), nearest-neighbor (n), or
smoothing spline (s<p>) interpolation with a non-negative fit parameter p. Linear
interpolation is the default. Interpolation remains within contiguous non-missing runs. Append
+g to bridge internal missing runs, optionally only when the gap does not exceed maxgap in
transformed coordinate units. Values are not extrapolated beyond data domain. Use -Sl+g to
fill every internal gap linearly, or -Sc+g5 to use a cubic spline only across gaps whose
brackets are at most 5 units apart. In application mode, -S requires -T unless +g is used.
-W[<window>][+r<r1/r2>][+w]
Taper the heterogeneity within the -L interval or, when -L is not given, the complete working
domain. The default window is cosine. The default beginning and ending taper ratios are both
0.2. A taper ratio is the fraction of the support length occupied by the transition at that
edge. It must be at least 0 and less than 0.5, and 0 disables that edge taper. One +r value
applies to both edges. r1/r2 sets them independently. Append +w to add the taper weight as a
final text column or as the NetCDF variable weight. For example, -Wcosine+r0/0.3 uses no
beginning taper and a 0.3 ending taper.
-Z[+x<sx>][+X<unit>][+v<scales>][+V<units>]
Transform output coordinates and values after generation or application. +x scales the output
coordinate, +X sets its unit, +v supplies one broadcast value scale or one scale per -F
field, and +V sets their units. Scaling occurs in place and does not reorder samples. A
negative +x therefore produces a decreasing output axis. For example, -Z+x-1000+Xm+v1000,⏎
…1000+Vm/s,m/s converts an increasing positive-down axis in km to a decreasing positive-up axis
in m and scales two selected velocity fields to m/s without reordering.
Processing order:
Input missing-value and NetCDF packing conversion. Input coordinate and field scaling. Regular
increasing-axis validation. -T/-S resampling or gap bridging. Heterogeneity generation. BLEND
tapering. optional model application. Then -Z output transformation. Unresolved missing values
are written as NaN.
-V[q|e|w|t|i|c|d]
Change the verbosity level (currently w). Choose among 7 levels; each level adds more detailed
messages:
q: Quiet, not even fatal error messages.
e: Error messages only.
w: Warnings [Default when no -V is given].
t: Timings (time-intensive operations only).
i: Informational messages (or just -V with no level appended).
c: Compatibility warnings.
d: Debugging messages.
-di<nodata>[+c<col>] Replace any <nodata> values in input data with NaN.
+c Append first column to be affected [2].
-^ (or -) Print short synopsis message.
-+ (or +) Print longer synopsis message.
-? (or no arguments) Print this usage message.
--PAR=<value> Temporarily override GMT default setting(s) (repeatable).
(See gmt.conf documentation for GMT default parameters).
Examples
See ssh1d examples.