v2.3

What's New

bam2tensor-inspect command

New CLI tool to inspect .methylation.npz output files without writing Python:

$ bam2tensor-inspect sample.methylation.npz
sample.methylation.npz
  Genome:          hg38
  Chromosomes:     24 (chr1, chr2, ... chrX, chrY)
  Reads:           1,423,891
  CpG sites:       28,217,448
  Data points:     12,847,322 (sparsity: 99.97%)
  CpG index CRC32: a1b2c3d4
  bam2tensor:      v2.3
  File size:       14.2 MB

Accepts multiple files and works on outputs from older versions (metadata fields are omitted gracefully).

Embedded provenance metadata in .npz files

Each output file now contains a metadata.json entry inside the ZIP archive with:

• bam2tensor_version — version that produced the file
• genome_name — reference genome identifier (e.g., hg38)
• expected_chromosomes — chromosome list defining the column mapping
• total_cpg_sites — number of CpG columns
• cpg_index_crc32 — CRC32 checksum of CpG positions (two files with the same CRC32 have identical column semantics and can be directly stacked/compared)

scipy.sparse.load_npz ignores this entry, so existing code is unaffected. Read metadata via bam2tensor.metadata.read_npz_metadata() or unzip -p file.npz metadata.json.

Improved output format documentation

The README now explicitly documents that column indices are determined by the reference genome's CpG sites and that GenomeMethylationEmbedding is needed to map columns back to genomic coordinates.

v2.2

Changes

• No changes

v2.1

Changes

• No changes

v2.0

bam2tensor v2.0 — Production/Stable

Promoted from Beta to Production/Stable.

New Features

• Bismark aligner support via XM methylation tag (Z/z for methylated/unmethylated CpG)
• --download-reference flag to auto-download and cache reference genomes (hg38, hg19, mm10, T2T-CHM13)
• --output-dir flag to write output files to a separate directory
• Chromosome name mismatch detection with actionable error messages (e.g. UCSC chr1 vs Ensembl 1)
• Aligner auto-detection displayed in CLI output (Bismark, Biscuit/bwameth, gem3/Blueprint)
• bwameth and EM-seq documentation and support (same YD tag format as Biscuit)

Improvements

• Structured CLI output with configuration summary, per-BAM progress, and final summary
• Optimized BAM read filtering using single bitwise flag check
• Elapsed time formatted as minutes + seconds for long runs
• Migrated from Poetry to uv for dependency management
• Test coverage improved to 98% (reference.py: 53%→100%, functions.py: 88%→96%, main.py: 89%→99%)
• Tests directory excluded from coverage metrics (only production code measured)

Bug Fixes

• Fixed typeguard failure: pass str not PosixPath to input_bam
• Fixed read duplication bug where reads spanning multiple CpG clusters could be counted twice

v1.5

Changes

📦 Dependencies

• Bump the poetry-dependencies group with 16 updates (#67) @dependabot[bot]
• Bump the github-action-dependencies group with 4 updates (#66) @dependabot[bot]
• Bump nox from 2025.10.16 to 2025.11.12 in /.github/workflows in the workflows-dependencies group (#65) @dependabot[bot]

v1.4

Changes

📦 Dependencies

• Bump the poetry-dependencies group across 1 directory with 29 updates (#64) @dependabot[bot]
• Bump the github-action-dependencies group across 1 directory with 4 updates (#63) @dependabot[bot]
• Bump the workflows-dependencies group in /.github/workflows with 4 updates (#61) @dependabot[bot]
• Bump the poetry-dependencies group across 1 directory with 38 updates (#59) @dependabot[bot]
• Bump the github-action-dependencies group across 1 directory with 5 updates (#58) @dependabot[bot]
• Bump the workflows-dependencies group across 1 directory with 3 updates (#56) @dependabot[bot]
• Bump the poetry-dependencies group with 17 updates (#51) @dependabot[bot]
• Bump the workflows-dependencies group in /.github/workflows with 4 updates (#50) @dependabot[bot]
• Bump the poetry-dependencies group with 16 updates (#49) @dependabot[bot]
• Bump pip from 25.0.1 to 25.1 in /.github/workflows in the workflows-dependencies group (#48) @dependabot[bot]
• Bump actions/setup-python from 5.5.0 to 5.6.0 in the github-action-dependencies group (#47) @dependabot[bot]
• Bump the poetry-dependencies group with 15 updates (#46) @dependabot[bot]
• Bump the github-action-dependencies group with 2 updates (#45) @dependabot[bot]
• Bump the workflows-dependencies group in /.github/workflows with 2 updates (#44) @dependabot[bot]
• Bump the poetry-dependencies group with 15 updates (#41) @dependabot[bot]
• Bump the workflows-dependencies group in /.github/workflows with 5 updates (#42) @dependabot[bot]
• Bump the github-action-dependencies group with 2 updates (#43) @dependabot[bot]
• Bump the github-action-dependencies group with 3 updates (#40) @dependabot[bot]
• Bump the poetry-dependencies group with 20 updates (#38) @dependabot[bot]
• Bump poetry from 1.8.4 to 1.8.5 in /.github/workflows in the workflows-dependencies group (#37) @dependabot[bot]
• Bump the poetry-dependencies group with 17 updates (#36) @dependabot[bot]
• Bump the github-action-dependencies group with 2 updates (#35) @dependabot[bot]
• Bump the poetry-dependencies group with 16 updates (#34) @dependabot[bot]
• Bump the github-action-dependencies group across 1 directory with 4 updates (#33) @dependabot[bot]
• Bump the workflows-dependencies group in /.github/workflows with 4 updates (#32) @dependabot[bot]
• Bump the poetry-dependencies group with 23 updates (#30) @dependabot[bot]
• Bump the poetry-dependencies group with 13 updates (#29) @dependabot[bot]
• Bump pypa/gh-action-pypi-publish from 1.10.1 to 1.10.2 in the github-action-dependencies group (#28) @dependabot[bot]
• Bump virtualenv from 20.26.3 to 20.26.6 in /.github/workflows in the workflows-dependencies group (#27) @dependabot[bot]
• Bump the poetry-dependencies group with 5 updates (#26) @dependabot[bot]
• Bump the github-action-dependencies group with 3 updates (#25) @dependabot[bot]
• Bump the poetry-dependencies group across 1 directory with 49 updates (#24) @dependabot[bot]
• Bump the github-action-dependencies group across 1 directory with 3 updates (#23) @dependabot[bot]
• Bump the workflows-dependencies group across 1 directory with 3 updates (#21) @dependabot[bot]
• Bump setuptools from 69.5.1 to 70.0.0 (#16) @dependabot[bot]
• Bump the poetry-dependencies group with 26 updates (#13) @dependabot[bot]
• Bump the workflows-dependencies group in /.github/workflows with 2 updates (#12) @dependabot[bot]
• Bump the poetry-dependencies group with 13 updates (#11) @dependabot[bot]
• Bump the workflows-dependencies group in /.github/workflows with 2 updates (#10) @dependabot[bot]
• Bump the github-action-dependencies group with 3 updates (#9) @dependabot[bot]
• Bump the github-action-dependencies group with 2 updates (#8) @dependabot[bot]
• Bump the poetry-dependencies group with 17 updates (#7) @dependabot[bot]
• Bump the workflows-dependencies group in /.github/workflows with 3 updates (#6) @dependabot[bot]

v1.3

Changes

• No changes

v1.2

Changes

📦 Dependencies

• Bump the poetry-dependencies group with 12 updates (#5) @dependabot

v1.1

Changes

• No changes

v1.0.1

Changes

• No changes