R: Find Profiles Within a Tow-Yow ctd Record

ctdFindProfiles {oce}

R Documentation

Find Profiles Within a Tow-Yow ctd Record

Description

Examine the pressure record looking for extended periods of either ascent or descent, and return either indices to these events or a vector of CTD records containing the events.

Usage

ctdFindProfiles(
  x,
  cutoff = 0.5,
  minLength = 10,
  minHeight,
  smoother = smooth.spline,
  direction = c("descending", "ascending"),
  breaks,
  arr.ind = FALSE,
  distinct,
  debug = getOption("oceDebug"),
  ...
)

Arguments

`x`	a ctd object.
`cutoff`	criterion on pressure difference; see “Details”. If not provided, this defaults to 0.5.
`minLength`	lower limit on number of points in candidate profiles. If not provided, this defaults to 10.
`minHeight`	lower limit on height of candidate profiles. If not provided, this defaults to 0.1 times the pressure span.
`smoother`	The smoothing function to use for identifying down/up casts. The default is `smooth.spline`, which performs well for a small number of cycles; see “Examples” for a method that is better for a long tow-yo. The return value from `smoother` must be either a list containing an element named `y` or something that can be coerced to a vector with `as.vector()`. To turn smoothing off, so that cycles in pressure are determined by simple first difference, set `smoother` to `NULL`.
`direction`	String indicating the travel direction to be selected.
`breaks`	optional integer vector indicating the indices of last datum in each profile stored within `x`. Thus, the first profile in the return value will contain the `x` data from indices 1 to `breaks[1]`. If `breaks` is given, then all other arguments except `x` are ignored. Using `breaks` is handy in cases where other schemes fail, or when the author has independent knowledge of how the profiles are strung together in `x`.
`arr.ind`	logical value indicating whether the array indices should be returned; the alternative is to return a vector of ctd objects.
`distinct`	An optional string indicating how to identify profiles by unique values. Use `"location"` to find profiles by a change in longitude and latitude, or use the name of any of item in the `data` slot in `x`. In these cases, all the other arguments except `x` are ignored. However, if `distinct` is not supplied, the other arguments are handled as described above.
`debug`	an integer specifying whether debugging information is to be printed during the processing. This is a general parameter that is used by many `oce` functions. Generally, setting `debug=0` turns off the printing, while higher values suggest that more information be printed. If one function calls another, it usually reduces the value of `debug` first, so that a user can often obtain deeper debugging by specifying higher `debug` values.
`...`	Optional extra arguments that are passed to the smoothing function, `smoother`.

Details

The method works by examining the pressure record. First, this is smoothed using smoother() (see “Arguments”), and then the result is first-differenced using diff(). Median values of the positive and negative first-difference values are then multiplied by cutoff. This establishes criteria for any given point to be in an ascending profile, a descending profile, or a non-profile. Contiguous regions are then found, and those that have fewer than minLength points are discarded. Then, those that have pressure ranges less than minHeight are discarded.

Caution: this method is not well-suited to all datasets. For example, the default value of smoother is smooth.spline(), and this works well for just a few profiles, but poorly for a tow-yo with a long sequence of profiles; in the latter case, it can be preferable to use simpler smoothers (see “Examples”). Also, depending on the sampling protocol, it is often necessary to pass the resultant profiles through ctdTrim(), to remove artifacts such as an equilibration phase, etc. Generally, one is well-advised to use the present function for a quick look at the data, relying on e.g. plotScan() to identify profiles visually, for a final product.

Value

If arr.ind=TRUE, a data frame with columns start and end, the indices of the downcasts. Otherwise, a vector of ctd objects. In this second case, the station names are set to a form like "10/3", for the third profile within an original ctd object with station name "10", or to "3", if the original ctd object had no station name defined.

Sample of Usage

library(oce)
# These examples cannot be tested, because they are based on
# data objects that are not provided with oce.

# Example 1. Find profiles within a towyo file, as can result
# if the CTD is cycled within the water column as the ship
# moves.
profiles <- ctdFindProfiles(towyo)

# Example 2. Use a moving average to smooth pressure, instead of the
# default smooth.spline() method. This might avoid a tendency of
# the default scheme to miss some profiles in a long towyo.
movingAverage <- function(x, n = 11, ...)
{
    f <- rep(1/n, n)
    stats::filter(x, f, ...)
}
casts <- ctdFindProfiles(towyo, smoother=movingAverage)

# Example 3: glider data read into a ctd object. Chop
# into profiles by looking for pressure jumps exceeding
# 10 dbar.
breaks <- which(diff(gliderAsCtd[["pressure"]]) > 10)
profiles <- ctdFindProfiles(gliderAsCtd, breaks=breaks)

Author(s)

Dan Kelley and Clark Richards