NanoFetch

Ridiculously easy gene-region BAM extraction.

nanofetch tumor.bam EGFR --index
Genome: GRCh38
Annotation: GENCODE 50 (GRCh38.p14)
Wrote EGFR.bam (18432 alignments) + EGFR.bam.bai

nanofetch turns gene symbols into reproducible genomic intervals, adds padding, and extracts overlapping alignments from coordinate-sorted BAM or CRAM files. It supports GRCh37, GRCh38, and the telomere-to-telomere T2T-CHM13v2.0 (hs1) assembly.

Install

Python 3.9 or newer is required.

python -m pip install nanofetch

For an isolated command-line installation, use pipx install nanofetch.

For local development:

git clone https://github.com/AlexanderM-M/Nanofetch.git
cd Nanofetch
python -m pip install -e '.[test]'
pytest

pysam is the only runtime dependency. A separate samtools installation is not required.

Usage

One gene, using the default 1 Mb padding on both sides:

nanofetch tumor.bam EGFR

Several genes:

nanofetch tumor.bam --genes EGFR CDK4 PDGFRA CDKN2A MET

Write one deduplicated, indexed BAM for all selected genes:

nanofetch tumor.bam --panel cns --combined cns.bam --index

Read a custom panel containing whitespace- or comma-separated symbols and # comments:

nanofetch tumor.bam --gene-file my-panel.txt --combined panel.bam --index

Compact families are accepted:

nanofetch tumor.bam CDKN2A/B NTRK1/2/3

Use the built-in CNS convenience panel:

nanofetch tumor.bam --panel cns --index --output-dir cns-regions

Use T2T-CHM13 explicitly, or let nanofetch detect it from chromosome lengths:

nanofetch t2t-aligned.bam EGFR --genome t2t
nanofetch t2t-aligned.bam --panel cns --genome hs1

Indexed CRAM input is supported. Supply its reference explicitly when required:

nanofetch tumor.cram EGFR --reference GRCh38.fa --index

Inspect the resolved regions without writing BAMs:

nanofetch tumor.bam EGFR --dry-run
Genome: GRCh38
Annotation: GENCODE 50 (GRCh38.p14)
EGFR   chr7:54018820-56211628   EGFR.bam

Generate a reproducibility manifest:

nanofetch tumor.bam EGFR MET --index --manifest regions.tsv

Export resolved padded regions as BED without extracting BAMs:

nanofetch tumor.bam --gene-file my-panel.txt --write-bed regions.bed --dry-run

Write compact gene-body coverage QC for every selected gene:

nanofetch tumor.bam --panel cns --combined cns.bam --summary coverage.tsv

The summary reports alignment count, mean depth, mean mapping quality, and the percentage of gene bases covered at 1×, 10×, and 30×.

SVG coverage plot

Create a self-contained coverage overview for one extracted gene:

nanofetch tumor.bam EGFR --plot EGFR.coverage.svg

The plot shows mean aligned-base depth in fixed-width bins, the annotated gene body, requested extraction span, assembly and annotation provenance, and counts for primary, supplementary, and secondary alignments. It visualizes the output BAM, so --include-supplementary and --include-secondary are reflected in the plot. SVG generation has no dependency beyond NanoFetch itself.

Run nanofetch --help for all options.

What is selected?

An alignment is selected when its aligned reference span overlaps the padded gene interval. It does not need to span the entire region.

By default, secondary (0x100) and supplementary (0x800) records are excluded. Use --include-secondary and --include-supplementary to retain records of those types that overlap the region.

--include-supplementary does not retrieve distant segments merely because a different segment from the same read overlaps the requested gene. That operation requires a read-name-based second pass and is intentionally outside the default semantics.

Overlapping padded intervals for multiple copies of the same symbol are merged, so an alignment is not written twice. Separate gene output BAMs may contain the same alignment when their padded regions overlap; this is expected.

Genome detection and contig names

Automatic detection compares exact primary-chromosome lengths in the BAM header. It will stop rather than guess when the build is ambiguous. The explicit spellings below are accepted:

Both chr7 and 7 naming styles are supported. T2T GenBank names such as CP068271.2 and RefSeq names such as NC_060931.1 are also mapped to their chromosomes.

Input and output safety

The input must be coordinate-sorted and indexed: BAM uses BAI or CSI, while CRAM uses CRAI. CRAM decoding can use --reference FASTA. nanofetch does not modify the input or create an input index automatically.

Existing output BAMs are protected unless --force is supplied. Outputs are written to a temporary file and moved into place only after writing succeeds. When an output is replaced, any stale BAI or CSI is removed. --index creates a fresh BAI. Plot and manifest files receive the same collision protection, and manifests are also written atomically.

Before extraction starts, nanofetch checks all planned BAM, index, plot, and manifest paths for conflicts. It refuses to use the input BAM or either of its conventional index paths as an output, even when --force is supplied.

Built-in CNS panel

The cns panel currently contains:

EGFR PDGFRA CDK4 MDM2 MDM4 MET CDKN2A CDKN2B NF1 PTEN TERT
BRAF FGFR3 NTRK1 NTRK2 NTRK3 ALK

This is a transparent convenience set, not a validated clinical assay. Use nanofetch --list-panels to inspect installed panels.

Annotation provenance

The package works offline. It bundles compact gene-level tables generated from pinned upstream files; it does not bundle complete GTF/GFF files.

• GRCh38: GENCODE release 50
• GRCh37: GENCODE 50lift37
• T2T: T2T-CHM13v2.0 RefSeq/Liftoff v5.3

Source URLs, SHA-256 digests, labels, and record counts are stored in src/nanofetch/data/annotations.json. The deterministic build script is scripts/build_annotations.py.

Scope

NanoFetch writes one BAM per gene by default or a single union with --combined. Potential later additions include custom GTF annotations, CRAM output, mate retrieval, and all-segment retrieval.

License

MIT. T2T consortium data are released under CC0; see the upstream CHM13 repository.