Introduction Usage Parameters Output Releases

Introduction

This document describes the output produced by the pipeline. Most of the plots are taken from the MultiQC report, which summarises results at the end of the pipeline.

The directories listed below will be created in the results directory after the pipeline has finished. All paths are relative to the top-level results directory.

Pipeline overview

The pipeline is built using Nextflow and processes data using the following steps:

  • HMMER - If the pipeline is run in “search and place” mode, an initial HMMER search is performed to identify query sequences for placement
  • Alignment - Align query sequences to the reference alignment
  • Placement - Place query sequences in the reference phylogeny
  • Summary - Summarise placement with a grafted tree, a classification and a heattree
  • MultiQC - Aggregate report describing results and QC from the whole pipeline
  • Pipeline information - Report metrics generated during the workflow execution

Alignment

Alignment of query sequences is done either with HMMER, Clustal Omega or MAFFT.

HMMER

In the “search and place” mode of the pipeline, hmmsearch output files as well as a *.hmmrank.tsv.gz summarising the search is output.

When using HMMER as the alignment program, a profile is first built, which is then used to align both the query and reference sequences, hence the presence of alignment files for the reference sequences in the output. The realignment of the reference sequences is done because an alignment will likely result in a profile that doesn’t exactly reflect the structure of the alignment in all parts. In particular, gappy positions in the original alignment will typically not be covered by the profile. These positions are often not phylogenetically informative or reliable. The MAFFT alignment strategy keeps the structure of the original reference alignment.

Output files
  • hmmer/
    • *.query.hmmalign.sthlm.gz: Query sequences aligned to reference HMM, in Stockholm format.
    • *.query.hmmalign.masked.sthlm.gz: Masked query sequence alignment, in Stockholm format.
    • *.query.hmmalign.masked.afa.gz: Masked query sequence alignment, in Fasta format.
    • *.ref.hmmalign.sthlm.gz: Reference sequences aligned to reference HMM, in Stockholm format.
    • *.ref.hmmalign.masked.sthlm.gz: Masked query sequence alignment, in Stockholm format.
    • *.ref.hmmalign.masked.afa.gz: Masked query sequence alignment, in Fasta format.
    • *.ref.hmmbuild.txt: Log from HMM profile build.
    • *.ref.hmm.gz: HMM profile made from the reference alignment, if not provided using the hmmfile parameter.
    • *.ref.unaligned.afa.gz: “Unaligned”, i.e. without gap characters, reference sequences in Fasta format.
    • *.tbl.gz: Per-sequence hit table (--tblout) for individual hmmsearch runs in “search and place” mode
    • *.domtbl.gz: Per-domain hit table (--domtblout) for individual hmmsearch runs in “search and place” mode, only written when --save_domtblout is set. Unlike the per-sequence table, this one carries alignment coordinates for each domain, which are needed to work out profile coverage or to find genes split over several ORFs.
    • *.txt.gz: Standard, human-readable, format results for individual hmmsearch runs in “search and place” mode
    • *.hmmrank.tsv.gz: Summarised hmmsearch results, one row per sequence and profile, ranking the profiles that matched each sequence. When --save_domtblout is set, each row also carries the lengths of the sequence (tlen) and the profile (qlen), plus four columns for each of the three coordinate sets HMMER reports: hmm (position in the profile), ali (the aligned part of the sequence) and env (the wider region the alignment is likely to lie within). For a set x, x_from and x_to are the outer bounds of the match, while x_len is how much of that span the sequence’s domains actually cover, so a hit whose domains are scattered has an x_len well below x_to - x_from. x_n_islands counts the separate stretches that coverage falls into: 1 for a single continuous match, more when the domains are broken up. The two lengths are the denominators for coverage, each belonging to a different coordinate set: hmm positions are in the profile, so hmm_len / qlen is the proportion of the profile a hit covers, while ali and env positions are in the sequence, so ali_len / tlen is the proportion of the sequence the alignment takes up (env_len / tlen for the looser envelope). Mixing them, say hmm_len / tlen, compares a profile position against a sequence length and means nothing. For the profile, hmm_from - 1 and qlen - hmm_to also tell you how much is missing from each of its ends. Coverage counts every domain HMMER reported, however weak on its own; which sequences are reported at all is still decided by the full-sequence scores, exactly as when the coordinates are not requested. A sequence is reported at all on the per-sequence threshold, whereas a domain has to clear the per-domain one, so a hit can be ranked here with no domain records behind it at all. Those rows carry NA in every column above, which is deliberate: an empty value is the clearest signal that hmmsearch reported no domains for the hit, and it keeps such rows distinguishable from ones whose coordinates were genuinely computed.

Clustal Omega

Output files
  • clustalo/
    • *.aln: Full alignment, containing both reference and query sequences.

MAFFT

When MAFFT is used for alignment, it us run with the --keeplength option to ensure the structure of the query alignment is identical to the reference alignment. Since the resulting alignment contains both query and reference sequences it needs to be split, which is done with EPA-NG which places two files in the epang directory.

Output files
  • mafft/
    • *.fas: Full alignment, containing both reference and query sequences.
  • epang/
    • *.query.fasta.gz: Aligned query sequences in Fasta format.
    • *.reference.fasta.gz: Aligned query sequences in Fasta format.

Placement

Phylogenetic placement of query sequences is performed with EPA-NG.

Output files
  • epang/
    • *.epa_info.log: Log file from phylogenetic placement with EPA-NG.
    • *.epa_result.jplace.gz: Main result file from EPA-NG in jplace format.

Summary

A number of summary operations are performed with Gappa after placement. First, the query sequences are grafted on to the reference tree to produce a comprehensive tree containing all sequences. Second, the “heattree” function is called which produces phylogenies in different formats with branches coloured to indicate the number of placed sequences in various parts of the tree. Third, if the user provides a classification of the reference sequences, a classification of query sequences is performed.

Output files
  • gappa/
    • *.graft.*.newick: Full phylogeny with query sequences grafted on to the reference phylogeny.
    • *.heattree.*: Files from calling gappa examine heattree, see Gappa documentation for details.
    • *.taxonomy.*: Classification files from calling gappa examine examinassign, see Gappa documentation for details.

MultiQC

Output files
  • multiqc/
    • multiqc_report.html: a standalone HTML file that can be viewed in your web browser.
    • multiqc_data/: directory containing parsed statistics from the different tools used in the pipeline.
    • multiqc_plots/: directory containing static images from the report in various formats.

MultiQC is a visualization tool that generates a single HTML report summarising all samples in your project. Most of the pipeline QC results are visualised in the report and further statistics are available in the report data directory.

Results generated by MultiQC collate pipeline QC from supported tools e.g. FastQC. The pipeline has special steps which also allow the software versions to be reported in the MultiQC output for future traceability. For more information about how to use MultiQC reports, see http://multiqc.info.

Pipeline information

Output files
  • pipeline_info/
    • Reports generated by Nextflow: execution_report.html, execution_timeline.html, execution_trace.txt and pipeline_dag.dot/pipeline_dag.svg.
    • Reports generated by the pipeline: pipeline_report.html, pipeline_report.txt and software_versions.yml. The pipeline_report* files will only be present if the --email / --email_on_fail parameter’s are used when running the pipeline.
    • Reformatted samplesheet files used as input to the pipeline: samplesheet.valid.csv.
    • Parameters used by the pipeline run: params.json.

Nextflow provides excellent functionality for generating various reports relevant to the running and execution of the pipeline. This will allow you to troubleshoot errors with the running of the pipeline, and also provide you with other information such as launch commands, run times and resource usage.

On this page