Report feature group data (legacy interface)

Source: R/generics.R, R/report-legacy.R

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.

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 class '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 class '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 class '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.

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.

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.

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.

References

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

Xie Y (2014). “knitr: A Comprehensive Tool for Reproducible Research in R.” In Stodden V, Leisch F, Peng RD (eds.), Implementing Reproducible Computational Research. Chapman and Hall/CRC. ISBN 978-1466561595.

Xie Y (2015). Dynamic Documents with R and knitr, 2nd edition. Chapman and Hall/CRC, Boca Raton, Florida. ISBN 978-1498716963, https://yihui.org/knitr/.

Xie Y (2025). knitr: A General-Purpose Package for Dynamic Report Generation in R. R package version 1.50, https://yihui.org/knitr/.

See also

reporting