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.bainanofetch 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.
Python 3.9 or newer is required.
python -m pip install nanofetchFor 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]'
pytestpysam is the only runtime dependency. A separate samtools installation is not
required.
One gene, using the default 1 Mb padding on both sides:
nanofetch tumor.bam EGFRSeveral genes:
nanofetch tumor.bam --genes EGFR CDK4 PDGFRA CDKN2A METWrite one deduplicated, indexed BAM for all selected genes:
nanofetch tumor.bam --panel cns --combined cns.bam --indexRead a custom panel containing whitespace- or comma-separated symbols and #
comments:
nanofetch tumor.bam --gene-file my-panel.txt --combined panel.bam --indexCompact families are accepted:
nanofetch tumor.bam CDKN2A/B NTRK1/2/3Use the built-in CNS convenience panel:
nanofetch tumor.bam --panel cns --index --output-dir cns-regionsUse 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 hs1Indexed CRAM input is supported. Supply its reference explicitly when required:
nanofetch tumor.cram EGFR --reference GRCh38.fa --indexInspect the resolved regions without writing BAMs:
nanofetch tumor.bam EGFR --dry-run
Genome: GRCh38
Annotation: GENCODE 50 (GRCh38.p14)
EGFR chr7:54018820-56211628 EGFR.bamGenerate a reproducibility manifest:
nanofetch tumor.bam EGFR MET --index --manifest regions.tsvExport resolved padded regions as BED without extracting BAMs:
nanofetch tumor.bam --gene-file my-panel.txt --write-bed regions.bed --dry-runWrite compact gene-body coverage QC for every selected gene:
nanofetch tumor.bam --panel cns --combined cns.bam --summary coverage.tsvThe summary reports alignment count, mean depth, mean mapping quality, and the percentage of gene bases covered at 1×, 10×, and 30×.
Create a self-contained coverage overview for one extracted gene:
nanofetch tumor.bam EGFR --plot EGFR.coverage.svgThe 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.
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.
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:
| Assembly | Accepted names | Bundled annotation |
|---|---|---|
| GRCh37 | grch37, hg19 |
GENCODE 50lift37 |
| GRCh38 | grch38, hg38 |
GENCODE 50 |
| T2T-CHM13v2.0 | t2t, hs1, chm13, chm13v2.0 |
RefSeq/Liftoff v5.3 |
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.
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.
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.
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.
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.
MIT. T2T consortium data are released under CC0; see the upstream CHM13 repository.