nx_pileup.nx

nx_pileup.nx -- CIGAR walking primitives for variant-calling pileup. license_tier: INDEPENDENT_REDERIVE genealogy_id: international-research-sources/sam-spec-v1.4.6 + li-2009-samtools-pileup G2.1a of NISHI_GENOMICS_SUBSTRATE_ROADMAP.md. The math foundation for variant calling: given an aligned read's CIGAR string and its alignment ref-start, compute "what query base contributes to a specific reference position?" Aggregating this across many reads at a single ref position IS the pileup, and the pileup IS the input to germline + somatic variant callers. CIGAR walking model (SAM-spec consumption flags from nx_cigar): For each op in alignment order: - if consumes_ref: advance ref-position counter by op_len - if consumes_query: advance query-position counter by op_len Until ref-position counter reaches the target. The resulting query-position counter is the read offset of the base that aligns to the target ref position (or in_gap=1 if the target falls inside a D / N op). Why this primitive matters: - Variant calling: aggregate per-position base counts -> SNVs - Indel detection: I/D ops at specific ref positions - Coverage depth: count reads spanning a position - Quality recalibration (BQSR): per-position quality stats - Pileup visualisation (IGV / samtools tview) API: cigar_query_pos_at_ref( cigar_codes, cigar_lens, n_groups, r_start, target_r, out_q_pos, out_in_gap ) -> i64 r_start : reference start position of this alignment (the SAM POS field minus 1 if interpreting SAM 1-indexed; substrate uses 0-indexed throughout) target_r : the reference position we want the read-base for out_q_pos : query offset (0-indexed into read sequence)