LongReadSum: A fast and flexible QC tool for long read sequencing data

LongReadSum supports FASTA, FASTQ, BAM, FAST5, and sequencing_summary.txt file formats for quick generation of QC data in HTML and text format.

README Contents

• Installation using Anaconda (recommended)
• Installation using Docker
• Building from source
• MultiQC support
• General usage for common filetypes:
  • Common parameters
  • WGS BAM
  • BAM with base modifications/methylation
  • RRMS BAM
  • PacBio unaligned BAM
  • RNA-Seq BAM (TIN values)
  • ONT POD5
  • ONT FAST5
    • Signal QC
    • Sequence QC
  • Basecall summary (ONT sequencing_summary.txt)
  • FASTQ
  • FASTA
• Revision history
• Getting help
• Citing LongReadSum

Installation using Anaconda

First, install Anaconda.

Next, create a new environment. This installation has been tested with Python 3.10, Linux 64-bit.

conda create -n longreadsum python=3.9
conda activate longreadsum

LongReadSum and its dependencies can then be installed using the following command:

conda install -c wglab -c conda-forge -c jannessp -c bioconda longreadsum

Installation using Docker

First, install Docker. Pull the latest image from Docker hub, which contains the latest longreadsum release and its dependencies.

docker pull genomicslab/longreadsum

Running

On Unix/Linux:

docker run -v C:/Users/.../DataDirectory:/mnt/ -it genomicslab/longreadsum bam -i /mnt/input.bam -o /mnt/output

Note that the -v command is required for Docker to find the input file. Use a directory under C:/Users/ to ensure volume files are mounted correctly. In the above example, the local directory C:/Users/.../DataDirectory containing the input file input.bam is mapped to a directory /mnt/ in the Docker container. Thus, the input file and output directory arguments are relative to the /mnt/ directory, but the output files will also be saved locally in C:/Users/.../DataDirectory under the specified subdirectory output.

Building from source

To get the latest updates in longreadsum, you can build from source. First install Anaconda. Then follow the instructions below to install LongReadSum and its dependencies:

# Pull the latest updates
git clone https://github.com/WGLab/LongReadSum
cd LongReadSum

# Create the longreadsum environment, install dependencies, and activate
conda env create -f environment.yml
conda activate longreadsum

# Build the program
make

MultiQC support

MultiQC is a widely used open-source tool for aggregating bioinformatics analyses results from many tools across samples.

To run MultiQC, input the LongReadSum directory containing the output JSON summary file, and specify the longreadsum module:

multiqc $INPUT_DIRECTORY --module longreadsum --outdir $OUTPUT_DIRECTORY/multiqc

Example report: <img width="1707" height="761" alt="image" src="https://github.com/user-attachments/assets/adbcacf7-44f8-48bd-9135-9293379d65d2" />

Running

Activate the conda environment and then run with arguments:

conda activate longreadsum
longreadsum <FILETYPE> [arguments]

General Usage

Specify the filetype followed by parameters:

longreadsum <FILETYPE> -i $INPUT_FILE -o $OUTPUT_DIRECTORY

Common parameters

To see all parameters for a filetype, run:

longreadsum <FILETYPE> --help

This section describes parameters common to all filetypes:

| Parameter | Description | Default | | --- | --- | --- | | -i, --input | A single input filepath | -I, --inputs | Multiple comma-separated input filepaths | -P, --pattern | Use pattern matching (*) to specify multiple input files. Enclose the pattern in double quotes. | -g, --log | Log file path | log_output.log | -G, --log-level |Logging level (1: DEBUG, 2: INFO, 3: WARNING, 4: ERROR, 5: CRITICAL) | 2 | -o, --outputfolder | Output directory | output_longreadsum | -t, --threads | The number of threads used | 1 | -Q, --outprefix | Output file prefix | QC_

WGS BAM

This section describes how to generate QC reports for BAM files from whole-genome sequencing (WGS) with alignments to a linear reference genome such as GRCh38 (data shown is HG002 sequenced with ONT Kit V14 Promethion R10.4.1 from https://labs.epi2me.io/askenazi-kit14-2022-12/)

General usage

longreadsum bam -i $INPUT_FILE -o $OUTPUT_DIRECTORY

BAM with base modifications

This section describes how to generate QC reports for BAM files with MM, ML base modification tags (data shown is HG002 sequenced with ONT MinION R9.4.1 from https://labs.epi2me.io/gm24385-5mc/)

Parameters

| Parameter | Description | Default | | --- | --- | --- | | --mod | Run base modification analysis on the BAM file | False | --modprob | Base modification filtering threshold. Above/below this value, the base is considered modified/unmodified. | 0.8 | --ref | The reference genome FASTA file to use for identifying CpG sites (optional)

General usage

longreadsum bam -i $INPUT_FILE -o $OUTPUT_DIRECTORY --mod --modprob 0.8 --ref $REF_GENOME

RRMS BAM

This section describes describes how to generate QC reports for ONT RRMS BAM files and associated CSVs (data shown is HG002 RRMS using ONT R9.4.1).

Accepted reads:

Rejected reads:

Parameters

| Parameter | Description | Default | | --- | --- | --- | | -c, --csv | CSV file containing read IDs to extract from the BAM file*

The CSV file should contain a read_id column with the read IDs in the BAM file, and a decision column with the accepted/rejected status of the read. Accepted reads will have stop_receiving in the decision column, while rejected reads will have unblock:

batch_time,read_number,channel,num_samples,read_id,sequence_length,decision
1675186897.6034577,93,4,4011,f943c811-3f97-4971-8aed-bb9f36ffb8d1,361,unblock
1675186897.7544408,80,68,4025,fab0c19d-8085-454c-bfb7-c375bbe237a1,462,unblock
1675186897.7544408,93,127,4028,5285e0ba-86c0-4b5d-ba27-5783acad6105,438,unblock
1675186897.7544408,103,156,4023,65d8befa-eec0-4496-bf2b-aa1a84e6dc5e,362,stop_receiving
...

General usage

longreadsum rrms -i $INPUT_FILE -o $OUTPUT_DIRECTORY -c $RRMS_CSV

RNA-Seq BAM

This section describes how to generate QC reports for TIN (transcript integrity number) scores from RNA-Seq BAM files (data shown is Adult GTEx v9 long-read RNA-seq data sequenced with ONT cDNA-PCR protocol from https://www.gtexportal.org/home/downloads/adult-gtex/long_read_data).

Outputs

A TSV file with scores for each transcript:

geneID	chrom	tx_start	tx_end	TIN
ENST00000456328.2	chr1	11868	14409	2.69449577083296
ENST00000450305.2	chr1	12009	13670	0.00000000000000
ENST00000488147.2	chr1	14695	24886	94.06518975035769
ENST00000619216.1	chr1	17368	17436	0.00000000000000
ENST00000473358.1	chr1	29553	31097	0.00000000000000
...

An TSV file with TIN score summary statistics:

Bam_file	TIN(mean)	TIN(median)	TIN(stddev)
/mnt/isilon/wang_lab/perdomoj/data/GTEX/GTEX-14BMU-0526-SM-5CA2F_rep.FAK93376.bam	67.06832655372376	74.24996965188242	26.03788585287367

A summary table in the HTML report:

Parameters

| Parameter | Description | Default | | --- | --- | --- | | --genebed | Gene BED12 file required for calculating TIN scores | --sample-size | Sample size for TIN calculation | 100 | --min-coverage | Minimum coverage for TIN calculation | 10

General usage

longreadsum bam -i $INPUT_FILE -o $OUTPUT_DIRECTORY --genebed $BED_FILE --min-coverage <COVERAGE> --sample-size <SIZE>

Download an example HTML report here (data is Adult GTEx v9 long-read RNA-seq data sequenced with ONT cDNA-PCR protocol from https://www.gtexportal.org/home/downloads/adult-gtex/long_read_data)

PacBio unaligned BAM

This section describes how to generate QC reports for PacBio BAM files without alignments (data shown is HG002 sequenced with PacBio Revio HiFi long reads obtained from https://www.pacb.com/connect/datasets/#WGS-datasets).

General u