reporting: Report workflow data
In rickhelmus/patRoon: Workflows for Mass-Spectrometry Based Non-Target Analysis

report

R Documentation

Report workflow data

Description

Functionality to report data produced by most workflow steps such as features, feature groups, formula and compound annotations, and TPs.

Usage

report(
  fGroups,
  MSPeakLists = NULL,
  formulas = NULL,
  compounds = NULL,
  compsCluster = NULL,
  components = NULL,
  TPs = NULL,
  settingsFile = system.file("report", "settings.yml", package = "patRoon"),
  path = NULL,
  EICParams = getDefEICParams(topMost = 1, topMostByRGroup = TRUE),
  specSimParams = getDefSpecSimParams(),
  clearPath = FALSE,
  openReport = TRUE,
  parallel = TRUE,
  overrideSettings = list()
)

## S4 method for signature 'featureGroups'
report(
  fGroups,
  MSPeakLists = NULL,
  formulas = NULL,
  compounds = NULL,
  compsCluster = NULL,
  components = NULL,
  TPs = NULL,
  settingsFile = system.file("report", "settings.yml", package = "patRoon"),
  path = NULL,
  EICParams = getDefEICParams(topMost = 1, topMostByRGroup = TRUE),
  specSimParams = getDefSpecSimParams(),
  clearPath = FALSE,
  openReport = TRUE,
  parallel = TRUE,
  overrideSettings = list()
)

genReportSettingsFile(out = "report.yml", baseFrom = NULL)

Arguments

`fGroups`	The `featureGroups` object that should be used for reporting data.
`MSPeakLists`, `formulas`, `compounds`, `compsCluster`, `components`, `TPs`	Further objects (`MSPeakLists`, `formulas`, `compounds`, `compoundsCluster`, `components`, `transformationProducts`) that should be reported. Specify `NULL` to skip reporting a particular object. Note that `MSPeakLists` must be set if either `formulas` or `compounds` is set.
`settingsFile`	The path to the report settings file used for report configuration (see `⁠Report settings⁠`).
`path`	The destination file path for files generated during reporting. Will be generated if needed. If `path=NULL` then the destination path is taken from the report settings (see below).
`EICParams`	A named `list` with parameters used for extracted ion chromatogram (EIC) creation. See the EIC parameters documentation for more details.
`specSimParams`	A named `list` with parameters that influence the calculation of MS spectra similarities. See the spectral similarity parameters documentation for more details.
`clearPath`	If `TRUE` then the report destination path will be (recursively) removed prior to reporting.
`openReport`	If set to `TRUE` then the output report file will be opened with the system browser.
`parallel`	If set to `TRUE` then code is executed in parallel through the futures package. Please see the parallelization section in the handbook for more details.
`overrideSettings`	A `list` with settings that override those from the report settings file. Example: `overrideSettings=list(compounds=list(topMost=25))`.
`out`	The output file path.
`baseFrom`	An existing report file to which the report settings should be based from. This is primarily used to update old settings files: the output settings file will be based on the old settings and amended with any missing.

Details

The reporting functionality is typically used at the very end of the workflow. It is used to overview the data generated during the workflow, such as features, their annotations and TP screening results.

report reports all workflow data in an interactive HTML file. The reports include both tabular data (e.g. retention times, annotation properties, screening results) and varios plots (e.g. chromatograms, (annotated) mass spectra and many more). This function uses functionality from other R packages, such as rmarkdown, flexdashboard, knitr and bslib.

The genReportSettingsFile function generates a new template ‘YAML’ file to configure report settings (see the next section).

Report settings

The report generation can be customized with a variety of settings that are read from a ‘YAML’ file. This is especially useful if you want to change more advanced settings or want to add or remove the parts that are reported The report settings file is specified through the settingsFile argument. If not specified then default settings will be used. To ease creation of a new template settings file, the genReportSettingsFile function can be used.

The following settings are currently available:

General
- format: the report format. Currently this can only be "html".
- path: the destination path (ignored if the path argument is specified).
- keepUnusedPlots: the number of days that unused plot files are kept (see ⁠Plot file caching⁠).
- selfContained: If true then the output ‘report.html’ embeds all graphics and script dependencies. Otherwise these files are read from the report_files/ directory. Self-contained reports are easily shared, since only the ‘report.html’ needs to be copied. However, they may be slower to generate and render, especially when the report contains a lot of data.
- noDate Set to true to omit the date from the report. Mainly used for internal purposes.
summary: defines the plots on the summary page: chord, venn and/or upset.
features
- retMin: if true then retention times are reported in minutes.
- chromatograms
  - large: inclusion of large chromatograms (used in feature group table and TP parent chromatogram view).
  - small: inclusion of small chromatograms (feature group table).
  - features: inclusion of chromatograms for individual features (features view). Set to all to also include plots for analyses in which a feature was not found (or removed afterwards).
  - intMax: Method to determine the maximum intensity plot range: eic or feature. Sets the intMax argument to plotChroms.
- intensityPlots: inclusion of intensity trend plots.
MSPeakLists
- spectra: inclusion of MS and MS/MS spectra (not annotated).
formulas
- include: whether formula results are reported (formula view). If false then the input formulas object is still used to amend e.g. compound annotated spectra.
- normalizeScores, exclNormScores: controls score normalization, sets the equally named arguments to e.g. plotScores.
- topMost only report this number of top ranked candidates. This number can be lowered to speed-up report generation.
compounds
- normalizeScores, exclNormScores, topMost: same as formulas, see above.
TPs
- graphs: inclusion of TP hierarchy graphs (generated with plotGraph).
- graphStructuresMax: maximum number of structures to plot in hierarchy graphs (sets structuresMax argument of plotGraph).
internalStandards
- graph: inclusion of internal standard network plot (plotGraph).

Plot file caching

When a new report is generated the plot files are stored inside the report_files sub-directory inside the destination path of the report. The plot files are kept so they can be reused to speed-up re-creation of reports (e.g. with different report settings). After the report is generated, any unused plot files are removed unless they were recently created (controlled by the keepUnusedPlots setting, see previous section). The clearPath argument can be used to completely remove any old files.

Note

No data will be reported for feature groups in any of the reported objects (formulas, compounds etc) which are not present in the input featureGroups object (fGroups).

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