bio-longread-qc

Version Compatibility

Reference examples tested with: BioPython 1.83+, numpy 1.26+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: <tool> --version then <tool> --help to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed

package and adapt the example to match the actual API rather than retrying.

Long-Read Quality Control

"Check the quality of my Nanopore/PacBio run" → Generate read length distributions, quality score plots, and summary statistics, then filter reads by length and quality thresholds.

• CLI: NanoPlot --fastq reads.fq.gz -o nanoplot_output/, chopper -q 10 -l 1000 < reads.fq > filtered.fq

NanoPlot - Visualization

# From FASTQ
NanoPlot --fastq reads.fastq.gz -o nanoplot_output -t 4

# From BAM
NanoPlot --bam aligned.bam -o nanoplot_output -t 4

# From sequencing summary (fastest)
NanoPlot --summary sequencing_summary.txt -o nanoplot_output

NanoPlot - Common Options

NanoPlot --fastq reads.fastq.gz \
    -o nanoplot_output \
    -t 8 \
    --N50 \                        # Show N50 in plots
    --title "Sample QC" \
    --plots hex dot \              # Plot types
    --format png pdf \             # Output formats
    --color darkblue \
    --maxlength 50000 \            # Max length for plots
    --minlength 500                # Min length for plots

NanoStat - Statistics Only

# Quick statistics (no plots)
NanoStat --fastq reads.fastq.gz --threads 4

# From BAM
NanoStat --bam aligned.bam --threads 4

# Output to file
NanoStat --fastq reads.fastq.gz --threads 4 > qc_stats.txt

chopper - Filter Reads

# Filter by length and quality
gunzip -c reads.fastq.gz | chopper -q 10 -l 1000 | gzip > filtered.fastq.gz

# Quality >= 10, length >= 1000bp

chopper - Common Options

gunzip -c reads.fastq.gz | chopper \
    --quality 10 \                 # Min quality
    --minlength 1000 \             # Min length
    --maxlength 50000 \            # Max length
    --headcrop 50 \                # Remove from start
    --tailcrop 50 \                # Remove from end
    --threads 4 \
    | gzip > filtered.fastq.gz

NanoFilt - Alternative Filter

# Filter with NanoFilt
gunzip -c reads.fastq.gz | NanoFilt -q 10 -l 1000 | gzip > filtered.fastq.gz

# With more options
gunzip -c reads.fastq.gz | NanoFilt \
    --quality 10 \
    --length 1000 \
    --maxlength 50000 \
    --headcrop 50 \
    | gzip > filtered.fastq.gz

Porechop - Adapter Trimming

# Trim adapters
porechop -i reads.fastq.gz -o trimmed.fastq.gz --threads 8

# With barcode splitting
porechop -i reads.fastq.gz -b output_dir/ --threads 8

Generate Summary Statistics

# Quick summary with seqkit
seqkit stats reads.fastq.gz

# Detailed stats
seqkit stats -a reads.fastq.gz

# Watch stats during basecalling
seqkit watch --fields ReadLen,MeanQual reads.fastq.gz

PycoQC - From Basecalling

# Generate QC report from sequencing_summary.txt
pycoQC -f sequencing_summary.txt -o pycoqc_report.html

# With BAM for alignment stats
pycoQC -f sequencing_summary.txt -a aligned.bam -o pycoqc_report.html

Calculate N50

# With seqkit
seqkit stats -a reads.fastq.gz | grep N50

# Manual calculation
seqkit fx2tab -l reads.fastq.gz | cut -f 2 | sort -rn | \
    awk '{sum+=$1; len[NR]=$1} END {
        target=sum/2; cumsum=0;
        for(i=1; i<=NR; i++) {
            cumsum+=len[i];
            if(cumsum>=target) {print "N50:", len[i]; break}
        }
    }'

Parse FASTQ Quality in Python

Goal: Compute read length and quality distributions from long-read FASTQ for custom QC analysis.

Approach: Iterate records with BioPython, collecting per-read length and mean Phred quality for summary statistics.

import numpy as np
from Bio import SeqIO

lengths = []
qualities = []

for record in SeqIO.parse('reads.fastq', 'fastq'):
    lengths.append(len(record))
    qualities.append(np.mean(record.letter_annotations['phred_quality']))

print(f'Total reads: {len(lengths)}')
print(f'Total bases: {sum(lengths):,}')
print(f'Mean length: {np.mean(lengths):.0f}')
print(f'Median length: {np.median(lengths):.0f}')
print(f'Mean quality: {np.mean(qualities):.1f}')

NanoPlot Output Files

| File | Description |

|------|-------------|

| NanoStats.txt | Summary statistics |

| NanoPlot-report.html | Interactive report |

| LengthvsQualityScatterPlot | Length vs Q plot |

| WeightedHistogramReadlength | Read length distribution |

| Yield_By_Length | Cumulative yield |

Key Parameters - NanoPlot

| Parameter | Description |

|-----------|-------------|

| --fastq | Input FASTQ |

| --bam | Input BAM |

| --summary | Sequencing summary |

| -o | Output directory |

| -t | Threads |

| --N50 | Show N50 line |

| --plots | Plot types |

| --format | Output formats |

Key Parameters - chopper

| Parameter | Default | Description |

|-----------|---------|-------------|

| -q | 0 | Min quality |

| -l | 0 | Min length |

| --maxlength | inf | Max length |

| --headcrop | 0 | Trim from start |

| --tailcrop | 0 | Trim from end |

| -t | 4 | Threads |

Quality Thresholds

| Q Score | Accuracy | Typical Use |

|---------|----------|-------------|

| Q7 | ~80% | Very low quality |

| Q10 | ~90% | Basic filtering |

| Q15 | ~97% | Moderate filtering |

| Q20 | ~99% | High quality (SUP) |

| Q30 | ~99.9% | Very high (HiFi) |

Related Skills

• long-read-alignment - Align filtered reads
• sequence-io/fastq-quality - FASTQ quality analysis
• medaka-polishing - Polish with filtered reads