% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/functions-XCMSnExp.R, R/methods-XCMSnExp.R
\docType{methods}
\name{filterFeatureDefinitions}
\alias{filterFeatureDefinitions}
\alias{[,XCMSnExp,ANY,ANY,ANY-method}
\alias{[[,XCMSnExp,ANY,ANY-method}
\alias{filterMsLevel,XCMSnExp-method}
\alias{filterFile,XCMSnExp-method}
\alias{XCMSnExp-filter}
\alias{filterMz,XCMSnExp-method}
\alias{filterRt,XCMSnExp-method}
\alias{split,XCMSnExp,ANY-method}
\title{XCMSnExp filtering and subsetting}
\usage{
filterFeatureDefinitions(x, features)

\S4method{[}{XCMSnExp,ANY,ANY,ANY}(x, i, j, ..., drop = TRUE)

\S4method{[[}{XCMSnExp,ANY,ANY}(x, i, j, drop = FALSE)

\S4method{filterMsLevel}{XCMSnExp}(object, msLevel.,
  keepAdjustedRtime = hasAdjustedRtime(object))

\S4method{filterFile}{XCMSnExp}(object, file, keepAdjustedRtime = FALSE)

\S4method{filterMz}{XCMSnExp}(object, mz, msLevel., ...)

\S4method{filterRt}{XCMSnExp}(object, rt, msLevel.,
  adjusted = hasAdjustedRtime(object))

\S4method{split}{XCMSnExp,ANY}(x, f, drop = FALSE, ...)
}
\arguments{
\item{x}{For \code{[} and \code{[[}: an \code{\link{XCMSnExp}} object.}

\item{features}{For \code{filterFeatureDefinitions}: either a \code{integer}
specifying the indices of the features (rows) to keep, a \code{logical}
with a length matching the number of rows of \code{featureDefinitions}
or a \code{character} with the feature (row) names.}

\item{i}{For \code{[}: \code{numeric} or \code{logical} vector specifying to
which spectra the data set should be reduced.
For \code{[[}: a single integer or character.}

\item{j}{For \code{[} and \code{[[}: not supported.}

\item{...}{Optional additional arguments.}

\item{drop}{For \code{[} and \code{[[}: not supported.}

\item{object}{A \code{\link{XCMSnExp}} object.}

\item{msLevel.}{For \code{filterMz}, \code{filterRt}, \code{numeric(1)}
defining the MS level(s) to which operations should be applied or to
which the object should be subsetted. See \code{\link{filterMz}}
for more details}

\item{keepAdjustedRtime}{For \code{filterFile}, \code{filterMsLevel},
\code{[} \code{split}: \code{logical(1)} defining whether the adjusted
retention times should be kept, even if e.g. features are being removed
(and the retention time correction was performed on these features).}

\item{file}{For \code{filterFile}: \code{integer} defining the file index
within the object to subset the object by file or \code{character}
specifying the file names to sub set. The indices are expected to be
increasingly ordered, if not they are ordered internally.}

\item{mz}{For \code{filterMz}: \code{numeric(2)} defining the lower and upper
mz value for the filtering.}

\item{rt}{For \code{filterRt}: \code{numeric(2)} defining the retention time
window (lower and upper bound) for the filtering.}

\item{adjusted}{For \code{filterRt}: \code{logical} indicating whether the
object should be filtered by original (\code{adjusted = FALSE}) or
adjusted retention times (\code{adjusted = TRUE}).
For \code{spectra}: whether the retention times in the individual
\code{Spectrum} objects should be the adjusted or raw retention times.}

\item{f}{For \code{split} a vector of length equal to the length of x
defining how \code{x} will be splitted. It is converted internally to
a \code{factor}.}
}
\value{
All methods return an \code{\link{XCMSnExp}} object.
}
\description{
\code{filterFeatureDefinitions} allows to subset the feature definitions of
an \code{XCMSnExp} object. Which feature definitions should be kept can be
specified with the \code{features} argument that can be a \code{logical},
\code{integer} or \code{character} vector. The function returns the
\code{XCMSnExp} with the reduced \code{featureDefinitions} data frame.

The \code{[} method allows to subset a \code{\link{XCMSnExp}}
object by spectra. Be aware that the \code{[} method removes all
preprocessing results, except adjusted retention times if
\code{keepAdjustedRtime = TRUE} is passed to the method.

\code{[[} extracts a single \code{\link{Spectrum}}
object from an \code{XCMSnExp}. The reported retention time is the
adjusted retention time if alignment has been performed on \code{x}.

\code{filterMsLevel}: reduces the \code{\link{XCMSnExp}}
object to spectra of the specified MS level(s). Chromatographic peaks
and identified features are also subsetted to the respective MS level. See
\code{\link{filterMsLevel}} documentation for details and
examples.

The methods listed on this page allow to filter and subset
\code{\link{XCMSnExp}} objects. Most of them are inherited from the
\code{\link{OnDiskMSnExp}} object and have been adapted for
\code{\link{XCMSnExp}} to enable subsetting also on the preprocessing
results.

\code{filterFile}: allows to reduce the
\code{\link{XCMSnExp}} to data from only certain files. Identified
chromatographic peaks for these files are retained while all eventually
present features (peak grouping information) are dropped. By default
also adjusted retention times are removed (if present). This can be
overwritten by setting \code{keepAdjustedRtime = TRUE}.

\code{filterMz}: filters the data set based on the
provided mz value range. All chromatographic peaks and features (grouped
peaks) falling completely within the provided mz value range are retained
(if their minimal mz value is \code{>= mz[1]} and the maximal mz value
\code{<= mz[2]}. Adjusted retention times, if present, are not altered by
the filtering.

\code{filterRt}: filters the data set based on the
provided retention time range. All chromatographic peaks and features
(grouped peaks) the specified retention time window are retained (i.e. if
the retention time corresponding to the peak's apex is within the
specified rt range). If retention time correction has been performed,
the method will by default filter the object by adjusted retention times.
The argument \code{adjusted} allows to specify manually whether filtering
should be performed by raw or adjusted retention times. Filtering by
retention time does not drop any preprocessing results nor does it remove
or change alignment results (i.e. adjusted retention times).
The method returns an empty object if no spectrum or feature is within
the specified retention time range.

\code{split} splits an \code{XCMSnExp} object into a \code{list}
of \code{XCMSnExp} objects based on the provided parameter \code{f}.
Note that by default all pre-processing results are removed by the
splitting, except adjusted retention times, if the optional argument
\code{keepAdjustedRtime = TRUE} is provided.
}
\details{
All subsetting methods try to ensure that the returned data is
consistent. Correspondence results for example are removed if the data
set is sub-setted by file, since the correspondence results are dependent
on the files on which correspondence was performed. Thus, some filter
and sub-setting methods drop some of the preprocessing results. An
exception are the adjusted retention times: most subsetting methods
support the argument \code{keepAdjustedRtime} (even the \code{[} method)
that forces the adjusted retention times to be retained even if the
default would be to drop them.
}
\note{
The \code{filterFile} method removes also process history steps not
related to the files to which the object should be sub-setted and updates
the \code{fileIndex} attribute accordingly. Also, the method does not
allow arbitrary ordering of the files or re-ordering of the files within
the object.

Note also that most of the filtering methods, and also the subsetting
operations \code{[} drop all or selected preprocessing results. To
consolidate the alignment results, i.e. ensure that adjusted retention
times are always preserved, use the \code{\link{applyAdjustedRtime}}
function on the object that contains the alignment results. This replaces
the raw retention times with the adjusted ones.
}
\examples{

## Load some of the files from the faahKO package.
library(faahKO)
fs <- c(system.file('cdf/KO/ko15.CDF', package = "faahKO"),
        system.file('cdf/KO/ko16.CDF', package = "faahKO"),
        system.file('cdf/KO/ko18.CDF', package = "faahKO"))
## Read the files
od <- readMSData(fs, mode = "onDisk")

## Perform peak detection on them using the matched filter algorithm. Note
## that we use a large value for binSize to reduce the runtime of the
## example code.
mfp <- MatchedFilterParam(binSize = 5)
xod <- findChromPeaks(od, param = mfp)

## Subset the dataset to the first and third file.
xod_sub <- filterFile(xod, file = c(1, 3))

## The number of chromatographic peaks per file for the full object
table(chromPeaks(xod)[, "sample"])

## The number of chromatographic peaks per file for the subset
table(chromPeaks(xod_sub)[, "sample"])

basename(fileNames(xod))
basename(fileNames(xod_sub))

## Filter on mz values; chromatographic peaks and features within the
## mz range are retained (as well as adjusted retention times).
xod_sub <- filterMz(xod, mz = c(300, 400))
head(chromPeaks(xod_sub))
nrow(chromPeaks(xod_sub))
nrow(chromPeaks(xod))

## Filter on rt values. All chromatographic peaks and features within the
## retention time range are retained. Filtering is performed by default on
## adjusted retention times, if present.
xod_sub <- filterRt(xod, rt = c(2700, 2900))

range(rtime(xod_sub))
head(chromPeaks(xod_sub))
range(chromPeaks(xod_sub)[, "rt"])

nrow(chromPeaks(xod))
nrow(chromPeaks(xod_sub))

## Extract a single Spectrum
xod[[4]]

## Subsetting using [ removes all preprocessing results - using
## keepAdjustedRtime = TRUE would keep adjusted retention times, if present.
xod_sub <- xod[fromFile(xod) == 1]
xod_sub

## Using split does also remove preprocessing results, but it supports the
## optional parameter keepAdjustedRtime.
## Split the object into a list of XCMSnExp objects, one per file
xod_list <- split(xod, f = fromFile(xod))
xod_list
}
\seealso{
\code{\link{XCMSnExp}} for base class documentation.
}
\author{
Johannes Rainer
}
