reporting-legacy: Report feature group data (legacy interface)

In rickhelmus/patRoon: Workflows for Mass-Spectrometry Based Non-Target Analysis

Report feature group data (legacy interface)

Description

Functionality to report data produced by most workflow steps such as features, feature groups, calculated chemical formulae and tentatively identified compounds. This is the legacy interface, for the updated interface see reporting.

Usage

reportCSV(
  fGroups,
  path = "report",
  reportFeatures = FALSE,
  formulas = NULL,
  formulasNormalizeScores = "max",
  formulasExclNormScores = NULL,
  compounds = NULL,
  compoundsNormalizeScores = "max",
  compoundsExclNormScores = c("score", "individualMoNAScore", "annoTypeCount",
    "annotHitCount", "libMatch"),
  compsCluster = NULL,
  components = NULL,
  retMin = TRUE,
  clearPath = FALSE
)

reportPDF(
  fGroups,
  path = "report",
  reportFGroups = TRUE,
  formulas = NULL,
  formulasTopMost = 5,
  formulasNormalizeScores = "max",
  formulasExclNormScores = NULL,
  reportFormulaSpectra = TRUE,
  compounds = NULL,
  compoundsNormalizeScores = "max",
  compoundsExclNormScores = c("score", "individualMoNAScore", "annoTypeCount",
    "annotHitCount", "libMatch"),
  compoundsOnlyUsedScorings = TRUE,
  compoundsTopMost = 5,
  compsCluster = NULL,
  components = NULL,
  MSPeakLists = NULL,
  retMin = TRUE,
  EICGrid = c(2, 1),
  EICParams = getDefEICParams(rRtWindow = 20, topMost = 1, topMostByRGroup = TRUE),
  clearPath = FALSE
)

reportHTML(
  fGroups,
  path = "report",
  reportPlots = c("chord", "venn", "upset", "eics", "formulas"),
  formulas = NULL,
  formulasTopMost = 5,
  formulasNormalizeScores = "max",
  formulasExclNormScores = NULL,
  compounds = NULL,
  compoundsNormalizeScores = "max",
  compoundsExclNormScores = c("score", "individualMoNAScore", "annoTypeCount",
    "annotHitCount", "libMatch"),
  compoundsOnlyUsedScorings = TRUE,
  compoundsTopMost = 5,
  compsCluster = NULL,
  includeMFWebLinks = "compounds",
  components = NULL,
  interactiveHeat = FALSE,
  MSPeakLists = NULL,
  specSimParams = getDefSpecSimParams(),
  TPs = NULL,
  retMin = TRUE,
  EICParams = getDefEICParams(rtWindow = 20, topMost = 1, topMostByRGroup = TRUE),
  TPGraphStructuresMax = 25,
  selfContained = TRUE,
  optimizePng = FALSE,
  clearPath = FALSE,
  openReport = TRUE,
  noDate = FALSE
)

## S4 method for signature 'featureGroups'
reportCSV(
  fGroups,
  path = "report",
  reportFeatures = FALSE,
  formulas = NULL,
  formulasNormalizeScores = "max",
  formulasExclNormScores = NULL,
  compounds = NULL,
  compoundsNormalizeScores = "max",
  compoundsExclNormScores = c("score", "individualMoNAScore", "annoTypeCount",
    "annotHitCount", "libMatch"),
  compsCluster = NULL,
  components = NULL,
  retMin = TRUE,
  clearPath = FALSE
)

## S4 method for signature 'featureGroups'
reportPDF(
  fGroups,
  path = "report",
  reportFGroups = TRUE,
  formulas = NULL,
  formulasTopMost = 5,
  formulasNormalizeScores = "max",
  formulasExclNormScores = NULL,
  reportFormulaSpectra = TRUE,
  compounds = NULL,
  compoundsNormalizeScores = "max",
  compoundsExclNormScores = c("score", "individualMoNAScore", "annoTypeCount",
    "annotHitCount", "libMatch"),
  compoundsOnlyUsedScorings = TRUE,
  compoundsTopMost = 5,
  compsCluster = NULL,
  components = NULL,
  MSPeakLists = NULL,
  retMin = TRUE,
  EICGrid = c(2, 1),
  EICParams = getDefEICParams(),
  clearPath = FALSE
)

## S4 method for signature 'featureGroups'
reportHTML(
  fGroups,
  path = "report",
  reportPlots = c("chord", "venn", "upset", "eics", "formulas"),
  formulas = NULL,
  formulasTopMost = 5,
  formulasNormalizeScores = "max",
  formulasExclNormScores = NULL,
  compounds = NULL,
  compoundsNormalizeScores = "max",
  compoundsExclNormScores = c("score", "individualMoNAScore", "annoTypeCount",
    "annotHitCount", "libMatch"),
  compoundsOnlyUsedScorings = TRUE,
  compoundsTopMost = 5,
  compsCluster = NULL,
  includeMFWebLinks = "compounds",
  components = NULL,
  interactiveHeat = FALSE,
  MSPeakLists = NULL,
  specSimParams = getDefSpecSimParams(),
  TPs = NULL,
  retMin = TRUE,
  EICParams = getDefEICParams(rtWindow = 20, topMost = 1, topMostByRGroup = TRUE),
  TPGraphStructuresMax = 25,
  selfContained = TRUE,
  optimizePng = FALSE,
  clearPath = FALSE,
  openReport = TRUE,
  noDate = FALSE
)

Arguments

fGroups	The featureGroups object that should be used for reporting data.
path	The destination file path for files generated during reporting. Will be generated if needed.
reportFeatures	If set to TRUE then for each analysis a ‘.csv’ file will be generated with information about its detected features.
formulas, compounds, compsCluster, components	Further objects (formulas, compounds, compoundsCluster, components) that should be reported. Specify NULL to skip reporting a particular object.
compoundsNormalizeScores, formulasNormalizeScores	A character that specifies how normalization of annotation scorings occurs. Either "none" (no normalization), "max" (normalize to max value) or "minmax" (perform min-max normalization). Note that normalization of negative scores (e.g. output by SIRIUS) is always performed as min-max. Furthermore, currently normalization for compounds takes the original min/max scoring values into account when candidates were generated. Thus, for compounds scoring, normalization is not affected when candidate results were removed after they were generated (e.g. by use of filter).
compoundsExclNormScores, formulasExclNormScores	A character vector specifying any compound scoring names that should not be normalized. Set to NULL to normalize all scorings. Note that whether any normalization occurs is set by the compoundsExclNormScores,formulasExclNormScores argument. For compounds: By default score and individualMoNAScore are set to mimic the behavior of the MetFrag web interface.
retMin	If TRUE then report retention times in minutes (otherwise seconds).
clearPath	If TRUE then the destination path will be (recursively) removed prior to reporting.
reportFGroups	If TRUE then feature group data will be reported.
formulasTopMost, compoundsTopMost	Only this amount of top ranked candidate formulae/compounds are reported. Lower values may significantly speed up reporting. Set to NULL to ignore.
reportFormulaSpectra	If TRUE then explained MS/MS spectra (if available) for candidate formulae will be reported. Specifying formulas and setting this argument to FALSE still allows further annotation of compound MS/MS spectra.
compoundsOnlyUsedScorings	If TRUE then only scorings are plotted that actually have been used to rank data (see the scoreTypes argument to generateCompoundsMetFrag for more details).
MSPeakLists	A MSPeakLists object that is mandatory when spectra for formulae and/or compounds will be reported.
EICGrid	An integer vector in the form c(columns, rows) that is used to determine the plotting grid when reporting EICs in PDF files.
EICParams	A named list with parameters used for extracted ion chromatogram (EIC) creation. See the EIC parameters documentation for more details.
reportPlots	A character vector specifying what should be plotted. Valid options are: "chord", "venn", "upset" (plot a chord, Venn and UpSet diagram, respectively), "eics" (plot EICs for individual feature groups) and "formulas" (plot annotated formula spectra). Set to "none" to plot none of these.
includeMFWebLinks	A character specifying to which feature groups a web link should be added in the annotation page to MetFragWeb. Options are: "compounds" (only to those with compounds results), "MSMS" (only to those with MSMS peak lists) or "none".
interactiveHeat	If TRUE an interactive heatmap HTML widget will be generated to display hierarchical clustering results. Set to FALSE for a 'regular' static plot.
specSimParams	A named list with parameters that influence the calculation of MS spectra similarities. See the spectral similarity parameters documentation for more details.
TPs	A transformationProducts object that should used for plotting hierarchies. Ignored if TPs=NULL or components is not a componentsTPs object.
TPGraphStructuresMax	Maximum number of TP structures to plot in TP hierarchies, see the TPs argument. Sets the structuresMax argument to plotGraph.
selfContained	If TRUE the output will be a standalone HTML file which contains all graphics and script dependencies. When FALSE, the latter will be placed in an additional directory (‘report_files’) which should remain present when viewing the output file. Especially on Windows, a non-self contained output might be desirable when reporting large amounts of data to prevent pandoc from running out of memory.
optimizePng	If TRUE then pngquant is used to reduce the size of generated graphics. A significant reduction in disk space usage may be seen, however, at the cost additional processing time. Multiple pngquant processes will be executed in parallel, which can be configured with patRoon.MP.maxProcs (parallelization will always happen with the "classic" method, see patRoon options).
openReport	If set to TRUE then the output report file will be opened with the system browser.
noDate	If TRUE then the current date is not added to the report. This is mainly used for testing and its main purpose is to guarantees equal report files when reportHTML() is called multiple times with equal arguments.

Details

These functions are usually called at the very end of the workflow. It is used to report various data on features and feature groups. In addition, these functions may be used for reporting formulae and/or compounds that were generated for the specified feature groups. Data can be reported in tabular form (i.e. ‘.csv’ files) by reportCSV or graphically by reportPDF and reportHTML. The latter functions will plot for instance chromatograms and annotated mass spectra, which are useful to get a graphical overview of results.

All functions have a wide variety of arguments that influence the reporting process. Nevertheless, most parameters are optional and only required to be given for fine tuning. In addition, only those objects (e.g. formulae, compounds, clustering) that are desired to be reported need to be specified.

reportCSV generates tabular data (i.e. ‘.csv’ files) for given data to be reported. This may also be useful to allow import by other tools for post processing.

reportPDF will report graphical data (e.g. chromatograms and mass spectra) within PDF files. Compared to reportHTML this function may be faster and yield smaller report files, however, its functionality is a bit more basic and generated data is more 'scattered' around.

reportHTML will report graphical data (e.g. chromatograms and mass spectra) and summary information in an easy browsable HTML file using rmarkdown, flexdashboard and knitr.

Parallelization

reportHTML uses multiprocessing to parallelize computations. Please see the parallelization section in the handbook for more details and patRoon options for configuration options.

Currently, reportHTML only uses "classic" multiprocessing, regardless of the patRoon.MP.method option.

Note

Any formulae and compounds for feature groups which are not present within fGroups (i.e. because it has been subset afterwards) will not be reported.

The topMost, topMostByRGroup and onlyPresent EIC parameters may be ignored, e.g., when generating overview plots.

References

Creating MetFrag landing page URLs based on code from MetFamily R package.

\addCitationsknitr2

\addCitationsknitr3

See Also

reporting

rickhelmus/patRoon documentation built on Nov. 22, 2024, 3:11 p.m.