.\" Man page generated from reStructuredText.
.
.TH "SAMPLE1D" "1gmt" "Jan 10, 2019" "5.4.5" "GMT"
.SH NAME
sample1d \- Resample 1-D table data using splines
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBsample1d\fP [ \fItable\fP ]
[  \fB\-A\fP\fBf\fP|\fBp\fP|\fBm\fP|\fBr\fP|\fBR\fP[\fB+l\fP] ]
[  \fB\-F\fP\fBl\fP|\fBa\fP|\fBc\fP|\fBn\fP[\fB+1\fP|\fB+2\fP] ]
[  \fB\-I\fP\fIinc\fP[\fIunit\fP] ]
[  \fB\-N\fP\fIknotfile\fP ]
[  \fB\-S\fP\fIstart\fP[/\fIstop\fP] ]
[  \fB\-T\fP\fIcol\fP ]
[  \fB\-V\fP[\fIlevel\fP] ]
[ \fB\-b\fPbinary ]
[ \fB\-d\fPnodata ]
[ \fB\-e\fPregexp ]
[ \fB\-f\fPflags ]
[ \fB\-g\fPgaps ]
[ \fB\-h\fPheaders ]
[ \fB\-i\fPflags ]
[ \fB\-o\fPflags ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBsample1d\fP reads a multi\-column ASCII [or binary] data set from file
[or standard input] and interpolates the time\-series or spatial profile at locations
where the user needs the values. The user must provide the column number
of the independent (monotonically increasing \fBor\fP decreasing)
variable, here called \fItime\fP (it may of course be any type of quantity).
Equidistant or arbitrary sampling can be selected. All columns
are resampled based on the new sampling interval. Several interpolation
schemes are available. Extrapolation outside the range of the input data
is not supported.
.SH REQUIRED ARGUMENTS
.sp
None.
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
.B \fItable\fP
This is one or more ASCII [of binary, see
\fB\-bi\fP] files with one column containing the
independent \fItime\fP variable (which must be monotonically in/de\-creasing)
and the remaining columns holding other data values. If no file is
provided, \fBsample1d\fP reads from standard input.
.UNINDENT
.INDENT 0.0
.TP
\fB\-A\fP\fBf\fP|\fBp\fP|\fBm\fP|\fBr\fP|\fBR\fP
For track resampling (if \fB\-T\fP\&...\fIunit\fP is set) we can select how
this is to be performed. Append \fBf\fP to keep original points, but
add intermediate points if needed; note this selection does not
necessarily yield equidistant points [Default], \fBm\fP as \fBf\fP, but
first follow meridian (along y) then parallel (along x), \fBp\fP as
\fBf\fP, but first follow parallel (along y) then meridian (along x),
\fBr\fP to resample at equidistant locations; input points are not
necessarily included in the output, and \fBR\fP as \fBr\fP, but adjust
given spacing to fit the track length exactly. Finally, append
\fB+l\fP if distances should be measured along rhumb lines (loxodromes).
.UNINDENT
.INDENT 0.0
.TP
\fB\-Fl\fP|\fBa\fP|\fBc\fP|\fBn\fP[\fB+1\fP|\fB+2\fP]
Choose from \fBl\fP (Linear), \fBa\fP (Akima spline), \fBc\fP (natural
cubic spline), and \fBn\fP (no interpolation: nearest point) [Default
is \fB\-Fa\fP]. You may change the default interpolant; see
GMT_INTERPOLANT in your gmt.conf file.
You may optionally evaluate the first or second derivative of the spline
by appending \fB1\fP or \fB2\fP, respectively.
.UNINDENT
.INDENT 0.0
.TP
\fB\-I\fP\fIinc\fP[\fIunit\fP]
\fIinc\fP defines the sampling interval [Default is the separation
between the first and second abscissa point in the \fItable\fP]. Append
a distance unit (see UNITS) to indicate that the first two columns
contain longitude, latitude and you wish to resample this path with
a spacing of \fIinc\fP in the chosen units. For sampling of (x, y)
Cartesian tracks, specify the unit as c. Use \fB\-A\fP to control how
path resampling is performed.
.UNINDENT
.INDENT 0.0
.TP
\fB\-N\fP\fIknotfile\fP
\fIknotfile\fP is an optional ASCII file with the \fItime\fP locations where the
data set will be resampled in the first column. Note: If \fB\-H\fP is
selected it applies to both \fItable\fP and \fIknotfile\fP\&. Also note that
\fB\-i\fP never applies to \fIknotfile\fP since we always consider the
first column only.
.UNINDENT
.INDENT 0.0
.TP
\fB\-S\fP\fIstart\fP[\fIstop\fP]
For equidistant sampling, \fIstart\fP indicates the \fItime\fP of the
first output value. [Default is the smallest even multiple of \fIinc\fP
inside the range of \fItable\fP]. Optionally, append /\fIstop\fP to
indicate the \fItime\fP of the last output value [Default is the
largest even multiple of \fIinc\fP inside the range of \fItable\fP].
.UNINDENT
.INDENT 0.0
.TP
\fB\-T\fP\fIcol\fP
Sets the column number of the independent \fItime\fP variable [Default is 0
(first)].
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-bi\fP[\fIncols\fP][\fBt\fP] (more ...)
Select native binary input. [Default is 2 (or at least the number of columns implied by \fB\-T\fP)].
.UNINDENT
.INDENT 0.0
.TP
\fB\-bo\fP[\fIncols\fP][\fItype\fP] (more ...)
Select native binary output. [Default is same as input].
.UNINDENT
.INDENT 0.0
.TP
\fB\-d\fP[\fBi\fP|\fBo\fP]\fInodata\fP (more ...)
Replace input columns that equal \fInodata\fP with NaN and do the reverse on output.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-e\fP[\fB~\fP]\fI"pattern"\fP \fB|\fP \fB\-e\fP[\fB~\fP]/\fIregexp\fP/[\fBi\fP] (more ...)
Only accept data records that match the given pattern.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-f\fP[\fBi\fP|\fBo\fP]\fIcolinfo\fP (more ...)
Specify data types of input and/or output columns.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-g\fP[\fBa\fP]\fBx\fP|\fBy\fP|\fBd\fP|\fBX\fP|\fBY\fP|\fBD\fP|[\fIcol\fP]\fBz\fP[+|\-]\fIgap\fP[\fBu\fP] (more ...)
Determine data gaps and line breaks.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-h\fP[\fBi\fP|\fBo\fP][\fIn\fP][\fB+c\fP][\fB+d\fP][\fB+r\fP\fIremark\fP][\fB+r\fP\fItitle\fP] (more ...)
Skip or produce header record(s).  
.UNINDENT
.INDENT 0.0
.TP
\fB\-i\fP\fIcols\fP[\fB+l\fP][\fB+s\fP\fIscale\fP][\fB+o\fP\fIoffset\fP][,\fI\&...\fP] (more ...)
Select input columns and transformations (0 is first column).
.UNINDENT
.INDENT 0.0
.TP
\fB\-o\fP\fIcols\fP[,...] (more ...)
Select output columns (0 is first column).
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.UNINDENT
.SH UNITS
.sp
For map distance unit, append \fIunit\fP \fBd\fP for arc degree, \fBm\fP for arc
minute, and \fBs\fP for arc second, or \fBe\fP for meter [Default], \fBf\fP
for foot, \fBk\fP for km, \fBM\fP for statute mile, \fBn\fP for nautical mile,
and \fBu\fP for US survey foot. By default we compute such distances using
a spherical approximation with great circles. Prepend \fB\-\fP to a
distance (or the unit is no distance is given) to perform "Flat Earth"
calculations (quicker but less accurate) or prepend \fB+\fP to perform
exact geodesic calculations (slower but more accurate).
.SH ASCII FORMAT PRECISION
.sp
The ASCII output formats of numerical data are controlled by parameters
in your gmt.conf file. Longitude and latitude are formatted
according to FORMAT_GEO_OUT, absolute time is
under the control of FORMAT_DATE_OUT and
FORMAT_CLOCK_OUT, whereas general floating point values are formatted
according to FORMAT_FLOAT_OUT\&. Be aware that the format in effect
can lead to loss of precision in ASCII output, which can lead to various
problems downstream. If you find the output is not written with enough
precision, consider switching to binary output (\fB\-bo\fP if available) or
specify more decimals using the FORMAT_FLOAT_OUT setting.
.SH CALENDAR TIME SAMPLING
.sp
If the abscissa are calendar times then you must use the \fB\-f\fP option
to indicate this. Furthermore, \fB\-I\fP then expects an increment in the
current TIME_UNIT units. There is not yet support for variable
intervals such as months.
.SH EXAMPLES
.sp
To resample the file profiles.tdgmb, which contains
(time,distance,gravity,magnetics,bathymetry) records, at 1km equidistant
intervals using Akima\(aqs spline, use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt sample1d profiles.tdgmb \-I1 \-Fa \-T1 > profiles_equi_d.tdgmb
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To resample the file depths.dt at positions listed in the file
grav_pos.dg, using a cubic spline for the interpolation, use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt sample1d depths.dt \-Ngrav_pos.dg \-Fc > new_depths.dt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To resample the file points.txt every 0.01 from 0\-6, using a cubic spline for the
interpolation, but output the first derivative instead (the slope), try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt sample1d points.txt S0/6 \-I0.01 \-Fc+1 > slopes.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To resample the file track.txt which contains lon, lat, depth every 2
nautical miles, use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt sample1d track.txt \-I2n \-AR > new_track.dt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To do approximately the same, but make sure the original points are
included, use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt sample1d track.txt \-I2n \-Af > new_track.dt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To obtain a rhumb line (loxodrome) sampled every 5 km instead, use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt sample1d track.txt \-I5k \-AR+l > new_track.dt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
gmt,
gmt.conf,
greenspline,
filter1d
.SH COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
.\" Generated by docutils manpage writer.
.