% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ctd.R
\name{ctdFindProfiles}
\alias{ctdFindProfiles}
\title{Find Profiles Within a Tow-Yow ctd Record}
\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{
\item{x}{a \linkS4class{ctd} object.}

\item{cutoff}{criterion on pressure difference; see \dQuote{Details}. If not
provided, this defaults to 0.5.}

\item{minLength}{lower limit on number of points in candidate profiles. If
not
provided, this defaults to 10.}

\item{minHeight}{lower limit on height of candidate profiles. If not
provided, this defaults to 0.1 times the pressure span.}

\item{smoother}{The smoothing function to use for identifying down/up
casts. The default is \code{smooth.spline}, which performs well for
a small number of cycles; see \dQuote{Examples} for a method that is
better for a long tow-yo. The return value from \code{smoother} must
be either a list containing an element named \code{y} or something
that can be coerced to a vector with \code{\link[=as.vector]{as.vector()}}. To
turn smoothing off, so that cycles in pressure are determined by
simple first difference, set \code{smoother} to \code{NULL}.}

\item{direction}{String indicating the travel direction to be selected.}

\item{breaks}{optional integer vector indicating the indices of last
datum in each profile stored within \code{x}. Thus, the first profile
in the return value will contain the \code{x} data from indices 1
to \code{breaks[1]}.  If \code{breaks} is given, then all
other arguments except \code{x} are ignored. Using \code{breaks}
is handy in cases where other schemes fail, or when the author
has independent knowledge of how the profiles are strung together
in \code{x}.}

\item{arr.ind}{logical value indicating whether the array indices should be
returned; the alternative is to return a vector of ctd objects.}

\item{distinct}{An optional string indicating how to identify profiles
by unique values. Use \code{"location"}
to find profiles by a change in longitude and latitude, or use the name of any
of item in the \code{data} slot in \code{x}. In these cases, all the
other arguments except \code{x} are ignored. However, if \code{distinct}
is not supplied, the other arguments are handled as described above.}

\item{debug}{an integer specifying whether debugging information is
to be printed during the processing. This is a general parameter that
is used by many \code{oce} functions. Generally, setting \code{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
\code{debug} first, so that a user can often obtain deeper debugging
by specifying higher \code{debug} values.}

\item{...}{Optional extra arguments that are passed to the smoothing function, \code{smoother}.}
}
\value{
If \code{arr.ind=TRUE}, a data frame with columns \code{start} and \code{end}, the indices
of the downcasts.  Otherwise, a vector of \code{ctd} objects. In this second case,
the station names are set to a form like \code{"10/3"}, for the third profile within an
original ctd object with station name \code{"10"}, or to \code{"3"}, if the original
ctd object had no station name defined.
}
\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.
}
\details{
The method works by examining the pressure record.  First, this is smoothed using
\code{smoother()} (see \dQuote{Arguments}), and then the result is first-differenced
using \code{\link[=diff]{diff()}}.  Median values of the positive and
negative first-difference values are then multiplied by \code{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 \code{minLength} points are
discarded.  Then, those that have pressure ranges less than \code{minHeight} are discarded.

Caution: this method is not well-suited to all datasets. For example, the default
value of \code{smoother} is \code{\link[=smooth.spline]{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 \dQuote{Examples}). Also, depending
on the sampling protocol, it is often necessary to pass the resultant profiles through
\code{\link[=ctdTrim]{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. \code{\link[=plotScan]{plotScan()}} to identify profiles visually, for a final product.
}
\section{Sample of Usage}{

\preformatted{
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)
}
}

\seealso{
The documentation for \linkS4class{ctd} explains the structure
of CTD objects, and also outlines the other functions dealing with them.

Other things related to ctd data: 
\code{\link{CTD_BCD2014666_008_1_DN.ODF.gz}},
\code{\link{[[,ctd-method}},
\code{\link{[[<-,ctd-method}},
\code{\link{argo2ctd}()},
\code{\link{as.ctd}()},
\code{\link{cnvName2oceName}()},
\code{\link{ctd}},
\code{\link{ctd-class}},
\code{\link{ctd.cnv.gz}},
\code{\link{ctdDecimate}()},
\code{\link{ctdFindProfilesRBR}()},
\code{\link{ctdRaw}},
\code{\link{ctdRepair}()},
\code{\link{ctdTrim}()},
\code{\link{ctd_aml_type1.csv.gz}},
\code{\link{ctd_aml_type3.csv.gz}},
\code{\link{d200321-001.ctd.gz}},
\code{\link{d201211_0011.cnv.gz}},
\code{\link{handleFlags,ctd-method}},
\code{\link{initialize,ctd-method}},
\code{\link{initializeFlagScheme,ctd-method}},
\code{\link{oceNames2whpNames}()},
\code{\link{oceUnits2whpUnits}()},
\code{\link{plot,ctd-method}},
\code{\link{plotProfile}()},
\code{\link{plotScan}()},
\code{\link{plotTS}()},
\code{\link{read.ctd}()},
\code{\link{read.ctd.aml}()},
\code{\link{read.ctd.itp}()},
\code{\link{read.ctd.odf}()},
\code{\link{read.ctd.odv}()},
\code{\link{read.ctd.saiv}()},
\code{\link{read.ctd.sbe}()},
\code{\link{read.ctd.ssda}()},
\code{\link{read.ctd.woce}()},
\code{\link{read.ctd.woce.other}()},
\code{\link{setFlags,ctd-method}},
\code{\link{subset,ctd-method}},
\code{\link{summary,ctd-method}},
\code{\link{woceNames2oceNames}()},
\code{\link{woceUnit2oceUnit}()},
\code{\link{write.ctd}()}
}
\author{
Dan Kelley and Clark Richards
}
\concept{things related to ctd data}
