merge1d

merge1d tiles or smoothly merges one-dimensional multiparameter data series. Inputs may be text tables or one-dimensional NetCDF series, but not both at the same time.

Synopsis

gmt merge1d <mergefile|input1 input2 ...> -Tmin/max/inc [-Goutput] [options]

Behavior

The output axis is defined by -Tmin/max/inc. Text tables use the first column as the coordinate and every remaining column as a data field. All participating tables must contain the same number of fields/columns. NetCDF variables selected together must share one coordinate dimension.

Direct file lists tile data in availability order. The default -Cf retains the first available value. -Cl, -Co, and -Cu select the lowest, last, or highest value. The +n and +p modifiers restrict replacement by sign.

Weighted merging uses records of the form:

primary [secondary] [west/east] [window] [r1/r2]

Each non-comment record contains up to five whitespace-separated fields:

primary

Required source providing the primary values for the record.

secondary

Optional source paired with the primary for merging. Use - for an unpaired fallback tile. Pairing is valid only within the primary coordinate domain.

west/east

Support interval for a paired primary. It must lie within the primary coordinate domain. The default is the entire primary domain.

window

BLEND window function applied within the support. The default is cosine.

r1/r2

Dimensionless beginning and ending taper ratios relative to the support length. r1 applies at west (low coordinate) and r2 at east (high coordinate). Each ratio must be in [0, 0.5). One ratio applies symmetrically, and the default is 0.2/0.2.

A ratio sets the fraction of the support length used by the transition at that boundary. For example, on support 20/80, 0/0.2 disables the west taper and uses approximately the final 12 coordinate units for the east taper. Within a taper, the selected window controls how the primary merging weight changes between its boundary value and 1. The paired secondary receives the complementary weight. Larger ratios give broader transitions and a smaller full-primary interior. A ratio of 0 disables the taper on that side. The boxcar window ignores taper ratios and has unit weight throughout the support.

Use - to skip an optional field when supplying a later field. Trailing optional fields may be omitted. Blank lines and text following # are ignored. For example:

primary.nc secondary.nc 20/80 cosine 0.25/0.25
secondary.nc - - - -

Add the secondary as a later unpaired record when it should provide fallback values outside the paired primary domain. -A normalizes positive weights where primary supports that share the same secondary source overlap.

The -S option selects interpolation onto -T: Akima (a), cubic (c), step-up (e), linear (l), nearest (n), or smoothing spline (s<p>) with non-negative fit parameter p. Linear (l) is the default. Interpolation operates independently within contiguous finite runs by default. Append +g to bridge internal gaps, optionally with a maximum bracketing coordinate distance. Values are not extrapolated before the first or after the last available sample. -P may subsequently fill any remaining primary gaps from the paired secondary. Without -P, those primary gaps remain missing.

Select NetCDF fields by appending ? and a comma-separated list to each filename, for example model.nc?vp,vs,rho. Selected variables must share one coordinate dimension. If ? is omitted, merge1d uses the first eligible one-dimensional data variable. Selector modifiers follow the field list. Use model.nc?<field1,field2,...>+<modifiers> for named fields or model.nc?+<modifiers> to transform the default variable without naming it. For example, model.nc?vp,vs+x0.001+Xkm+v0.001,0.001+Vkm/s,km/s selects vp and vs, scales the input axis in metres to kilometres, and scales both fields in m/s to km/s.

The selector modifiers +x and +v scale the input coordinate and fields, while +X and +V set their target-unit metadata. One +v or +V value applies to every selected field. Otherwise, values follow selector order. These input transforms are applied before interpolation and merging. Input +x scaling does not reorder coordinates or samples, and the transformed input axis must be strictly increasing. A decreasing source axis can therefore use a negative +x scale to make it increase. Output -Z+x can restore the axis convention after merging without reordering the data. The +n modifier declares an additional missing-value sentinel.

The -F option names output NetCDF variables. It does not select source variables. Selected fields map positionally to -F, so model1.nc?vp,vs,den and model2.nc?p,s,d can both map to output fields vp,vs,rho with -Fvp,vs,rho. One explicitly selected variable retains its source name when -F is absent. An unselected single variable is named z. The -Z modifiers transform the final coordinate and fields after merging, in -F order when supplied and model selector order otherwise. -Z scales output coordinates and fields in place and does not reorder coordinates, fields, or weights. A negative -Z+x scale therefore produces a decreasing output axis. For example, with -Fvp,vs, -Z+x-0.001+Xkm+v0.001,0.001+Vkm/s,km/s converts a positive-down axis from m to a negative-down axis in km and converts both velocity fields in m/s to km/s without changing sample order. Declared missing values, IEEE NaNs, selector +n sentinels, and text -di values are set to NaN.

Text output goes to standard output unless -G is supplied. A .nc suffix requests NetCDF output. -W adds the shared weight field, with long_name="merging weight" and units 1. -W+o writes only the coordinate and weight. All selected fields use this same merging weight.

Usage

gmt merge1d [gq] 6.5.0 [64-bit] - Tile or smoothly merge one-dimensional tables and multiparameter
  NetCDF series

usage: gmt merge1d [<mergefile> | <input1> <input2> ...] -T<min>/<max>/<inc> [-A] [-Cf|l|o|u[+n|p]]
  [-F<fields>] [-G<output>] [-P] [-Sa|c|e|l|n|s<p>] [-W[+o]]
  [-Z+x<scale>[+X<unit>]+v<scales>[+V<units>]] [-V[q|e|w|t|i|c|d]] [-di<nodata>[+c<col>]] [-f[i|⏎
  …o]<colinfo>] [-h[i|o][<nrecs>][+c][+d][+m<segheader>][+r<remark>][+t<title>]]

  REQUIRED ARGUMENTS:

  <mergefile> | <input1> <input2> ...
     Supply one mergefile or list one or more data inputs directly. Direct inputs use clobber/⏎
     …tiling mode in availability order. A run may use text or NetCDF inputs, but not both.
       Each non-comment mergefile record contains up to five whitespace-separated fields:
       primary: Required source providing the primary values for the record.
       secondary: Optional source paired with primary for merging. Use '-' for an unpaired fallback
          tile.
       west/east: Support interval for a paired primary. It must lie within the primary coordinate
          domain. The default is the entire primary domain.
       window: BLEND window function applied within the support. The default is cosine.
       r1/r2: Dimensionless beginning and ending taper ratios. Each must be in [0, 0.5). One ratio
          applies symmetrically. The default is 0.2/0.2.
       A taper ratio sets the fraction of the support length used by the transition at that
          boundary. r1 applies at west (low coordinate) and r2 at east (high coordinate). For
          example, on support 20/80, 0/0.2 disables the west taper and uses approximately the final
          12 coordinate units for the east taper.
       Within a taper, the selected window controls how the primary merging weight changes between
          its boundary value and 1. The paired secondary receives the complementary weight. A
          larger ratio gives a broader transition and a smaller full-primary interior. A ratio of 0
          disables the taper on that side. The boxcar window ignores taper ratios and has unit
          weight throughout the support.
       Use '-' to skip an optional field when supplying a later field. Trailing optional fields may
          be omitted. Blank lines and text after '#' are ignored.
       Example mergefile:
        primary.nc secondary.nc 20/80 cosine 0.25/0.25
        secondary.nc - - - -
       Text tables use the first column as the axis and remaining columns as fields.
       For NetCDF, append ?field1,field2,... to select one or more data variables, which must share
          one coordinate. If ? is omitted, the first eligible one-dimensional data variable is
          used.
       Append selector modifiers after the field list. +x scales the input axis, +v supplies one
          broadcast scale or one scale per selected field, +X and +V set their target-unit
          metadata, and +n declares an additional missing-value sentinel. Use file.nc?<field1,⏎
          …field2,...>+<modifiers> for named fields or file.nc?+<modifiers> to transform the default
          field without naming it. These input transforms are applied before interpolation and
          merging.
       Input +x scaling does not reorder coordinates or samples. The transformed input axis must be
          strictly increasing. Use a negative +x scale to make a decreasing source axis increase,
          then use output -Z+x<scale> to restore a decreasing output convention if desired.
       Example: model.nc?vp,vs+x0.001+Xkm+v0.001,0.001+Vkm/s,km/s selects vp and vs, scales the
          input axis from m to km, and scales both fields from m/s to km/s.

  -T<min>/<max>/<inc>
     Set the regular output coordinate range and increment.

  OPTIONAL ARGUMENTS:

  -A
     Normalize positive weights where primary supports overlap. Overlapping supports must use the
     same secondary source. A later record for that secondary starts a lower-priority layer.
     Unpaired records remain fallback tiles.

  -Cf|l|o|u[+n|p]
     Select clobber mode instead of blending:
       f: Keep the first value. This is the default for direct file lists.
       l: Keep the lowest value.
       o: Keep the last value.
       u: Keep the highest value.
       +n: Only consider non-positive values for clobbering.
       +p: Only consider non-negative values for clobbering.

  -F<field1,field2,...>
     Set NetCDF output variable names. -F does not select source variables: names selected with ?
     map positionally to -F. Thus model1.nc?vp,vs,den and model2.nc?p,s,d may be merged with -Fvp,⏎
     …vs,rho when the differently named variables are equivalent.

  -G<output>
     Write to output. A .nc suffix selects NetCDF. Otherwise a text table is written. Text output
     defaults to standard output.

  -P
     Fill primary values that remain missing after interpolation from their paired secondary
     values. By default, primary NaNs are preserved.

  -Sa|c|e|l|n|s<p>[+g[<maxgap>]]
     Choose GMT 1-D interpolation: Akima (a), cubic (c), step-up (e), linear (l), nearest (n), or
     smoothing spline (s<p>) with non-negative fit parameter p. Linear (l) is the default. Append
     +g to bridge internal missing runs, optionally only when the bracketing coordinate distance
     does not exceed maxgap.

  -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.

  -W[+o]
     Include the shared merging weight. For text it is appended as the final column. Append +o for
     coordinate and weight only.

  -Z[+x<scale>][+X<unit>][+v<scales>][+V<units>]
     Transform output coordinates and fields after merging. Unlike modifiers appended to an input
     selector, -Z applies only to the completed output. +x scales the output axis and +v supplies
     one broadcast scale or one scale per output field, in -F order when -F is used and selector
     order otherwise. +X and +V set target-unit metadata. -Z scales output coordinates and fields
     in place and does not reorder coordinates, fields, or weights. A negative axis scale therefore
     produces a decreasing output axis.
       Example: with -Fvp,vs, -Z+x-0.001+Xkm+v0.001,0.001+Vkm/s,km/s converts a positive-down
          output axis from m to a negative-down axis in km and converts vp and vs from m/s to km/s.
          The output samples remain in their original order.

  -di<nodata>[+c<col>] Replace any <nodata> values in input data with NaN.
       +c Append first column to be affected [2].

  -f[i|o]<colinfo>
     Indicate content of input/output columns. Optionally append i(nput) or o(utput) [Default is
     both]. Append <colinfo> as one or more comma-separated groups of <cols><type>, where <cols> is
     a column (or column ranges) and <type> is the column type, chosen from T (Calendar format), t
     (time relative to TIME_EPOCH), f (floating point), x (longitude), y (latitude), or d
     (dimension). You may also use s (string) to indicate the start column of trailing text.
     Shortcuts: -f[i|o]g means -f[i|o]0x,1y (geographic, i.e., lon/lat coordinates), -f[i|o]c means
     -f[i|o]0:1f (Cartesian coordinates), while -fp[<unit>] means input x,y are already in
     projected coordinates in <unit> [e].

  -h[i|o][<nrecs>][+c][+d][+m<segheader>][+r<remark>][+t<title>]
     Input/output file has <nrecs> header record(s) [OFF]. Optionally, append i for input or o for
     output only and number of expected header records [0]. Note: -hi turns off the writing of all
     headers on output since none will be read. Optional modifiers:
       +c Add header record with column information [none].
       +d Delete headers before adding new ones [Default will append headers].
       +m Insert a new segment header and <segheader> content after the headers [none].
       +r Add a <remark> comment to the output [none].
       +t Add a <title> comment to the output [none].
     Note: <remark> and <title> may contain \n to indicate line-breaks. For binary files, <nrecs>
     is considered to mean number of bytes instead of records.

  -^ (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 merge1d examples.

merge1d

Synopsis

Behavior

Usage

Examples

See also