% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/section.R
\name{subset,section-method}
\alias{subset,section-method}
\alias{subset.section}
\title{Subset a section Object}
\usage{
\S4method{subset}{section}(x, subset, ...)
}
\arguments{
\item{x}{a \linkS4class{section} object.}

\item{subset}{an optional indication of either the stations to be kept,
or the data to be kept within the stations.  See \dQuote{Details}.}

\item{...}{optional arguments, of which only the first is examined. The
possibilities for this argument are \code{indices}, which must be a
vector of station indices (see Example 6), or \code{within}, which must be
a list or data frame, containing items named either \code{x} and \code{y}
or \code{longitude} and \code{latitude} (see Example 7). If \code{within}
is given, then \code{subset} is ignored.}
}
\value{
A \linkS4class{section} object.
}
\description{
Return a subset of a section object.
}
\details{
This function is used to subset data within the
stations of a section, or to choose a subset of the stations
themselves. The first case is handled with the \code{subset} argument,
while the second is handled if \code{...} contains a vector named
\code{indices}. Either \code{subset} or \code{indices} must be
provided, but not both.

\strong{In the "subset" method}, \code{subset} indicates
either stations to be kept, or data to be kept within the stations.

The first step in processing is to check for the presence of certain
key words in the \code{subset} expression. If \code{distance}
is present, then stations are selected according to a condition on the
distance (in km) from the first station to the given station (Example 1).
If either \code{longitude} or \code{latitude} is given, then
stations are selected according to the stated condition (Example 2).
If \code{stationId} is present, then selection is in terms of the
station ID (not the sequence number) is used (Example 3). In all of these
cases, stations are either selected in their entirety or dropped
in their entirety.

If none of these keywords is present, then the \code{subset} expression is
evaluated in the context of the \code{data} slot of each of the CTD stations
stored within \code{x}. (Note that this slot does not normally
contain any of the keywords that are listed in the previous
paragraph; it does, then odd results may occur.) Each station is examined
in turn, with \code{subset} being evaluated individually in each. The evaluation
produces a logical vector. If that vector has length 1 (Examples 4 and 5)
then the station is retained or discarded, accordingly. If the vector is longer,
then the logical vector is used as a sieve to subsample that individual CTD
profile.

\strong{In the "indices" method}, stations are selected using
\code{indices}, which may be a vector of integers that indicate sequence
number, or a logical vector, again indicating which stations to keep.
}
\section{Sample of Usage}{

\preformatted{
# Example 7. Subset by a polygon determined with locator()
par(mfrow=c(2, 1))
plot(section, which="map")
bdy <- locator(4) # choose a polygon near N. America
GS <- subset(section, within=bdy)
plot(GS, which="map")
}
}

\examples{
library(oce)
data(section)

# Example 1. Stations within 500 km of the first station
starting <- subset(section, distance < 500)

# Example 2. Stations east of 50W
east <- subset(section, longitude > (-50))

# Example 3. Gulf Stream
GS <- subset(section, 113 <= stationId & stationId <= 129)

# Example 4. Only stations with more than 5 pressure levels
long <- subset(section, length(pressure) > 5)

# Example 5. Only stations that have some data in top 50 dbar
surfacing <- subset(section, min(pressure) < 50)

# Example 6. Similar to #4, but done in more detailed way
long <- subset(section,
    indices = unlist(lapply(
        section[["station"]],
        function(s) 5 < length(s[["pressure"]])
    ))
)

}
\seealso{
Other functions that subset oce objects: 
\code{\link{subset,adp-method}},
\code{\link{subset,adv-method}},
\code{\link{subset,amsr-method}},
\code{\link{subset,argo-method}},
\code{\link{subset,cm-method}},
\code{\link{subset,coastline-method}},
\code{\link{subset,ctd-method}},
\code{\link{subset,echosounder-method}},
\code{\link{subset,lobo-method}},
\code{\link{subset,met-method}},
\code{\link{subset,oce-method}},
\code{\link{subset,odf-method}},
\code{\link{subset,rsk-method}},
\code{\link{subset,sealevel-method}},
\code{\link{subset,topo-method}},
\code{\link{subset,xbt-method}}

Other things related to section data: 
\code{\link{[[,section-method}},
\code{\link{[[<-,section-method}},
\code{\link{as.section}()},
\code{\link{handleFlags,section-method}},
\code{\link{initializeFlagScheme,section-method}},
\code{\link{plot,section-method}},
\code{\link{read.section}()},
\code{\link{section}},
\code{\link{section-class}},
\code{\link{sectionAddStation}()},
\code{\link{sectionGrid}()},
\code{\link{sectionSmooth}()},
\code{\link{sectionSort}()},
\code{\link{summary,section-method}}
}
\author{
Dan Kelley
}
\concept{functions that subset oce objects}
\concept{things related to section data}
