R/SynSigRun.R

In WuyangFF95/SynSigRun: Run Mutational Signature Analysis Software Packages Using Mutational Spectra generated by SynSigGen

#' @title \code{SynSigRun}: An easy-to-use package for non-experts which runs software
#' packages reproducibly with synthetic tumors generated by \code{SynSigGen}.
#'
#' @description \code{SynSigRun} gives necessary information to mutational-signature analysis
#' programs. These programs used catalogs of synthetic mutational spectra created
#' by package \code{SynSigGen}, and results were assessed by \code{SynSigEval}.
#'
#' @details # Workflow
#' Typical workflow for conducting a mutational signature analysis with
#' mutational spectra is as follows.
#'
#' ## Input mutational spectra
#' Mutational spectra can be obtained from vcf files of real samples
#' (see "Importing mutational spectra from \code{ICAMS}"). Mutational spectra
#' can also be generated in-silico by R package \code{SynSigGen}, and then
#' imported by \code{ICAMS}
#' (see "(In SynSigGen) Creating Synthetic Mutational Spectra").
#'
#' ### Importing mutational spectra from \code{ICAMS}
#'
#' Relevant functions are: \enumerate{
#'
#' \item \code{ReadCatalog}
#' \item \code{StrelkaSBSVCFFilesToCatalog}
#' \item \code{StrelkaIDVCFFilesToCatalog}
#' \item \code{MutectVCFFilesToCatalog}
#'
#' }
#'
#' See \code{ICAMS} package documentation for more details.
#'
#' ### (In \code{SynSigGen}) Creating Synthetic Mutational Spectra
#'
#' These functions create synthetic mutational spectra based
#' on parameters derived from mutational signature profiles
#' and exposures.
#'
#' Relevant functions for generate exposures are: \enumerate{
#'
#' \item \code{GenerateSynFromReal}
#' \item \code{GenerateSyntheticExposures}
#' \item \code{GenSBS1SBS5Exposure}
#'
#' }
#'
#' After generating exposures for spectra dataset, \code{SynSigGen} used
#' these functions to generate mutational spectra: \enumerate{
#'
#' \item \code{CreateFromReal}
#' \item \code{CreateMixedTumorTypeSyntheticData}
#' \item \code{CreateRandomSyn}
#" \item \code{CreateSBS1SBS5CorrelatedSyntheticData}
#'
#' }
#'
#' See \code{SynSigGen} package documentation for more details.
#'
#' ## (In \code{SynSigRun}) Run mutational analysis computational approaches
#'
#' Relevant functions are: \enumerate{
#'
#' \item \code{\link{RunhdpLessHier}}
#' \item \code{\link{Runmaftools}}
#' \item \code{\link{RunMutationalPatterns}}
#' \item \code{\link{RunsigneR}}
#' \item \code{\link{Runtcsm}}
#'
#' }
#'
#' ## (In \code{SynSigEval}) Summarize results
#'
#' Summarize results of of signature extraction
#' and exposure inference (a.k.a. signature attribution):
#'
#' Relevant functions are: \enumerate{
#'
#' \item \code{SummarizeSigOnehelmsmanSubdir}
#' \item \code{SignatureAnalyzerSummarizeTopLevel}
#' \item \code{SignatureAnalyzerSummarizeSBS1SBS5}
#' \item \code{SummarizeSigOneSigProExtractorSubdir}
#' \item \code{SummarizeSigProExtractor}
#' \item \code{SummarizeSigOneExtrAttrSubdir}
#'
#'
#' }
#'
#' Package \code{SynSigEval} uses functions in \code{ICAMSxtra}
#' to compare two sets of mutational signatures.
#' Often we will be interested in comparing signature profiles
#' extracted from synthetic data to the
#' ground-truth signature profiles: \enumerate{
#'
#' \item \code{Match1Sig}
#' \item \code{MatchSigs1Direction}
#' \item \code{MatchSigs2Directions}
#' \item \code{MatchSigsAndRelabel}
#'
#' }
#'
#' # Folder structure for \code{SynSigRun} and \code{SynSigEval}:
#'
#' Summary function will fit to the new 5-level folder structure:
#'
#' First Level - \code{top.level.dir}: dataset folder (e.g. "S.0.1.Rsq.0.1", "syn.pancreas").
#' All spectra datasets under any top.level.dir have the same exposure.
#'
#' Second Level - \code{ground.truth.exposure.dir}: spectra folder: (e.g. "sp.sp", "sa.sa.96").
#' All spectra datasets under any second.level.dir have the same signature and
#' the same exposure counts.
#'
#' Third Level - \code{third.level.dir}: \enumerate{
#'
#' \item It can be ("Attr") for storing results of packages
#' which can only do signature attribution of known signatures ("Attr");
#'
#' \item It can be ("ExtrAttr"), folder to store results of computational approaches which
#' can do de-novo extraction and following attribution, without knowing the number of ground-truth
#' mutational signatures active in the spectra data set.
#'
#' \item It can also be ("ExtrAttrExact"), folder to store results of computational approaches
#' which can do de-novo extraction and following attribution, given the number of ground-truth
#' mutational signatures active in the spectra data set.
#' }
#'
#' Fourth Level - \code{tool.dir}: The results of a computational approach
#' (e.g. "sigproextractor.results","SignatureEstimation.QP.results").
#' Under this level, \code{tool.dir} may contain multiple \code{run.dir},
#' each is a run of the computational approach using a specific number of seed.
#'
#' Fifth level - \code{run.dir}: contains results from a run of the computational approach
#' using a specific number of seed. (e.g. "seed.1")
#'
#'
#' @docType package
#' @name SynSigRun
#'
#' @md
NULL