5.9 Reporting

The previous sections showed various functionality to inspect and visualize results. An easy way to do this automatically is by using the reporting functionality of patRoon. There are currently two interfaces: a legacy interface that is described in the next subsection, and the modernized version discussed here.

The reports are generated by the report() function, which combines the data generated during the workflow. This function outputs an HTML file (other formats may follow in future versions), which can be opened with a regular web browser to interactively explore and visualize the data. The report combines chromatograms, mass spectra, tables with feature and annotation properties and many other useful ways to easily explore your data.

Which data is reported is controlled by the following function arguments:

Argument	Description
`fGroups`	The `featureGroups` object that should be reported (mandatory).
`MSPeakLists`	The MS peak lists object used for annotations (mandatory if `formulas`/`compounds` are specified).
`formulas`, `compounds`	The `formulas` and `compounds` objects that should be used to report feature annotations.
`compsCluster`	The result object from compound clustering.
`components`	Any componentization results, e.g. with adduct annotations and from transformation product screening.
`TPs`	Output from object from generated transformation products.

Most of these arguments are optional, and if not specified this part of the workflow is simply not reported. This also means that reporting can be performed at every stage during the workflow, which, for instance, can be useful to quickly inspect results when testing out various settings to generate workflow data. More advanced arguments to report() are discussed in the reference manual (?reporting).

Some examples:

report(fGroups) # only report feature groups
report(fGroups[, 1:50]) # same, but only first 50, e.g. to do a quick inspection

# include feature annotations
report(fGroups, MSPeakLists = mslists, formulas = formulas, compounds = compounds)

# TP screening
report(fGroups, MSPeakLists = mslists, formulas = formulas, compounds = compounds,
           components = componentsTP, TPs = TPs)

The report itself is primarily configured through a report settings file, which is an easily editable YAML file. The default file is as follows:

general:
    version: 2
    format: html
    path: report
    keepUnusedPlots: 7
    selfContained: false
    noDate: false
summary: [ chord, venn, upset ]
features:
    retMin: true
    chromatograms:
        large: true
        small: true
        features: false
        intMax: eic
    intensityPlots: false
    aggregateConcs: mean
    aggregateTox: mean
MSPeakLists:
    spectra: true
formulas:
    include: true
    normalizeScores: max
    exclNormScores: [ ]
    topMost: 25
compounds:
    normalizeScores: max
    exclNormScores: [ score, individualMoNAScore, annoTypeCount, annotHitCount, libMatch ]
    onlyUsedScorings: true
    topMost: 25
TPs:
    graphs: true
    graphStructuresMax: 25
internalStandards:
    graph: true

A detailed description for all the settings can be found in the reference manual (?reporting). The table below summarizes the most interesting options:

Parameter	Description
`general --> format`	The output format. Currently only `"html"`.
`general --> selfContained`	If set (`true`) then the output will be a self contained `.html` file. Handy to share reports, but not recommended for large amounts of data.
`features --> chromatograms --> features`	If enabled (`true`) then the report includes chromatograms of individual features. If set to `all` then also chromatograms are generated for analyses in which a feature was not detected. This is especially useful to inspect if features were ‘missed’ during feature detection or accidentally removed after a filter step.
`formulas/compounds --> topMost`	Specifies the maximum number of top-ranked candidates to plot. Often it will take a considerable amount of time to report all candidates, hence, by default this is limited.

When the newProject tool is used to create a new patRoon project a template settings file (report.yml) is automatically created. Otherwise, this file can be generated with the genReportSettingsFile() function. Simply running this function without any arguments is enough:

genReportSettingsFile()

5.9.1 Legacy interface

The legacy interface was the default reporting interface for patRoon versions older than 2.2. The interface now mainly serves for backward compatibility reasons, but may still be useful since the new interface does not (yet) support all the formats from the legacy interface. The following three reporting functions are available:

reportCSV(): exports workflow data to comma-separated value (csv) files
reportPDF(): generates simple reports by plotting workflow data in portable document files (PDFs)
reportHTML(): generates interactive and easily explorable reports

Like the report() function described above, the arguments to these functions control which data will be reported. However, these functions do not use a report settings file, and all configuration happens through function arguments. Some common arguments are listed below; for a complete listing see the reference manual (?`reporting-legacy`).

Argument	Functions	Remarks
`fGroups`, `formulas`, `compounds`, `formulas`, `components`, `compsCluster`, `TPs`	All	Objects to plot. Only `fGroups` is mandatory.
`MSPeakLists`	`reportPDF()`, `reportHTML()`	The `MSPeakLists` object that was used to generate annotation data. Only needs to be specified if `formulas` or `compounds` are reported.
`path`	All	Directory path where report files will be stored (`"report"` by default).
`formulasTopMost`, `compoundsTopMost`	`reportPDF()`, `reportHTML()`	Report no more than this amount of highest ranked candidates.
`selfContained`	`reportHTML()`	Outputs to a single and self contained `.html` file. Handy to share reports, but not recommended for large amounts of data.

Some typical examples:

reportHTML(fGroups) # simple interactive report with feature data
# generate PDFs with feature and compound annotation data
reportPDF(fGroups, compounds = compounds, MSPeakLists = mslists)
reportCSV(fGroups, path = "myReport") # change destination path

# generate report with all workflow types and increase maximum number of
# compound candidates to top 10
reportHTML(fGroups, formulas = formulas, compounds = compounds,
           components = components, MSPeakLists = mslists,
           compsCluster = compsClust,
           compoundsTopMost = 10)