Before installing the pipeline, make sure your system supports these requirements

The following are the requirements for running the workflow:

• A system with either docker or singularity configured.

• Python 3.6 and above (for running and running )

  • Python Packages (will be installed as part of pipeline installation):

    • coloredlogs

    • toil[cwl]

Step 1: Create a virtual environment.

Option (A) - if using cwltool

If you are using cwltool only, please proceed using python 3.9 as done below:

Here we can use either or . Here we will use conda. The

Option (B) - recommended for Juno HPC cluster

If you are using toil, python 3 is required. Please install using Python 3.6 as done below:

Here we can use either or . Here we will use conda.

Step 2: Clone the repository

Clone the repository and checkout the develop branch for the most up-to-date version:

Step 3: Install requirements using pip

We have already specified the version of cwltool and other packages in the requirements.txt file. Please use this to install.

Step 4: Load singularity and nodejs for HPC

For HPC normally singularity is used for containers. Therefore, please make sure that it is loaded. For JUNO/SELENE, you can do the following:

We also need to make sure nodejs is installed, this can be installed using conda:

Step 5: Generate an inputs file

Next you must generate a proper input file in either or format.For details on how to create this file, please follow this example (there is a minimal example of what needs to be filled in in the workflow inputs ):​

It's also possible to create and fill in a "template" inputs file using this command:

Note: To see help for the inputs for cwl workflow you can use:

Once we have successfully installed the requirements we can now run the workflow using cwltool/toil .

Step 5: Run the workflow

Given the output files from , there are workflows to generate the quality control files, aggregate the files across many samples, and visualize them using MultQC. You can choose to run these workflows whether you have just one or hundreds of samples. Depending on your use case, there are two main options:

Option A:

Generate a single inputs.yml file for all your samples and run nucleo_qc.cwl. This will generate a single MultiQC report with all the samples. The samples you selected do run together may be from a single batch.

Option B:

Generate multiple yaml files for each sample or sample batches and run nucleo_qc.cwl seperately on each. This will generate multiple outputs and multiple single sample MultiQC reports. In order to rejoin all samples to a single MultiQC report you must generate nucleo_aggregate_visualize.yml file () and then run nucleo_aggregate_visualize.cwl (Figure 4).

Introduction

This section aims to provide an introduction to the Nucleo Quality Control process along with installation and running instructions. The Nucleo QC process generated QC metrics for all type of BAM files generated by Nucleo, including collapsed, uncollapsed, duplex and simplex BAM files. The main outputs of the workflow are the MultiQC report and coverage report. Thorough intepretation of the output files can be found in this gitbook section.

Credits

• CMO cfDNA Informatics Team

• Clinical Bioinformatics

Option 1: Input.yml example to run workflow enable mosdepth/athena to create coverage reports

This section will guide you in how to interpret the output from running the ACCESS QC workflow. The main output from running the ACCESS QC workflow is a report (for both single sample and multiple samples). Each subsection explains certain parts of the MultiQC report.

Table of Contents

The workflows for nucleo quality control are written in the common workflow language (CWL). Below, figure 1 illustrates the organization level, all tools used in the bigger workflows are listed first, this tools are then called in the subworkflows listed second, then the subworfklows are called to make bigger main workflows.

For instance, in the qc_collapsed subworkflows we are using multiple command line tools such as all the biometrics tools. The main workflow to generate all the QC outputs is nucleo_qc seen at the bottom in the high-level CWL workflow section. This workflow calls both the nucleo_qc_generator.cwl that generates the QC results for each BAM file (collapsed, uncollapsed, duplex and simplex) by calling all the subworkflows and nucleo_aggregate_visualize.cwl that aggregates the QC results into different folders and calls MultiQC to generate the html QC report.

Introduction

This figure below represents the insert size distribution from the CMO-CH target regions. Insert size is calculated from the start and stop positions of the reads after mapping to the reference genome.

Methods

Tool used: BAM type: Collapsed BAM

The data used to produce this figure are the values under the MODE_INSERT_SIZE column contained in the output file from CollectInsertSizeMetrics.

Interpretation

Usually this plot has a specific shape as Cell free DNA has distinctive features due to the natural processes behind its fragmentation. One such feature is the set of 10-11 bp fluctuations that indicate the preferential splicing of fragments due to the number of bases per turn of the DNA helix, which causes a unique pattern of binding to the surface of histones.

The more pronounced peak at 166 bp indicate complete wrapping of the DNA around the histones' circumference, and similarly the second more pronounced peak indicates two complete wraps.

However in the CMO-CH panel we are using Buffy coat samples. These samples are mechanically sheared and thus do not exhibit these distinctive features, hence the different shape for their distribution in comparison to other reports.

The workflow outputs multiple QC metric files that are merged into a single MultiQC report. The workflow also outputs the athena coverage report. For further interpretation please use the link to MultiQC and Athena.

Nucleo_qc.cwl produces two main folders (Figure 1):

1. Sample folder: The sample folder contains sample-specific files regarding contamination.

2. MultiQC folder: The MultiQC folder contains the following:

   1. MultiQC html report

   2. MultiQC data folder and

   3. Aggregate parsed stats folder. The latter folder contains sample-specific files.

The figure plots below represent the normalized coverage against the % GC content from the CMO-CH target regions. Each line is data from a single sample.

Methods

Tool used: GATK-CollectHsMetrics BAM type: (1) collapsed BAM and (2) uncollapsed BAM.

The data used to produce this figure are the values under the normalized_coverage and %gc columns, which are in the *_per_target_coverage.txt the output file from CollectHsMetrics. For each sample separately, the % GC content for each target region is calculated, followed by binning the target regions by their GC content (in 5% intervals). Then for each bin, the mean coverage is calculated and then normalized across all regions that fall into each GC bin.

Interpretation

Extreme base compositions, i.e., GC-poor or GC-rich sequences, lead to an uneven coverage or even no coverage of reads across the genome. This can affect downstream small variants and copy number calling. Both of these rely on consistent sequencing depth across all regions. Ideally, this plot should be as flat as possible. High GC-rich regions have a decrease in coverage as these regions are harder to sequence.

Introduction

This figure shows the density plot of coverage values from the ACCESS target regions. Each line is data from one sample. Each sample is normalized by the median coverage value of that sample to align all peaks with one another and correct for sample-level differences.

Methods

Tool used: BAM type: Collapsed BAM

The data used to produce this figure are the values under the normalized_coverage column, which are in the *_per_target_coverage.txt output file from CollectHsMetrics. Then the gaussian_kde function from the python scipy package is used to produce the density plot.

Interpretation

Each distribution should be unimodal, apart from a second peak on the low end due to X chromosome mapping from male samples. Narrow peaks are indicative of evenly distributed coverage across all bait regions. Wider distributions indicate uneven read distribution and may be correlated with a large GC bias. Note that the provided bed file lists the start and stop coordinates of ACCESS design probes, not the actual genomic target regions.

We investigate the number of Duplex families by plotting the count of the number of families with the ab and ba single-strand families of size ab_size and ba_size.

Introduction

There are several sections displaying bait set capture efficiency. Each section corresponds to a separate BAM type and bait set combination. The tool used to produce the metrics is GATK-CollectHsMetrics. By default, only the mean bait coverage, mean target coverage, and % Usable bases on-target are displayed. However, there are many more metrics that can be toggled to display by clicking on the Configure Columns button.

Methods

Tool used: BAM type: (1) Uncollapsed BAM, (1) Collapsed BAM, (1) Duplex BAM, and (4) Simplex BAM

Interpretation

The aim is to have high coverage across the panel.

Introduction

Two metrics are used to estimate sample contamination: minor contamination and major contamination. Moreover, minor contamination is calculated separately for collapsed and duplex BAMs. Both contamination metrics are produced by the fingerprinting SNP set. However, minor contamination is calculated using just the homozygous sites, whereas the major contamination is via the ratio of heterozygous to homozygous sites. For each contamination-BAM type combination there is a table showing per-sample contamination values and any associated metrics.

We investigate the number of Simplex families by plotting the count of the number of families with the ab and ba single-strand families of size ab_size and ba_size.

The first section of the MultiQC report is the Summary QC metrics table that displays the summary information per sample. The metrics presented are mainly lab sample quality metrics, alignment information, and quality of the target capture.

Interpretation

In the above table, the coloring represents the QC criteria of the values set by the Bioinformatics tram. The coloring schema is either red, yellow, or green, which indicates if the metric fails, is borderline, or passes the thresholds. This allows the Bioinformatics team to quickly glance at all samples to see where potential issues are. Below are the descriptions for each column and were the data was obtained from.

Metrics produced by CollectDuplexSeqMetrics that are sampled at various levels of coverage, via random downsampling, during the construction of duplex metrics. The downsampling is done in such a way that the fractions are approximate, and not exact, therefore the fraction the field should only be interpreted as a guide, and the read_pairs field used to quantify how much data was used.

Introduction

This figure below illustrates the mean base quality by cycle BaseQualityScoreRecalibration (BQSR). The sequencer uses the difference in intensity of the fluorescence of the bases to give an estimate of the quality of the base that has been read. The BQSR tool from GATK recalculates these values based on the empirical error rate of the reads themselves, which is a more accurate estimate of the original quality of the read.

The table below summarised the variants called in hotspot regions in the normal samples.

Major contamination is calculated by the Collapsed BAM and is calculated using the ratio of heterozygous to homozygous sites.

Minor contamination is calculated separately for collapsed and duplex BAMs. Minor contamination is calculated using just the homozygous sites.

CMO-CH QC thresholds

Athena is a tool to generate coverage statistics for NGS data, and combine these into an interactive HTML report. This gives both summary level and in depth information as to the coverage of the data, including various tables and plots to visualise the data. Examples of the output statistics files and may be found in data/example. Athena can also optionally include plots visualising per-chromosome level coverage - refer to this for an example. More details can be found

Credits

Jethro Rainford - Cambridge University Hospital UK

The following subpages serve to summarize each section of the athena coverage report.

Introduction

This section contains a table showing the samples clustered into groups, where each row in the table corresponds to one sample. The table will show whether your samples are grouping together in unexpected ways, which would indicate sample mislabelling.

Methods

Tool used: BAM type: Collapsed BAM Regions: MSK-ACCESS-v1_0-curatedSNPs.vcfIt is a two step process to produce the table: (1) extract SNP genotypes from each sample using biometrics extract command and (2) perform a pairwise comparison of all samples to determine sample relatedness using the biometrics genotype command. Please see the biometrics documentation for further documentation on the methods.

Interpretation

Below is a description of all the columns.

The first section of the report provides an overview of all sections in the report and the sample name for each report.

The athena tool is made of 3 parts; 1) annotate the bed file 2) generate statistic files 3) generate the coverage report. This can be run independently or together with a single workflow:

Run independently:

1. Annotate each region of the bed file with the gene, exon and per base coverage data using https://github.com/msk-access/cwl-commandlinetools/blob/develop/athena/1.4.2/annotate_bed/annotate_bed.cwl

2. Generate per exon and per gene statistics using https://github.com/msk-access/cwl-commandlinetools/blob/develop/athena/1.4.2/coverage_stats_single/coverage_stats_single.cwl

3. Generate HTML coverage report with

Run three steps with a single workflow:

• Run all 3 steps above using a single workflow using

Coverage gene level

This section provides coverage metrics for each gene, showing which genes have sub-optimal coverage for a given threshold.

Users can optionally outpout coverage plots per exon for each gene.

Coverage exon level

The table below shows which exons in each gene has sub-optimal coverage for each given threshold.

The above is also shown diagrammatically in the plots below. These plots are interactive allowing users to assess what portion of the exons has sub-optimal coverage

The summary section provides an overview of the report as seen below. Key information about the panel and coverage threshold and statistics are displayed. For example in this report the coverage threshold was set at 500X and the number of genes not covered 100% at 500X were 8.

The plot in the summary section diagrammatically illustrates which genes have an overall coverage above 99% (green), below 99% (yellow) and below 95% (red).

The coverage per chromosome section provides an overview of the global read coverage per chromosome (target regions only for target-capture assays).

The per exon coverage section provides coverage metrics for all exons in all genes.

Coverage of known variants

Parameter Used by Tools

Common Parameters Across Tools