% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/synergise.R
\name{synergise2}
\alias{synergise2}
\alias{synergize2}
\title{Synergise identification and quantitation results}
\usage{
synergise2(filenames, master = FALSE, object, outputdir,
  outputfile = paste0("synapter_report_", strftime(Sys.time(),
  "\%Y\%m\%d-\%H\%M\%S"), ".html"), fdr = 0.01, fdrMethod = c("BH",
  "Bonferroni", "qval"), fpr = 0.01, peplen = 7, missedCleavages = 2,
  IisL = FALSE, identppm = 20, quantppm = 20, uniquepep = TRUE,
  span.rt = 0.05, span.int = 0.05, grid.ppm.from = 2, grid.ppm.to = 20,
  grid.ppm.by = 2, grid.nsd.from = 0.5, grid.nsd.to = 5,
  grid.nsd.by = 0.5, grid.imdiffs.from = 0.6, grid.imdiffs.to = 1.6,
  grid.imdiffs.by = 0.2, grid.subset = 1, grid.n = 0,
  grid.param.sel = c("auto", "model", "total", "details"), fm.ppm = 25,
  fm.ident.minIntensity = 70, fm.quant.minIntensity = 70,
  fm.minCommon = 1, fm.minDelta = 1, fm.fdr.unique = 0.05,
  fm.fdr.nonunique = 0.05, mergedEMRTs = c("rescue", "copy", "transfer"),
  template = system.file("reports", "synergise2.Rmd", package = "synapter"),
  verbose = interactive())
}
\arguments{
\item{filenames}{A named \code{list} of file names to be load. The
names must be \code{identpeptide}, \code{quantpeptide},
\code{quantpep3d} and \code{fasta} (could be an RDS file created by
\code{link{createUniquePeptideDbRds}}). If fragmentmatching should be used
\code{identfragments} (could be skipped if a master RDS files is used for
\code{identpeptide}) and \code{quantspectra} have to be given as well.
\code{identpeptide} can be a \code{csv} final peptide file (from PLGS) or
a saved \code{"\linkS4class{MasterPeptides}"} data object as created by
\code{\link{makeMaster}} if working with \emph{master} peptide data.
To serialise the \code{"\linkS4class{MasterPeptides}"} instance, use the
\code{saveRDS} function, and file extenstion \code{rds}.}

\item{master}{A \code{logical} indicating if the identification final
peptide files are master (see \code{\link{makeMaster}}) or
regular files. Default is \code{FALSE}.}

\item{object}{An instance of class \code{Synapter} that will be
copied,  processed and returned. If \code{filenames} are also
provided, the latter and \code{object}'s \code{inputFiles} will be
checked for equality.}

\item{outputdir}{A \code{character} with the full path to an
existing directory.}

\item{outputfile}{A \code{character} with the file name for the report.}

\item{fdr}{Peptide false discovery rate. Default is 0.01.}

\item{fdrMethod}{P-value adjustment method. One of \code{"BH"}
(default) for Benjamini and HochBerg (1995), \code{"Bonferroni"}
for Bonferroni's single-step adjusted p-values for strong control
of the FWER and \code{"qval"} from the \code{qvalue} package. See
\code{\link{Synapter}} for references.}

\item{fpr}{Protein false positive rate. Default is 0.01.}

\item{peplen}{Minimum peptide length. Default is 7.}

\item{missedCleavages}{Number of allowed missed cleavages. Default
is 2.}

\item{IisL}{If \code{TRUE} Isoleucin and Leucin are treated as equal.
In this case sequences like "ABCI", "ABCL" are removed because they are
not unqiue. If \code{FALSE} (default) "ABCI" and "ABCL" are reported as
unique.}

\item{identppm}{Identification mass tolerance (in ppm). Default is 20.}

\item{quantppm}{Quantitation mass tolerance (in ppm). Default is 20.}

\item{uniquepep}{A \code{logical} is length 1 indicating if only
unique peptides in the identification and quantitation peptides as
well as unique tryptic peptides as defined in the fasta
file. Default is \code{TRUE}.}

\item{span.rt}{The loess span parameter for retention time correction.
Default is 0.05.}

\item{span.int}{The loess span parameter for intensity correction.
Default is 0.05.}

\item{grid.ppm.from}{Mass tolerance (ppm) grid starting
value. Default is 2.}

\item{grid.ppm.to}{Mass tolerance (ppm) grid ending value. Default
is 20.}

\item{grid.ppm.by}{Mass tolerance (ppm) grid step value. Default
is 2.}

\item{grid.nsd.from}{Number of retention time stdev grid starting
value. Default is 0.5.}

\item{grid.nsd.to}{Number of retention time stdev grid ending
value. Default is 5.}

\item{grid.nsd.by}{Number of retention time stdev grid step
value. Default is 0.5.}

\item{grid.imdiffs.from}{Ion mobility difference grid starting value.
value. Default is 0.6.}

\item{grid.imdiffs.to}{Ion mobility difference grid ending value.
Default is 1.6.}

\item{grid.imdiffs.by}{Ion mobility difference grid step value.
Default is 0.2.}

\item{grid.subset}{Percentage of features to be used for the grid
search. Default is 1.}

\item{grid.n}{Absolute number of features to be used for the grid
search. Default is 0, i.e ignored.}

\item{grid.param.sel}{Grid parameter selection method. One of
\code{auto} (default), \code{details}, \code{model} or
\code{total}. See \code{\link{Synapter}} for details on these
selection methods.}

\item{fm.ppm}{Fragment Matching tolerance: Peaks in a range of \code{fm.ppm}
are considered as identical. Default is 25.}

\item{fm.ident.minIntensity}{Minimal intensity of a Identification fragment
to be not filtered prior to Fragment Matching.}

\item{fm.quant.minIntensity}{Minimal intensity of a peaks in a Quantitation
spectra to be not filtered prior to Fragment Matching.}

\item{fm.minCommon}{Minimal number of peaks that unique matches need to have
in common. Default 1.}

\item{fm.minDelta}{Minimal difference in number of peaks that non-unique matches need
to have to be considered as true match. Default 1.}

\item{fm.fdr.unique}{Minimal FDR to select \code{fm.minCommon} automatically
(if both values are given the more restrictive one (that filters more
fragments) is used). Default 0.05.}

\item{fm.fdr.nonunique}{Minimal FDR to select \code{fm.minDelta} automatically
(if both values are given the more restrictive one (that filters more
fragments) is used). Default 0.05.}

\item{mergedEMRTs}{One of \code{"rescue"} (default), \code{"copy"}
or \code{"transfer"}. See the documentation for the
\code{findEMRTs} function in \code{\link{Synapter}} for details.}

\item{template}{A \code{character} full path to Rmd template.}

\item{verbose}{A \code{logical} indicating if progress output
should be printed to the console. Default is \code{TRUE}.}
}
\value{
Invisibly returns an object of class \code{Synapter}.
        Used for its side effect of creating an html report of
        the run in \code{outputdir}.
}
\description{
Performs a complete default analysis on the files defined
in \code{filenames}, creates a complete html report and
saves/exports all results as \code{csv} and \code{rds} files.
See details for a description of the pipeline and
\code{\link{Synapter}} for manual execution of individual steps.
}
\details{
In contrast to \code{\link{synergise1}} \code{synergise2} extends the
default analysis and offers the follwing unique features:
\itemize{
  \item Performing 3D grid search (M/Z, Retention Time, Ion Mobility) for
        HDMSE data.
  \item Applying intensity correction.
  \item Filtering results by fragment matching.
}

Data can be input as a \code{\link{Synapter}} object if available or
as a list of files (see \code{filenames}) that will be used to read the
data in. The html report and result files will be created in the
\code{outputdir} folder. All other input parameters have default values.

The data processing and analysis pipeline is as follows:
\enumerate{
 \item If \code{uniquepep} is set to TRUE (default), only unique
       proteotypic identification and quantitation peptides are retained.
 \item Peptides are filtered for a FDR <= \code{fdr} (default is 0.01)
       using the "BH" method (see \code{fdr} and \code{fdrMethod}
       parameters for details).
 \item Peptide with a mass tolerance > 20 ppms (see \code{quantppm} and
       \code{identppm}) are filtered out.
 \item Peptides with a protein false positive rate (as reported by the
       PLGS software) > \code{fpr} are filtered out.
 \item Common identification and quantitation peptides are merged and a retention time
       model is created using the Local Polynomial Regression Fitting
       (\code{\link{loess}} function for the \code{stats} package) using
       a default \code{span.rt} value of 0.05.
 \item A grid search to optimise the width in retention time and mass
       tolerance (and ion mobility for HDMSE) for EMRTs matching is performed.
       The default grid search space is from 0.5 to 5 by 0.5 retention time
       model standard deviations (see \code{grid.nsd.from}, \code{grid.nsd.to} and
       \code{grid.nsd.by} parameters) and from 2 to 20 by 2 parts per
       million (ppm) for mass tolerance (see \code{grid.ppm.from},
       \code{grid.ppm.to} and \code{grid.ppm.by} parameters). If HDMSE data
       are used the search space is extended from ion mobility difference
       0.6 to 1.6 by 0.2 (see \code{grid.imdiffs.from}, \code{grid.imdiffs.to}
       and \code{grid.imdiffs.by}).
       The data can be subset using using an absolute number of features
       (see \code{grid.n}) or a fixed percentage (see \code{grid.subset}).
       The pair of optimal \code{nsd} and \code{ppm} is chosen
       (see \code{grid.param.sel} parameter).
 \item Fragment Matching is used to filter false-positive matches from the
       grid search using a default of 1 common peak for unique matches and
       at least a difference of 1 common peaks to choose the correct match
       out of non-unique matches (see \code{fm.minCommon} and
       \code{fm.minDelta}).
 \item The intensity is corrected by a Local Polynomial Regression Fitting
       (\code{\link{loess}} function for the \code{stats} package) using a
       default \code{span.int} value of 0.05.
 \item The quantitation EMRTs are matched using the optimised parameters.
}
If a master identification file is used (\code{master} is set to \code{TRUE}, default
is \code{FALSE}), the relevant actions that have already been executed when
the file was created with \code{\link{makeMaster}} are not repeated here.
}
\examples{
\dontrun{
library(synapterdata)
data(synobj2)
output <- tempdir() ## a temporary directory
synergise2(object = synobj2, outputdir = output, outputfile = "synapter.html")
htmlReport <- paste0("file:///", file.path(output, "synapter.html")) ## the result report
browseURL(htmlReport) ## open the report with default browser
}
}
\references{
Bond N. J., Shliaha P.V., Lilley K.S. and Gatto
L. (2013) J. Prot. Research.
}
\author{
Laurent Gatto, Sebastian Gibb
}
