Updating final report

[mgeaghan]

This PR updates the final pipeline report with helpful explanatory text to guide users through interpreting the results and how to re-run the workflow with updated parameters if need be.

The update also adds the samplesheet, custom marker genes, and comparisons CSV files to the report module so that information can be included in the report.

An example report can be found on SharePoint

[georgiesamaha]

Looking great. A few suggestions I think might make the report more immediately useful up front for users.

A methods section for publications

The explanatory text scattered across pages describes methodology, but there's no consolidated, copy-pasteable methods paragraph. For users who need to write up their analysis, they'd have to synthesise across 10 pages. The report would benefit from a dedicated methods.qmd page or just in the index/home page with a structured write-up: tools used, versions, parameters applied, and citations.

An executive summary of findings

The index page lists what ran and shows the samplesheet, but gives no high-level results. A user should be able to open the report and immediately read:

• Cells retained after filtering: X
• Clusters identified: N (at resolution Y)
• Cell types annotated: [list]
• DE comparisons run: N (X significant genes found)

Looks like all these numbers exist in the underlying data, would be great to surface at the top if its not too tricky.

Consolidate parameters

Filtering thresholds are shown in qc_filter.html, but clustering resolution chosen, integration parameters, and annotation settings aren't presented together. A "Parameters used" table on the index page (pulling from the metadata files already staged by report.nf) would make the report self-contained for reproducibility.

Rendered analysis_ora.qmd

File exists in assets/ but no analysis_ora.html appears in the rendered output example on sharepoint. Apologies if I've just missed this.

Explanatory text is method-oriented, not results-oriented

The added text explains how the methods work, which is great as background, but users of a service report primarily want interpretation guidance: "what should I look for in this plot?", "what does a good p-value distribution look like vs. a bad one?", "how do I choose a resolution from this clustree?" The text is moving in the right direction and would benefit from some connection between methods and guidance if its not too tricky.

[georgiesamaha]

would be great if we could also output the final rendered html in addition to the reports.tar so we can email this to clients in the handover process separately from the whole report directory.

[mgeaghan]

@georgiesamaha I've made the following changes:

• Made the report a single-page HTML for easy sharing.
• Fixed the issue with ORA not appearing in the final report
• Added a methods section in a callout, which includes the run command (inspired by nf-core)
• Added an analysis summary section with:
  • A table of # samples, # filtered cells, avg. cells per sample, # clusters, # comparisons, and total # DE genes detected
  • A table of cell types identified and the number of clusters assigned to each
  • A reproduction of the sample sheet
  • A table of all parameters set (including default values)
• Reduced some of explanatory text to focus on the interpretations of plots/tables/etc.
  • Also removed explanations on how to set parameters, e.g. cluster resolutions (rationale: this is a final summary report, explanations for how to run things belong in the README)
• Added a table of software versions to the end of the report.

Example report: report.cohort.html