Module cpg_truth 

Coverage-weighted per-CpG truth tally written as a MethylDackel-format bedGraph from simulated reads. Per-CpG ground-truth methylation tally and bedGraph writer.

Counts, per reference CpG site, how many simulated read mates “called” the site as methylated vs unmethylated based on the simulator’s per-haplotype, per-strand methylation bitmap. The output format matches MethylDackel’s extract CpG .bedGraph exactly:

track type="bedGraph" description="..."
chrom  start  end  rate(0-100)  n_methylated  n_unmethylated

so the same downstream concordance scripts that consume MethylDackel output (e.g. comparing aligner-derived methylation calls to truth) can be pointed at the truth bedGraph without modification.

Counting model

For each simulated read mate (R1 and R2 counted independently — matching MethylDackel’s default per-read tallying):

• For every reference CpG (top-strand CG dinucleotide at top positions (p, p+1)) whose strand-specific C is covered by the mate’s genomic span:
  • CT (top-strand-derived) fragments carry top-strand chemistry; the call is top[hap_pos_for(p)].
  • GA (bottom-strand-derived) fragments carry bottom-strand chemistry; the call is bottom[hap_pos_for(p+1)].
• The call increments n_methylated (bit set) or n_unmethylated (bit clear).

Both R1 and R2 of a directional pair derive from the same source-strand chemistry. When both mates cover the same CpG site (the genomic overlap of the pair), they make the same call (since chemistry is now applied once at fragment scale) and both contribute.

Calls are made against the per-haplotype methylation bitmap, not the post-conversion sequenced base. So the truth reflects the simulator’s biological intent and is unaffected by --methylation-conversion-rate (chemistry inefficiency) or sequencing errors — useful precisely because it lets a downstream evaluator measure how much of the alignment-tool disagreement is due to chemistry/error noise vs alignment failure.

Structs

CpgTruthTally

Per-(contig, top-C reference position) tally of methylated vs unmethylated calls. Indexed by (contig_index, ref_pos_of_top_C); the implied bedGraph end is ref_pos + 1 (matches MethylDackel).