Skip to main content

NMD variant effect prediction

The NMD-Scanner is a Python-based variant effect annotation tool that predicts the likelihood of transcript degradation through nonsense-mediated decay (NMD). It reconstructs reference and alternative coding sequences as well as transcript sequences in some cases, identifies premature termination codons (PTCs), and evaluates canonical and non-canonical NMD escape rules. It can handle single-nucleotide variants, multiple base substitutions, long and short deletions and duplications as well as frameshift variants.

Features

  • Reads variants from VCF and gene annotations from GFF3 (GENCODE or Ensembl flavor), gzip-compressed or not
  • Reconstructs reference and alternative CDS, reference transcript sequence and (in some cases) the alternative transcript sequences with metadata
  • Detects start / stop-loss and premature termination codons (PTCs) with the exact position in the CDS and in which exon it lies
  • Computes different NMD-related features:
    • Total, upstream and downstream exon count
    • Distance of PTC to original stop codon
    • Distance of PTC to start codon
    • Transcript length
    • 3' and 5' UTR lengths
  • Evaluates five canonical NMD escape rules:
    • Last exon rule
    • 50nt penultimate rule
    • Long exon rule
    • Start-proximal rule
    • Single-exon rule
  • Predicts the NMD efficiency of each PTC with a random forest (see NMD efficiency prediction)
  • Writes the results as CSV or Parquet, or returns them as a pandas DataFrame

Technical Notes defines the features and the NMD escape rules, with figures.

Installation

Requires Python >= 3.12.

From PyPI:

pip install nmd-scanner

Usage

Option 1: Annotating a VCF on the command line

After the install, the nmd-scanner command is available:

nmd-scanner --vcf input.vcf --annotation annotation.gff3.gz --fasta reference.fa --output results/input.csv

# write Parquet instead of CSV
nmd-scanner --vcf input.vcf --annotation annotation.gff3.gz --fasta reference.fa --output results/input.parquet

# option: fix exon numbering (recommended for hg19)
nmd-scanner --vcf input.vcf --annotation annotation.gff3.gz --fasta reference.fa --output results/input.csv --reassign-exons

# option: leave out the 4 sequence columns
nmd-scanner --vcf input.vcf --annotation annotation.gff3.gz --fasta reference.fa --output results/input.parquet --no-sequences

Arguments:

  • --vcf: Path to input VCF, plain or gzip-compressed, left-normalized and with one ALT allele per record. Split multi-allelic records and left-normalize the VCF first, e.g. with bcftools norm -m- -f reference.fa. Records with a symbolic, breakend, . or * ALT are skipped with a warning.
  • --annotation: Path to the gene annotation in GFF3 (GENCODE or Ensembl flavor), optionally gzip-compressed, with the suffix .gff3 or .gff.
  • --fasta: Path to reference genome FASTA.
  • --output: Path to the output file. Extension selects the format: .csv for CSV, .parquet or .pq for Parquet.
  • --reassign-exons: (flag) Recompute exon numbers (recommended for hg19)
  • --no-sequences: (flag) Leave out the 4 sequence columns ref_cds_seq, alt_cds_seq, transcript_seq and alt_transcript_seq. These columns make up most of the output size.
  • --no-prediction: (flag) Leave out the column nmd_efficiency_prediction, the prediction of the NMD efficiency model.

The chromosome names must match in the VCF, the GFF3 and the FASTA, e.g. all chr1 or all 1.

Output:

  • The file specified by --output, with one row per variant-transcript pair, containing:
    • transcript_type and transcript_tags: the type and the tags of the transcript, to filter by transcript
    • reconstructed reference / alternative CDS and transcript sequences (+ metadata); --no-sequences leaves out the sequences
    • PTC detection and start / stop-loss flags
    • NMD escape rules
    • NMD features such as UTR lengths, exon counts, distances, etc.
    • nmd_efficiency_prediction_status and nmd_efficiency_prediction: whether the NMD efficiency model can predict the variant-transcript pair, and the NMD efficiency it predicts (see NMD efficiency prediction)

Output columns in the Technical Notes gives the meaning of each column and says when it is null.

Option 2: Import as a python module

annotate returns the result table of the CLI as a pandas.DataFrame; sequences=False and prediction=False are the flags --no-sequences and --no-prediction.

import nmd_scanner

results = nmd_scanner.annotate("input.vcf", "annotation.gff3.gz", "reference.fa", reassign_exons=False)
nmd_scanner.write_results(results, "results.parquet")  # or "results.csv"

annotate_variants takes the tables of read_vcf and read_annotation, so one annotation serves many VCFs. The table of read_vcf has the output columns chrom, start, end, variant_id, ref and alt (see Output columns). In it, alt is null for the VCF ALT ., and annotate_variants skips such a record. A table from another source needs no variant_id. In such a table, an empty ref or alt is a valid allele: alt "" is a deletion without its anchor base, and ref "" with start equal to end is an insertion.

The steps of annotate are public too; see How annotate builds the result.

NMD efficiency prediction

The CLI and annotate add the column nmd_efficiency_prediction, the prediction of a random forest that ships with the package. --no-prediction and prediction=False leave it out, and nmd_scanner.add_nmd_efficiency_prediction(results) adds it to a result of add_features_and_rules.

The model predicts NMD_efficiency of the NMDEff TCGA benchmark (Kim et al. 2024), about -log2(VAF_RNA / VAF_DNA). 0 means no NMD, and 1 means that the variant allele fraction in the RNA is half of that in the DNA. The prediction is null where nmd_efficiency_prediction_status is not ok. The model learned mostly from protein_coding transcripts tagged Ensembl_canonical. To keep only those, filter on transcript_type and transcript_tags.

Model validation

The figure gives the Spearman correlation of the prediction with the measured NMD efficiency, with 95% CIs from a bootstrap over genes. "Canonical rules" ranks the same measurements by nmd_escape alone. scripts/README.md shows how to reproduce the figure.

Cohort Variant origin
TCGA (Kim et al. 2024), out of fold, folds grouped by chromosome somatic, in tumors
Geuvadis (Iha et al. 2025), lymphoblastoid cell lines, the study's accurate annotation germline
GTEx v8 (Kim et al. 2024), 54 tissues, mean per variant germline
MMRF-TARGET (Kim et al. 2024) somatic, in tumors

Spearman correlation per cohort

License

All source code in this repository is licensed under the MIT License.

Citation

Schröder, C.H. (2025). Enhanced Aberrant Gene Expression Prediction across Human Tissues. Master's Thesis, Technical University of Munich / Ludwig-Maximilians-Universität München.

Metadata

Release files for nmd-scanner 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nmd-scanner 1.0.0
File Size Uploaded Provenance Actions
nmd_scanner-1.0.0.tar.gz 23.5 MB With provenance Details for nmd_scanner-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nmd-scanner 1.0.0
File Interpreter ABI Platform Actions
nmd_scanner-1.0.0-py3-none-any.whl Python 3 none any Details for nmd_scanner-1.0.0-py3-none-any.whl

Total release size: 24.0 MB

Release files / nmd_scanner-1.0.0.tar.gz

Download URL nmd_scanner-1.0.0.tar.gz
Size 23.5 MB
Tags Source
SHA-256 checksum
How to use checksums
ebaaa6a509b52b1c277ceaaee89889bdc01b437e19839f14d7624475209b6698
BLAKE2b-256 checksum
How to use checksums
8595a46a742f2124ab3018eae9e4c9afba54472d2a63c9685236e3e54c8b8a30
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / nmd_scanner-1.0.0-py3-none-any.whl

Download URL nmd_scanner-1.0.0-py3-none-any.whl
Size 462.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
195eec02f7c08f6fc4484d8edd80b1d47ca901cfa5c2334d5bacb647beb97456
BLAKE2b-256 checksum
How to use checksums
ad81d84ec2c843e98705054979883def6ba4a73220db447076a8437442db2d06
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for nmd-scanner 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for nmd_scanner-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page