Module meth 

Methylation bitmaps and chemistry-conversion logic.

Provides per-haplotype methylation state via MethylationTable and ContigMethylation, plus the apply_methylation_conversion free function that simulates the per-base chemistry of either an em-seq / bisulfite library (unmethylated C → T) or a TAPS library (methylated C → T).

Per-haplotype CpG detection and per-strand bitmaps

Each haplotype gets its own pair of BitVecs indexed by haplotype position (0..haplotype_length):

• top[h] = “the top-strand C at haplotype position h is methylated.”
• bottom[h + 1] = “the bottom-strand C at haplotype position h + 1 is methylated.”

Indexing by haplotype position rather than reference position naturally handles SNPs, insertions, and deletions that create or destroy CpG sites on a particular haplotype: each haplotype’s bitmap reflects the CpG context that actually exists on that haplotype. Both bitmaps have length equal to the haplotype’s materialized length; positions that don’t host a strand-specific C (or that host a non-CpG cytosine) always read false. Non-CpG cytosines are always treated as unmethylated.

Methylation model (the methylate generator)

MethylationTable::from_haplotype fills these bitmaps with a context-aware, spatially-correlated model rather than independent per-CpG coin flips. Each CpG is classified ([CpgContext]) into island / shore / open-sea from the haplotype sequence; a two-state (methylated/unmethylated) Markov chain then walks the CpG list using that context’s [ContextParams] (target rate + correlation length, bundled per-context in [MethylationModel]). The chain’s stationary mean equals the context’s target rate while neighbouring CpGs are spatially correlated, so islands come out hypomethylated, open-sea hypermethylated, with shore gradients in between. Methylation is symmetric across strands by default; sporadic hemimethylation is introduced per-CpG via [MethylationModel::hemi_rate]. Allele-specific methylation falls out naturally because each haplotype is walked as an independent chain. The model is built once (from CLI flags) and threaded through ContigMethylation::from_haplotypes → MethylationTable::from_haplotype.

Chemistry modes

MethylationMode selects which class of cytosines is converted to thymine during chemistry simulation:

• MethylationMode::EmSeq – unmethylated cytosines convert to thymine; methylated cytosines are preserved. Matches both classical bisulfite chemistry and enzymatic methyl-seq (em-seq, NEBNext) – the conversion patterns are identical.
• MethylationMode::Taps – methylated cytosines convert to thymine (TET oxidation + pyridine borane); unmethylated cytosines are preserved. The inverse of em-seq: a C→T event at a CpG signals methylation.

Structs

ContigMethylation

Per-contig methylation state covering ALL haplotypes for one contig. Indexed by crate::fragment::Fragment::haplotype_index.

MethylationAnnotation

Annotation captured during methylation read generation, used by downstream writers (notably the golden BAM) to emit the full Bismark- compatible methylation tag set: XG:Z (genome-strand indicator), XR:Z (read-conversion direction; derived from the SAM flag at emission time), YS:Z (pre-conversion bases), the holodeck cf:i conversion-failure flag, plus the Bismark call tags XM:Z / YM:Z / NM:i / MD:Z carried in r1_call_tags / r2_call_tags and computed by crate::methylation_tags::populate_pair_call_tags.

MethylationConfig

Configuration bundle passed through the read-generation pipeline when methylation chemistry simulation is enabled. Carries the per-contig, per-haplotype methylation state plus the chemistry parameters.

MethylationRecordTags

Per-record methylation annotation passed into the golden BAM record builder when the pair was generated with methylation chemistry enabled (em-seq or TAPS). Carries the XG:Z strand indicator (shared across R1 and R2) and the read’s own pre-conversion bases in read 5’->3’ (FASTQ) orientation. The record builder reverse-complements them when the record is reverse-strand so YS:Z ends up in the same orientation as SEQ.

MethylationTable

Per-haplotype methylation state, one bitmap per strand. Bitmaps are indexed by haplotype position (which may differ from reference position when the haplotype contains indels).

Enums

ConversionType

Which methylation conversion pattern a read displays when mapped to the reference. Mirrors the Bismark XG:Z (genome-strand) tag convention – it’s a strand indicator and stays the same for both em-seq and TAPS chemistries; only the biological meaning of an observed C→T differs (em-seq: unmethylated at that site; TAPS: methylated at that site).

MethylationMode

Methylation chemistry. Selects which class of cytosines is converted to thymine during chemistry simulation.

Functions

apply_methylation_conversion

Apply per-base methylation chemistry conversion to read bases in place.