% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/master.R
\name{makeMaster}
\alias{makeMaster}
\alias{writeMasterPeptides}
\alias{writeMasterPeptides,MasterPeptides,character-method}
\alias{writeFragmentLibrary}
\alias{writeFragmentLibrary,MasterPeptides,character-method}
\title{Merges final peptide files}
\usage{
makeMaster(pepfiles, fragmentfiles, fdr = 0.01, method = c("BH",
  "Bonferroni", "qval"), span.rt = 0.05, span.int = 0.05,
  maxDeltaRt = Inf, removeNeutralLoss = TRUE, removePrecursor = TRUE,
  tolerance = 2.5e-05, verbose = interactive())
}
\arguments{
\item{pepfiles}{A \code{character} vector of final peptide file
names to be merged.}

\item{fragmentfiles}{A \code{character} vector of final fragment file
names to be combined into an fragment library. These files should be
from the same runs as the final peptide files used in \code{pepfiles}.}

\item{fdr}{A \code{numeric} indicating the peptide false
discovery  rate limit.}

\item{method}{A \code{character} indicating the p-value adjustment to
be used. One of \code{BH} (default), \code{Bonferroni} or \code{qval}.}

\item{span.rt}{A \code{numeric} with the loess span parameter value
to be used for retention time modelling.}

\item{span.int}{A \code{numeric} with the loess span parameter value
to be used for intensity modelling.}

\item{maxDeltaRt}{A \code{double} value that sets a maximum limit for
the retention time deviaton between master and slave run to be included}

\item{removeNeutralLoss}{A \code{logical}, if \code{TRUE} peptides with
neutral loss are removed from the fragment library.}

\item{removePrecursor}{A \code{logical}, if \code{TRUE} precursor ions are
removed from the fragment spectra.}

\item{tolerance}{A \code{double} value that determines the tolerance used
to look for the precursor ions.}

\item{verbose}{A \code{logical} indicating if information should be
printed out.}
}
\value{
An instance of class \code{"\linkS4class{MasterPeptides}"}.
}
\description{
This function combines a list of peptide final peptide files into
one single \emph{master} file that is obtained by merging
the unique peptides from the filtered original peptide files. \cr
Additionally it can combine multiple final fragment files into a fragment
library.
}
\details{
The merging process is as follows:
\enumerate{
\item Each individual peptide final peptide file is filtered to retain
(i) non-duplicated unique tryptic peptides, (ii) peptides with a
false discovery rate <= \code{fdr} and (iii) proteins with a false
positive rate <= \code{fpr}.

\item The filtered peptide files are ordered (1) according to their total
number of peptides (for example [P1, P2, P3]) and (2) as before with the first
item is positioned last ([P2, P3, P1] in the previous example).
The peptide data are then combined in pairs in these respective orders.
The first one is called the \emph{master} file.

\item For each (master, slave) pair, the slave peptide file
retention times are modelled according to the (original)
master's retention times and slave peptides, not yet present in the
master file are added to the master file.

\item The final \emph{master} datasets, containing their own peptides and
the respective slave specific retention time adjusted peptides are returned
as a \code{MasterPeptides} instance.
}

The resulting \code{MasterPeptides} instance can be further used
for a complete master vs. peptides/Pep3D analysis, as described in
\code{\link{Synapter}}, \code{\link{synergise}} or using the GUI
(\code{\link{synapterGUI}}). To do so, it must be serialised (using the
\code{saveRDS} function) with a \code{.rds} file
extension, to be recognised (and loaded) as a \code{R} object.

When several quantitation (or identification) files are combined as a master set
to be mapped back against the inidividual final peptide files,
the second master [P2, P3, P1] is used when analysing the peptide data
that was first selected in the master generation (P1 above).
This is to avoid aligning two identical sets of peptides (those of P1)
and thus not being able to generate a valid retention time model.
This is detected automatically for the user.

The two master peptides dataframes can be exported to disk as
two \code{csv} files with \code{writeMasterPeptides}. The
\code{MasterPeptides} object returned by \code{makeMaster} can be
saved to disk (with \code{save} or \code{saveRDS}) and later reloaded
(with \code{load} or \code{readRDS}) for further analysis.

The fragment library generation works as follows:
\enumerate{
\item Each individual final fragment file is imported and only peptides
present in the \emph{master} dataset are used.

\item The fragments are combined based on their precursor ions.

\item The intensities of identical fragments (seen in different runs)
is summed and divided by the summed precursor intensity (of the same
peptide in different runs).

\item Afterwards the intensities are normalized to the average precursor
intensity of the different runs.

\item Finally a \code{\linkS4class{MSnExp}} object is created.
}

The fragment library dataframe can be exported to disk as
\code{csv} file with \code{writeFragmentLibrary}.
}
\references{
Shliaha P.V., Bond N. J., Lilley K.S. and Gatto L., in prep.
}
\seealso{
See the \code{\link{Synapter}} class manual page for
detailed information on filtering and modelling and the general
algorithm implemented in the \code{synapter} package.

The \code{\link{estimateMasterFdr}} function allows to control
false dicovery rate when combining several peptide files while
maximising the number of identifications and suggest which
combination of peptide files to use.

The vignette, accessible with \code{synapterGuide()}
illustrates a complete pipeline using \code{estimateMasterFdr} and
\code{makeMaster}.
}
\author{
Laurent Gatto, Sebastian Gibb
}
