Reports

Most Nextflow pipelines will generate reports or output files which are useful to inspect at the end of the pipeline execution. Reports may be in various formats (e.g. HTML, PDF, TXT) and would typically contain quality control (QC) metrics that would be important to assess the integrity of the results.

Reports allow you to directly visualise supported file types or to download them via the user interface (see Limitations). This saves users the time and effort of having to retrieve and visualize output files from their local storage.

Visualize reports

Available reports are listed in a Reports tab on the Runs page. You can select a report from the table to view or download it (see Limitations for supported file types and sizes).

To open a report preview, the file must be smaller than 10 MB.

You can download a report directly or from the provided file path. Reports larger than 25MB cannot be downloaded directly — the option to download from file path is given instead.

Configure reports

Create a config file that defines the paths to a selection of output files published by the pipeline for Seqera to render reports. There are 2 ways to provide the config file, both of which have to be in YAML format:

1. Pipeline repository: If a file called tower.yml exists in the root of the pipeline repository then this will be fetched automatically before the pipeline execution.
2. Seqera Platform interface: Provide the YAML definition within the Advanced options > Seqera Cloud config file box when:
   • Creating a pipeline in the Launchpad.
   • Amending the launch settings during pipeline launch. This is available to users with the Maintain role only.

caution

Any configuration provided in the interface will override configuration supplied in the pipeline repository.

Configure reports for Nextflow CLI runs

The reports and log files for pipeline runs launched with Nextflow CLI (nextflow run <pipeline> -with-tower) can be accessed directly in the Seqera UI. The files generated by the run must be accessible to your Seqera workspace primary compute environment. Specify your workspace prior to launch by setting the TOWER_WORKSPACE_ID environment variable. Reports are listed under the Reports tab on the run details page.

Execution logs are available in the Logs tab by default, provided the output files are accessible to your workspace primary compute environment. To specify additional report files to be made available, your pipeline repository root folder must include a tower.yml file that specifies the files to be included (see below).

Reports implementation

Pipeline reports need to be specified using YAML syntax:

reports:
  <path pattern>:
    display: text to display (required)
    mimeType: file mime type (optional)

Path pattern

Only the published files (using the Nextflow publishDir directive) are candidate files for Seqera reports. The path pattern is used to match published files to a report entry. It can be a partial path, a glob expression, or just a file name.

Examples of valid path patterns are:

• multiqc.html: This will match all the published files with this name.
• **/multiqc.html: This is a glob expression that matches any subfolder. It's equivalent to the previous expression.
• results/output.txt: This will match all the output.txt files inside any results folder.
• *_output.tsv: This will match any file that ends with \_output.tsv.

caution

To use * in your path pattern, you must wrap the pattern in double quotes for valid YAML syntax.

Display

Display defines the title that will be shown on the website. If there are multiple files that match the same pattern, a suffix will be added automatically. The suffix is the minimum difference between all the matching paths. For example, given this report definition:

reports:
  "**/out/sheet.tsv":
    display: "Data sheet"

For paths /workdir/sample1/out/sheet.tsv and /workdir/sample2/out/sheet.tsv, both match the path pattern. The final display name will for these paths will be Data sheet (sample1) and Data sheet (sample2).

MIME type

By default, the MIME type is deduced from the file extension, so you don't need to explicitly define it. Optionally, you can define it to force a viewer, for example showing a txt file as a tsv. It is important that it is a valid MIME-type text, otherwise it will be ignored and the extension will be used instead.

Built-in reports

Nextflow can generate a number of built-in reports:

• Execution report
• Execution timeline
• Trace file
• Workflow diagram (i.e. DAG)

In Nextflow version 24.03.0-edge and later, these reports can be included as pipeline reports in Seqera Platform. Specify them in tower.yml like any other file:

reports:
  "report.html":
    display: "Nextflow execution report"
  "timeline.html":
    display: "Nextflow execution timeline"
  "trace.txt":
    display: "Nextflow trace file"
  "dag.html":
    display: "Nextflow workflow diagram"

note

The filenames must match any custom filenames defined in the Nextflow config:

• Execution report: report.file
• Execution timeline: timeline.file
• Trace file: trace.file
• Workflow diagram: dag.file

Limitations

The current reports implementation limits rendering to the following formats: HTML, csv, tsv, pdf, and txt. In-page rendering/report preview is restricted to files smaller than 10 MB. Larger files need to be downloaded first.

The download is restricted to files smaller than 25 MB. Files larger than 25 MB need to be downloaded from the path.

YAML formatting validation checks both the tower.yml file inside the repository and the UI configuration box. The validation phase will produce an error message if you try to launch a pipeline with non-compliant YAML definitions.