xenial (1) grdspotter.1gmt.gz

Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       grdspotter - Create CVA image from a gravity or topography grid

SYNOPSIS

       grdspotter  [grdfile] rotfile CVAgrid increment region [ agegrid ] [ DIgrid ] [ IDgrid ] [  ] [ upper_age
       ] [ PAgrid ] [ IDinfo ] [  ] [ t|ufixed_val ] [ [ [level] ] [ n_try ]] [ -Zz_min[/z_max[/z_inc]] ] [ -r ]

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       grdspotter reads a grid file with residual bathymetry or gravity and calculates flowlines from each  node
       that  exceeds a minimum value using the specified rotations file. These flowlines are then convolved with
       the volume of the prism represented by each grid node and added up to give a Cumulative Volcano Amplitude
       grid (CVA).

REQUIRED ARGUMENTS

       grdfile
              Data grid to be processed, typically residual bathymetry or free-air anomalies.

       -Erotfile
              Give  file  with  rotation  parameters.  This file must contain one record for each rotation; each
              record must be of the following format:

              lon lat tstart [tstop] angle [ khat a b c d e f g df ]

              where tstart and tstop are in Myr and lon lat angle are in degrees. tstart and tstop are the  ages
              of  the  old  and  young  ends  of  a  stage.  If  tstop is not present in the record then a total
              reconstruction rotation is expected and tstop is implicitly set to 0 and should not  be  specified
              for any of the records in the file. If a covariance matrix C for the rotation is available it must
              be specified in a format using the nine optional terms listed in brackets. Here, C = (g/khat)*[  a
              b  d; b c e; d e f ] which shows C made up of three row vectors. If the degrees of freedom (df) in
              fitting the rotation is 0 or not given it is set to 10000. Blank lines  and  records  whose  first
              column  contains  #  will  be ignored. You may prepend a leading + to the filename to indicate you
              wish to invert the rotations.   Alternatively,  give  the  filename  composed  of  two  plate  IDs
              separated  by  a hyphen (e.g., PAC-MBL) and we will instead extract that rotation from the GPlates
              rotation database. We return an error if the rotation cannot be found.

       -G     Specify name for output CVA grid file.

       -Ixinc[unit][=|+][/yinc[unit][=|+]]
              x_inc [and  optionally  y_inc]  is  the  grid  spacing.  Optionally,  append  a  suffix  modifier.
              Geographical (degrees) coordinates: Append m to indicate arc minutes or s to indicate arc seconds.
              If one of the units e, f, k, M, n or u is appended instead, the increment is assumed to  be  given
              in  meter, foot, km, Mile, nautical mile or US survey foot, respectively, and will be converted to
              the equivalent degrees longitude at the middle latitude of the region (the conversion  depends  on
              PROJ_ELLIPSOID).  If  /y_inc  is  given but set to 0 it will be reset equal to x_inc; otherwise it
              will be converted to degrees latitude. All coordinates: If = is appended  then  the  corresponding
              max  x (east) or y (north) may be slightly adjusted to fit exactly the given increment [by default
              the increment may be adjusted slightly to fit the given domain]. Finally,  instead  of  giving  an
              increment  you  may  specify  the  number  of nodes desired by appending + to the supplied integer
              argument; the increment is then recalculated  from  the  number  of  nodes  and  the  domain.  The
              resulting  increment  value  depends  on  whether  you  have  selected  a  gridline-registered  or
              pixel-registered grid; see App-file-formats for details. Note: if -Rgrdfile is used then the  grid
              spacing has already been initialized; use -I to override the values.

       -R[unit]west/east/south/north[/zmin/zmax][r]
              west,  east,  south, and north specify the region of interest, and you may specify them in decimal
              degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if  lower  left  and  upper  right  map
              coordinates  are  given instead of w/e/s/n. The two shorthands -Rg and -Rd stand for global domain
              (0/360 and -180/+180 in longitude respectively, with -90/+90 in latitude).  Alternatively for grid
              creation,  give  Rcodelon/lat/nx/ny, where code is a 2-character combination of L, C, R (for left,
              center, or right) and T, M, B for top, middle, or bottom. e.g., BL for lower left.  This indicates
              which  point  on a rectangular region the lon/lat coordinate refers to, and the grid dimensions nx
              and ny with grid spacings via -I is used  to  create  the  corresponding  region.   Alternatively,
              specify  the  name  of an existing grid file and the -R settings (and grid spacing, if applicable)
              are copied from the grid. Using -Runit expects projected (Cartesian) coordinates  compatible  with
              chosen  -J  and  we  inversely  project  to  determine  actual rectangular geographic region.  For
              perspective view (-p), optionally append /zmin/zmax.  In case of perspective view (-p), a  z-range
              (zmin,  zmax)  can  be  appended  to indicate the third dimension. This needs to be done only when
              using the -Jz option, not when using only the -p option. In the latter case a perspective view  of
              the plane is plotted, with no third dimension.

OPTIONAL ARGUMENTS

       -Aagegrid
              Supply  a  crustal  age grid that is co-registered with the input data grid. These ages become the
              upper ages to use when constructing flowlines [Default extend flowlines back to oldest  age  found
              in the rotation file; but see ].

       -DDIgrid
              Use  flowlines  to  determine  the  maximum  CVA encountered along each flowline and create a Data
              Importance (DI) grid with these values at the originating nodes.

       -LIDgrid
              Supply a co-registered grid with seamount chain IDs for each node.  This option requires that  you
              also use .

       -M     Do  not  attempt  to  keep  all flowlines in memory when using -D and/or -P. Should you run out of
              memory you can use this option to compute flowlines on-the-fly. It will be slower as we no  longer
              can  reuse  the  flowlines  calculated for the CVA step. Cannot be used with -W or the multi-slice
              mode in -Z.

       -Nupper_age
              Set the upper age to assign to nodes whose crustal age is unknown (i.e., NaN) [no upper age]. Also
              see .

       -PPAgrid
              Use  flowlines  to  determine  the  flowline  age  at  the  CVA maximum for each node and create a
              Predicted Age (PA) grid with these values at the originating nodes.

       -QIDinfo
              Either give (1) a single ID to use or (2) the name of a file with a list of IDs  to  use  [Default
              uses all IDs]. Each line would be TAG ID [w e s n]. The w/e/s/n zoom box is optional; if specified
              it means we only trace the flowline if inside  this  region  [Default  uses  region  set  by  -R].
              Requires -L.

       -S     Normalize  the  resulting CVA grid to percentages of the CVA maximum.  This also normalizes the DI
              grid (if requested).

       -Tt|ufixed_val
              Selects ways to adjust ages; repeatable. Choose from -Tt to truncate crustal ages  given  via  the
              option that exceed the upper age set with  [no truncation], or ufixed_val which means that after a
              node passes the test implied by , we use this fixed_val instead in the calculations. [Default uses
              individual node values].

       -V[level] (more ...)
              Select verbosity level [c].

       -Wn_try
              Get  n_try bootstrap estimates of the maximum CVA location; the longitude and latitude results are
              written to stdout [Default is no bootstrapping]. Cannot be used with -M.

       -Zz_min[/z_max[/z_inc]]
              Ignore nodes with z-values lower than z_min [0] and  optionally  larger  than  z_max  [Inf].  Give
              z_min/z_max/z_inc  to  make  separate  CVA  grids  for  each z-slice [Default makes one CVA grid].
              Multi-slicing cannot be used with -M.

       -r (more ...)
              Set pixel node registration [gridline].

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows use just -).

       -+ or just +
              Print an extensive usage (help) message, including the explanation of any  module-specific  option
              (but not the GMT common options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation of options, then exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

GEODETIC VERSUS GEOCENTRIC COORDIINATES

       All  spherical rotations are applied to geocentric coordinates.  This means that incoming data points and
       grids are considered to represent  geodetic  coordinates  and  must  first  be  converted  to  geocentric
       coordinates.  Rotations  are  then  applied,  and  the  final  reconstructed points are converted back to
       geodetic coordinates.  This default behavior can be bypassed if the ellipsoid setting  PROJ_ELLIPSOID  is
       changed to Sphere.

EXAMPLES

       To create a CVA image from the Pacific topography grid Pac_res_topo.nc, using the DC85.d Euler poles, and
       only output a grid for the specified domain, run

              gmt grdspotter Pac_res_topo.nc -EDC85.d -GCVA.nc -R190/220/15/25 -I2m -N145 -Tt -V

       This file can then be plotted with grdimage.

NOTES

       GMT  distributes  the  EarthByte  rotation  model  Global_EarthByte_230-0Ma_GK07_AREPS.rot.   To  use  an
       alternate  rotation  file,  create  an environmental parameters named GPLATES_ROTATIONS that points to an
       alternate rotation file.

SEE ALSO

       gmt, grdimage, project, mapproject, backtracker, hotspotter, originator

REFERENCES

       Wessel, P., 1999, "Hotspotting" tools released, EOS Trans. AGU, 80 (29), p. 319.

       Wessel, P., 2008, Hotspotting: Principles and properties of a plate tectonic  Hough  transform,  Geochem.
       Geophys. Geosyst. 9(Q08004): doi:10.1029/2008GC002058.

       2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe