elygtl
elygtl applies the Ely geotechnical layering method to dry columns of a
three-dimensional multiparamter NetCDF model using a Vs30 grid and either a
constant or spatially variable transition depth. This is one of the modules
that applies specifically to seismic wavespeed model parameters.
Synopsis
gmt elygtl model.nc vs30.nc -Goutput.nc -Fvs=vs [options]
Behavior
-F maps existing Vp, Vs, and optional density variables. At least Vp or Vs
is required. -C may create a property that is absent from the source:
Brocher relationships convert between Vp and Vs, and density is obtained from
final Vp with the Nafe-Drake relationship. Newly created properties are inferred
throughout the eligible solid model, not only inside the GTL. Existing
properties are otherwise retained outside the GTL.
For normalized depth q from the local surface to the transition depth,
the Ely profile uses
and combines the transition-depth value with the Vs30-derived surface value:
The local surface is the shallowest finite value in the available Vp or Vs
field. The transition thickness is 350 m by default and may be replaced by a
positive constant or a spatially variable grid with -E. The anchor is
sampled with the vertical interpolation selected by -S, so the GTL meets
the original model there. -T may replace the model z lattice, and the
+g modifier of -S bridges internal missing layers when requested.
Calculations use metres, seconds, m/s, and kg/m3 internally. Lowercase source
modifiers first transform stored coordinates and properties. -U then
converts velocities and density to SI and applies the inverse conversion on
output. After input scaling, x, y, and z must be strictly increasing and z must
be positive down. Scaling does not reorder layers or data. -Z independently
scales output coordinates and properties after the Ely calculation, making it
possible to restore a preferred positive-up or positive-down convention without
changing the data layering order.
-H fills strictly internal holes in native horizontal layers before
resampling. -R must lie within the transformed model domain, and -I may
resample mapped properties, Vs30, transition thickness, and the wet mask
horizontally. Common option -n controls this horizontal interpolation.
-T defines an increasing positive-down output z lattice, while -S
controls vertical interpolation and optional internal-gap bridging. None of
these operations extrapolates beyond the model footprint.
Wet columns are identified using the same GSHHG hierarchy or user-mask scheme
as in topobath. -Mg gives GMT shoreline classification priority, -Mm
gives selected model evidence priority, and -Ml or -Mw classifies the
complete domain as land or wet. A -K mask is authoritative. The
+e<vs30|vp|vs|rho> modifier selects the model evidence. Vs30 is the default.
For a mapped cube property, a shallowest finite sample above sea level indicates
land and one below sea level indicates wet. At sea level, +w supplies the
water value and +t its matching tolerance. Model Vs defaults to zero in
water, while Vp and density require an explicit water value. These values use
transformed model units before -U conversion.
Unselected compatible variables, coordinates, and metadata are copied to the
output. When -R, -I, or -T changes a coordinate lattice, unselected
variables that depend on a changed coordinate are omitted while compatible
variables and scalar metadata are retained in the NetCDF file.
Usage
gmt elygtl [gq] 6.5.0 [64-bit] - Apply Ely geotechnical layering to three-dimensional
multiparameter NetCDF cubes
usage: gmt elygtl <model.nc>[+n<missing>][+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+z<sz>][+Z<unit>]⏎
…[+v<scales>][+V<units>] <vs30_grid>[?field][+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+v<scale>]⏎
…[+V<unit>] -G<output.nc> -Fvp=<name>,vs=<name>[,rho=<name>] [-Cvp=<name>,vs=<name>,rho=<name>]
[-H[n|l|a|s|m[<arg>]][+m<maxgap>]] [-E<depth>|<grid>[?field][+x<sx>][+X<unit>][+y<sy>][+Y<unit>]⏎
…[+v<scale>][+V<unit>]] [-Mg|m|l|w[+e<vs30|vp|vs|rho>][+w<value>][+t<tolerance>]] [-Sa|c|e|l|n|⏎
…s<p>[+g[<maxgap>]]] [-T<zmin>/<zmax>/<dz>] [-U<velocity_scale>[/<density_scale>]]
[-Z+x<sx>+X<unit>+y<sy>+Y<unit>+z<sz>+Z<unit>+v<scales>+V<units>] [-A<min_area>[/<min_level>/⏎
…<max_level>]] [-D<a|f|h|i|l|c|n>] [-K<landmask>] [-R<west>/<east>/<south>/<north>[+r]] [-I<dx>[/⏎
…<dy>]] [-V[q|e|w|t|i|c|d]] [-di<nodata>[+c<col>]] [-n[b|c|l|n][+a][+b<BC>][+c][+t<threshold>]]
REQUIRED ARGUMENTS:
<model.nc>[+n<missing>][+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+z<sz>][+Z<unit>][+v<scales>]⏎
…[+V<units>]
Read the 3-D NetCDF model. NetCDF scale_factor and add_offset are applied first, followed by
the lowercase modifiers. All transformed x, y, and z coordinates must be strictly increasing.
The working z axis must be positive down and expressed in metres for the Ely calculation.
Scaling changes coordinate values in place and does not reorder model layers or data. For
example, +z-1 converts a stored positive-up axis of 4000 ... -16000 m to an increasing
positive-down axis of -4000 ... 16000 m. For an axis stored in kilometres, use +z-1000 to
obtain the same working axis in metres. +v/+V follow active -F properties in vp,vs,rho order.
Use +n for an additional missing-value sentinel.
<vs30_grid>[?field][+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+v<scale>][+V<unit>]
Supply Vs30. Coordinate and value transforms are applied before sampling it onto the working
model lattice. Vs30 must be in m/s when the Ely equations are evaluated. Legacy +s<scale>
remains an alias for +v<scale>.
-G<output.nc>
Write the transformed model. Unselected variables are preserved when their dimensions remain
compatible. If -R, -I, or -T changes a coordinate lattice, unselected variables that depend on
a changed coordinate are omitted because elygtl does not resample them.
-Fvp=<name>,vs=<name>[,rho=<name>]
Map existing model variables. At least vp or vs is required. The three names are semantic
roles, not required NetCDF variable names. For example, -Fvp=Vp,vs=Vs,rho=Density maps the
NetCDF variables Vp, Vs, and Density to the P-wave velocity, S-wave velocity, and density
roles used by elygtl.
OPTIONAL ARGUMENTS:
-R<west>/<east>/<south>/<north>[+r]
Specify the min/max coordinates of your data region in user units. Use dd:mm[:ss] for regions
given in arc degrees, minutes [and seconds]. Use -R<xmin>/<xmax>/<ymin>/<ymax>[+u<unit>] for
regions given in projected coordinates, with <unit> selected from e|f|k|M|n|u [Default: e]. If
+u is set, projected regions centered on (0,0) may be set via -R<halfwidth>[/⏎
…<halfheight>]+u<unit>, where <halfheight> defaults to <halfwidth> if not given. Use
[yyyy[-mm[-dd]]]T[hh[:mm[:ss[.xxx]]]] format for time axes. Append +r if -R specifies the
coordinates of the lower left and upper right corners of a rectangular area.
Alternatively, use -R<code><x0>/<y0>/<n_columns>/<n_rows> for origin and grid dimensions,
where <code> is a 2-char combo from [T|M|B][L|C|R] (top/middle/bottom/left/center/right) and
grid spacing must be specified via -I<dx>[/<dy>] (also see -r).
Set an output horizontal region contained within the transformed model domain. The complete
transformed model region is used when -R is omitted. Input scaling precedes region selection.
-I<dx>[/<dy>]
Set output horizontal increments. The model increments are retained when -I is omitted. Mapped
model properties, Vs30, transition thickness, and the wet mask are sampled onto this lattice.
Common option -n selects the GMT horizontal interpolation used for mapped model layers and
ancillary grids. Input scaling and -H precede -R/-I.
-Cvp=<name>,vs=<name>,rho=<name>
Create entirely missing properties under the requested names. Vp and Vs use Brocher relations
outside the GTL. Density uses the Nafe-Drake relation from final Vp. Empirical creation occurs
after input interpolation and before output -Z scaling. For example, -Fvs=Vs -Cvp=Vp,⏎
…rho=Density creates Vp and Density from an existing Vs variable, while -Fvp=Vp -Cvs=Vs creates
Vs from an existing Vp variable.
-A<min_area>[/<min_level>/<max_level>][+a<antarctica>][+l|r][+p<percent>]
Select GSHHG features used by automatic wet/land classification. The default is 0/0/1, which
treats oceans as wet and land as dry while ignoring lakes and smaller water bodies. Levels are
0 ocean, 1 land, 2 lake, 3 island in lake, and 4 pond. GMT's +a, +l, +r, and +p modifiers
follow grdlandmask.
-D<a|f|h|i|l|c|n>
Set the GMT shoreline resolution used by -Mg or as the prior for -Mm. The default is low
resolution (l). Use n to disable shoreline classification. This option has no effect for
Cartesian models, -K, -Ml, or -Mw.
-E<depth>|<grid>[?field][+x<sx>][+X<unit>][+y<sy>][+Y<unit>][+v<scale>][+V<unit>]
Set the positive transition thickness below the local model surface, either as a constant or
spatially variable grid. The default is 350 m. The local surface is the shallowest finite
layer among the mapped properties, and the transition base is surface + thickness on the
positive-down axis. Grid transforms precede sampling. Legacy +s is an alias for +v on a
transition grid. For example, -E500 uses a 500 m thickness everywhere, while
-Etransition.nc?depth+v1000 reads a thickness grid stored in kilometres.
-H[n|l|a|s|m[<arg>]][+m<maxgap>]
Fill strictly internal horizontal missing-data holes in every native x-y model layer before
horizontal resampling and Ely GTL. Original finite nodes and boundary-connected missing
regions are preserved. Without -H, native horizontal holes are not filled. Use linear Delaunay
interpolation when -H is given without a method. Available methods are:
Nearest neighbor (n). Optionally append a search radius in grid nodes.
Linear Delaunay interpolation (l). This is the default.
Local weighted average (a). Optionally append radius[/sectors] in grid nodes. The default is
3/4.
Spline interpolation (s). Optionally append tension from 0 through 1. The default is 0.
Minimum-curvature interpolation (m). Optionally append tension from 0 through 1. The default
is 0.
+m fills only holes whose x and y spans are no larger than <maxgap> grid nodes. By default,
every strictly internal hole is eligible.
-K<landmask>[?field][+x<sx>][+X<unit>][+y<sy>][+Y<unit>]
Supply an authoritative mask with wet=0 and land=1. It replaces GMT and model classification.
Use ?field for a multi-variable file. +x and +y scale mask coordinates. +X and +Y set their
units. Mask values cannot be scaled. -K cannot be combined with -Mm, -Ml, or -Mw.
-Mg|m|l|w[+e<vs30|vp|vs|rho>][+w<value>][+t<tolerance>]
Choose wet/land classification precedence. Use g for GMT shoreline priority (the default), m
to let the selected evidence override GMT where it resolves a class, l to classify the entire
domain as land, or w to classify it as wet. A user -K mask is authoritative. Append +e to
select the evidence source. vs30 is the default. Finite positive Vs30 indicates land, a finite
non-positive value indicates wet, and missing Vs30 is unresolved. For vp, vs, or rho
evidence, the selected role must be mapped by -F. The shallowest finite model sample above sea
level indicates land and one below sea level indicates wet. At sea level, +w gives the water
value and +t gives its non-negative matching tolerance. Vs defaults to +w0. Vp and density
require +w. Water values and tolerances use transformed model units after input +v scaling but
before -U conversion. For example, -Mm+evs gives model Vs priority, -Mm+evp+w1500+t50
recognizes Vp from 1450 through 1550 as water, and -Mg+erho+w1000+t25 retains GMT priority
while using model density where GMT is unresolved.
-Sa|c|e|l|n|s<p>[+g[<maxgap>]]
Choose vertical interpolation: Akima (a), cubic (c), step-up (e), linear (l), nearest (n), or
smoothing spline (s<p>) with a non-negative fit parameter p. Linear is the default. Append +g
to bridge internal missing layers, optionally only when the bracketing z-coordinate distance
does not exceed maxgap. -S applies when -T resamples z. +g also fills internal gaps on an
unchanged z lattice. Option -H fills enclosed holes within x-y layers, whereas common -n
controls horizontal sampling onto the -R/-I lattice.
-T<zmin>/<zmax>/<dz>
Set the increasing positive-down working z lattice in metres, with zmin at the top, zmax at
the bottom, zmin < zmax, and dz > 0. The requested range must remain within the transformed
model axis. The native z lattice is retained when -T is omitted. Option -S controls vertical
interpolation onto this lattice. For example, -T0/2000/50 resamples from 0 to 2000 m depth at
50 m intervals.
-U<velocity_scale>[/<density_scale>]
Multiply mapped velocities and density by these factors after input +v scaling to obtain m/s
and kg/m^3 for the empirical equations, then apply the inverse factors before -Z output
scaling. Both factors default to 1. This option does not scale z, Vs30, or transition
thickness. use their input modifiers to express those quantities in metres and m/s before Ely
GTL.
-Z[+x<sx>][+X<xunit>][+y<sy>][+Y<yunit>][+z<sz>][+Z<zunit>][+v<scales>][+V<units>]
Transform output coordinates and properties after interpolation, classification, and Ely GTL.
+x, +y, and +z scale coordinates. +X, +Y, and +Z set coordinate units. +v supplies one
broadcast scale or one scale per output property. +V sets property units. Property lists
follow vp,vs,rho order for mapped and created outputs. Scaling occurs in place and does not
reorder coordinates, layers, or data. For example, -Z+z-0.001+Zkm+v0.001+Vkm/s restores a
positive-up z axis in kilometres and writes velocity in km/s.
Processing order:
NetCDF unpacking and input modifiers. Increasing positive-down axis validation. -H horizontal
gap filling. -R/-I and common -n horizontal resampling. -T/-S vertical resampling and gap
bridging. Vs30, transition-grid, and mask sampling. Wet/land classification. -U SI conversion
and Ely GTL. Empirical property creation. Then -Z output scaling. Interpolation does not
extrapolate beyond the model footprint.
-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].
-n[b|c|l|n][+a][+b<BC>][+c][+t<threshold>]
Specify a grid interpolation directive:
b: B-spline.
c: Bicubic spline [Default].
l: Bilinear spline.
n: Nearest-neighbor value, i.e., no spline at all.
Optional modifiers:
+a Switch off anti-aliasing (except for linear) [Default is ON].
+b Change boundary conditions, where <BC> can be either g for geographic, p for periodic, or
n for natural boundary conditions. For p and n you may optionally append x or y [Default
is both]: x for periodic boundary conditions on x, y for periodic boundary conditions on
y [Default is Natural conditions, unless grid is known to be geographic].
+c Clip interpolated grid to input z-min/max [Default may exceed limits].
+t Change the minimum weight in vicinity of NaNs. A <threshold> of 1.0 requires all nodes
involved in interpolation to be non-NaN; 0.5 will interpolate about half way from a non-
NaN to a NaN node [Default is 0.5].
-^ (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 elygtl examples.