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. withbcftools 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.gff3or.gff.--fasta: Path to reference genome FASTA.--output: Path to the output file. Extension selects the format:.csvfor CSV,.parquetor.pqfor Parquet.--reassign-exons: (flag) Recompute exon numbers (recommended for hg19)--no-sequences: (flag) Leave out the 4 sequence columnsref_cds_seq,alt_cds_seq,transcript_seqandalt_transcript_seq. These columns make up most of the output size.--no-prediction: (flag) Leave out the columnnmd_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_typeandtranscript_tags: the type and the tags of the transcript, to filter by transcript- reconstructed reference / alternative CDS and transcript sequences (+ metadata);
--no-sequencesleaves 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_statusandnmd_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 |
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.