codonyat 1.3.1__tar.gz → 1.3.2__tar.gz

{codonyat-1.3.1 → codonyat-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codonyat
-Version: 1.3.1
+Version: 1.3.2
 Summary: codon-yat — A codon-aware (Yet Another) amino acid variant typer from SAM alignments of viral NGS data.
 Author-email: Marc Noguera Julian <info@treetopunder.com>
 License-Expression: MIT

codonyat-1.3.2/aa_caller/aavf.py

@@ -0,0 +1,169 @@
+"""AAVF v1.0 writer. Research use only. Never emits CAT or SRVL."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Sequence
+from datetime import date
+from pathlib import Path
+
+from .constants import PACKAGE_VERSION
+from .genetic_code import codon_to_aminoacid
+from .metrics import classify_flags, is_acgt_codon
+from .models import Variant
+from .reference import FullReference
+
+_AAVF_AA = frozenset("ACDEFGHIKLMNPQRSTVWYX*")
+
+
+def aavf_amino_acid(codon: str) -> str:
+    """Map a codon to an AAVF amino-acid letter (``*`` = stop, ``X`` = other)."""
+    aa = codon_to_aminoacid(codon)
+    if aa == "_":
+        return "*"
+    if aa in _AAVF_AA:
+        return aa
+    return "X"
+
+
+def mark_changed_bases(ref_codon: str, alt_codon: str) -> str:
+    """Lowercase matches to the reference codon; uppercase substitutions.
+
+    Matches the AAVF v1.0 examples (``RC=aaa;AC=aaC``).
+    """
+    ref = ref_codon.lower()
+    alt = alt_codon.lower()
+    marked = []
+    for i, base in enumerate(alt):
+        if i < len(ref) and base == ref[i]:
+            marked.append(base)
+        else:
+            marked.append(base.upper())
+    return "".join(marked)
+
+
+def _fmt_float(value: float) -> str:
+    return f"{value:.6g}"
+
+
+def write_aavf(
+    sample_name: str,
+    reference: FullReference,
+    output_path: Path,
+    protein_pairs: Sequence[tuple[str, dict[int, dict]]],
+    *,
+    min_freq: float,
+    min_coverage: int,
+    sb_alpha: float,
+    file_date: str | None = None,
+) -> None:
+    """Write an AAVF v1.0 file for the counted proteins.
+
+    FILTER codes are the item-1 flags ``lowfreq``, ``sb`` and ``lowcov``.
+    CAT and SRVL are never written. Partial / gapped codons map to ``X``.
+    True amino-acid indels are not called.
+    """
+    dated = file_date or date.today().strftime("%Y%m%d")
+    fasta_name = Path(reference.path).name
+    contig_lines = [
+        f"##contig=<ID={record_id.replace(':', '|')},length={len(reference.sequences[record_id])}>"
+        for record_id in reference.record_ids
+    ]
+    header_lines = [
+        "##fileformat=AAVFv1.0",
+        f"##fileDate={dated}",
+        f"##source=codonyat-{PACKAGE_VERSION} (research use only)",
+        f"##reference={fasta_name}",
+        *contig_lines,
+        '##INFO=<ID=RC,Number=1,Type=String,Description="Reference codon">',
+        '##INFO=<ID=AC,Number=.,Type=String,Description="Alternate codon(s) encoding ALT">',
+        '##INFO=<ID=ACC,Number=.,Type=Integer,Description="Alternate codon counts, same order as AC">',
+        '##INFO=<ID=ACF,Number=.,Type=Float,Description="Alternate codon frequencies, same order as AC">',
+        '##INFO=<ID=FWC,Number=1,Type=Integer,Description="Forward-strand coverage at the codon">',
+        '##INFO=<ID=RVC,Number=1,Type=Integer,Description="Reverse-strand coverage at the codon">',
+        '##INFO=<ID=SR,Number=1,Type=Float,Description="Forward/reverse coverage ratio at the codon">',
+        '##FILTER=<ID=lowfreq,Description="ALT frequency below --min-freq">',
+        '##FILTER=<ID=sb,Description="Strand-bias Fisher p-value below --sb-alpha">',
+        '##FILTER=<ID=lowcov,Description="Codon coverage below --min-coverage">',
+        "#CHROM\tGENE\tPOS\tREF\tALT\tFILTER\tALT_FREQ\tCOVERAGE\tINFO",
+    ]
+
+    # Stream rows instead of accumulating the whole file in a list; output can
+    # be large when many variants are called and there is no need to hold it.
+    with open(output_path, "w") as handle:
+        handle.write("\n".join(header_lines) + "\n")
+
+        for protein_name, entries in protein_pairs:
+            # aa_pos then genomic position; keeps GENE blocks contiguous.
+            ordered = sorted(
+                entries.items(),
+                key=lambda item: (item[1].get("aa_pos", item[0]), item[0]),
+            )
+            for pos, entry in ordered:
+                depth = int(entry["depth"])
+                if depth <= 0:
+                    continue
+                record_id = str(entry.get("record_id", reference.id)).replace(":", "|")
+                gene = protein_name.replace(":", "|")
+                aa_pos = int(entry.get("aa_pos", 0)) or "."
+                ref_codon = reference.get_seq_at(
+                    pos, 3, entry.get("record_id"), positions=entry.get("codon_coords")
+                )
+                ref_aa = aavf_amino_acid(ref_codon) if ref_codon else "X"
+                fw_depth = int(entry["fw_depth"])
+                rv_depth = int(entry["rv_depth"])
+                sr = (fw_depth / rv_depth) if rv_depth else 0.0
+
+                by_aa: dict[str, list[Variant]] = defaultdict(list)
+                for variant in entry["variants"].values():
+                    by_aa[aavf_amino_acid(variant.codon)].append(variant)
+
+                for alt_aa, variants in by_aa.items():
+                    alt_count = sum(v.count for v in variants)
+                    alt_fw = sum(v.fw_reads for v in variants)
+                    alt_rv = sum(v.rv_reads for v in variants)
+                    alt_freq = (alt_count / depth) if depth else 0.0
+                    flags, _p = classify_flags(
+                        freq=alt_freq,
+                        coverage=depth,
+                        fw=alt_fw,
+                        rv=alt_rv,
+                        other_fw=fw_depth - alt_fw,
+                        other_rv=rv_depth - alt_rv,
+                        min_freq=min_freq,
+                        min_coverage=min_coverage,
+                        sb_alpha=sb_alpha,
+                    )
+                    filter_field = ";".join(flags) if flags else "PASS"
+                    ac_parts = []
+                    acc_parts = []
+                    acf_parts = []
+                    for variant in variants:
+                        codon = variant.codon
+                        labelled = mark_changed_bases(ref_codon, codon) if is_acgt_codon(codon) else codon.lower()
+                        ac_parts.append(labelled)
+                        acc_parts.append(str(int(variant.count)))
+                        acf_parts.append(_fmt_float(variant.count / depth if depth else 0.0))
+                    info = (
+                        f"RC={ref_codon.lower()};"
+                        f"AC={','.join(ac_parts)};"
+                        f"ACC={','.join(acc_parts)};"
+                        f"ACF={','.join(acf_parts)};"
+                        f"FWC={fw_depth};RVC={rv_depth};SR={_fmt_float(sr)}"
+                    )
+                    handle.write(
+                        "\t".join(
+                            [
+                                record_id,
+                                gene,
+                                str(aa_pos),
+                                ref_aa,
+                                alt_aa,
+                                filter_field,
+                                _fmt_float(alt_freq),
+                                str(depth),
+                                info,
+                            ]
+                        )
+                        + "\n"
+                    )

{codonyat-1.3.1 → codonyat-1.3.2}/aa_caller/cli.py

@@ -108,8 +108,6 @@ def main() -> None:
         min_baseq=args.min_baseq,
         collapsed_read_counts=args.collapsed_read_counts,
     )
-    container.load()
-
     logger.info("Calculating %s variant frequencies", ",".join(protein_names))
     container.calculate_for_proteins(proteins, reference)
 

{codonyat-1.3.1 → codonyat-1.3.2}/aa_caller/constants.py

@@ -6,7 +6,7 @@ DEFAULT_ENTROPY_THRESHOLD = 0.0
 DEFAULT_PROTEIN = "RT"
 
 # Opt-in research statistics (v1.3.0). Unused unless --stats / --aavf / --min-baseq is set.
-PACKAGE_VERSION = "1.3.1"
+PACKAGE_VERSION = "1.3.2"
 WILSON_Z_95 = 1.959963984540054  # Φ^{-1}(0.975)
 DEFAULT_MIN_FREQ = 0.01
 DEFAULT_MIN_COVERAGE = 10

{codonyat-1.3.1 → codonyat-1.3.2}/aa_caller/container.py

@@ -4,7 +4,8 @@ import csv
 import logging
 import math
 import xml.etree.ElementTree as ET
-from collections.abc import Sequence
+from bisect import bisect_left, bisect_right
+from collections.abc import Iterator, Sequence
 from pathlib import Path
 
 from .genetic_code import codon_to_aminoacid
@@ -15,6 +16,65 @@ from .sam import SamEntry
 logger = logging.getLogger(__name__)
 
 
+class _ReadCollection(Sequence[SamEntry]):
+    """Lazy, re-iterable view over the mapped records in a SAM file.
+
+    ``SamContainer.load`` used to materialise every mapped read in a list. Each
+    ``SamEntry`` cached a reference-position → read-position dict, so a 1 kb
+    read cost roughly 100 KB. With a few million reads that easily exhausts
+    memory. This view keeps only the path and streams the file on each pass;
+    ``read`` aggregation therefore uses O(1) memory in the sample size.
+
+    It still behaves as a read-only sequence (``len``, iteration, indexing) so
+    existing code that inspects ``SamContainer.reads`` keeps working.
+    """
+
+    def __init__(self, path: Path, collapsed_read_counts: bool = False) -> None:
+        self.path = Path(path)
+        self.collapsed_read_counts = collapsed_read_counts
+        self._count: int | None = None
+
+    def __iter__(self) -> Iterator[SamEntry]:
+        count = 0
+        with open(self.path) as fh:
+            for line in fh:
+                if line.startswith("@"):
+                    continue
+                entry = SamEntry(line, collapsed_read_counts=self.collapsed_read_counts)
+                if entry.is_mapped():
+                    count += 1
+                    yield entry
+        # Cache the count after a complete pass so ``len()`` does not rescan.
+        self._count = count
+
+    def __len__(self) -> int:
+        if self._count is None:
+            # Count without building SamEntry objects (which would decode the
+            # CIGAR and sequence for every alignment just to report a length).
+            count = 0
+            with open(self.path) as fh:
+                for line in fh:
+                    if line.startswith("@"):
+                        continue
+                    fields = line.split("\t", 2)
+                    if not (int(fields[1]) & 4):
+                        count += 1
+            self._count = count
+        return self._count
+
+    def __getitem__(self, index: int | slice):
+        if isinstance(index, slice):
+            return list(self)[index]
+        if index < 0:
+            index += len(self)
+        if index < 0:
+            raise IndexError("read index out of range")
+        for current, entry in enumerate(self):
+            if current == index:
+                return entry
+        raise IndexError("read index out of range")
+
+
 class SamContainer:
     """Aggregates SAM entries and computes RT variant statistics for an amplicon set."""
 
@@ -29,7 +89,10 @@ class SamContainer:
     ) -> None:
         """Initialize the container with the SAM path, ratio window, and entropy threshold."""
         self.sam_path = sam_path
-        self.reads: list[SamEntry] = []
+        # Streaming view: no alignment records are retained between passes.
+        self.reads: Sequence[SamEntry] = _ReadCollection(
+            sam_path, collapsed_read_counts=collapsed_read_counts
+        )
         self.variants: dict[int, dict] = {}
         self.protein_variants: dict[str, dict[int, dict]] = {}
         self._protein_result_list: list[tuple[str, dict[int, dict]]] = []
@@ -40,14 +103,13 @@ class SamContainer:
         self.collapsed_read_counts = collapsed_read_counts
 
     def load(self) -> None:
-        """Load every mapped read from the SAM file so they can be aggregated."""
-        with open(self.sam_path) as fh:
-            for line in fh:
-                if line.startswith("@"):
-                    continue
-                entry = SamEntry(line, collapsed_read_counts=self.collapsed_read_counts)
-                if entry.is_mapped():
-                    self.reads.append(entry)
+        """Prepare the streaming read view (kept for API compatibility).
+
+        Reads are parsed and aggregated in :meth:`calculate_for_proteins` rather
+        than retained. This method still validates the file by counting mapped
+        records without storing them, so ``len(container.reads)`` works as before.
+        """
+        len(self.reads)
 
     def calculate_variant_frequencies(
         self, protein_name: str, reference: FullReference, record_id: str | None = None
@@ -83,15 +145,24 @@ class SamContainer:
         self.calculate_for_proteins(proteins, reference)
 
     def calculate_for_proteins(self, proteins: Sequence[Protein], reference: FullReference) -> None:
-        """Count every requested protein in one pass over ``self.reads``.
+        """Count every requested protein in one streaming pass over the SAM file.
 
         Supports multi-record references (reads are matched by RNAME) and
-        multi-interval proteins.
+        multi-interval proteins. Only per-position aggregate state is retained;
+        alignment records are released as soon as they have been counted.
+
+        For each read we look up the codons whose coordinates lie inside the
+        read's aligned reference span instead of walking every codon of the
+        protein. That keeps both memory and CPU proportional to the covered
+        bases rather than to reads × protein length.
         """
         if not proteins:
             raise ValueError("At least one protein is required")
 
-        jobs: list[tuple[Protein, dict[int, dict]]] = []
+        # Each job: (protein, entries, sorted codon starts, codon spans).
+        jobs: list[
+            tuple[Protein, dict[int, dict], list[int], list[tuple[int, int]]]
+        ] = []
         for protein in proteins:
             entries: dict[int, dict] = {}
             aa_pos = 0
@@ -107,18 +178,44 @@ class SamContainer:
                     "aa_pos": aa_pos,
                     "codon_coords": codon_coords,
                 }
-            jobs.append((protein, entries))
+            starts = sorted(entries)
+            spans = [
+                (
+                    min(entries[pos]["codon_coords"]),
+                    max(entries[pos]["codon_coords"]),
+                )
+                for pos in starts
+            ]
+            jobs.append((protein, entries, starts, spans))
+
+        jobs_by_record: dict[str, list[tuple[Protein, dict[int, dict], list[int], list[tuple[int, int]]]]] = {}
+        for job in jobs:
+            jobs_by_record.setdefault(job[0].record_id, []).append(job)
 
         for read in self.reads:
-            for protein, entries in jobs:
-                if read.reference != protein.record_id:
-                    continue
-                for pos, entry in entries.items():
-                    self._accumulate_read_at_position(read, pos, entry)
+            if not read.is_mapped():
+                continue
+            read_jobs = jobs_by_record.get(read.reference)
+            if not read_jobs:
+                continue
+            span_start = read.coordinate
+            span_end = read.reference_end
+            for _protein, entries, starts, spans in read_jobs:
+                # Codons entirely outside the read cannot contribute. Using the
+                # first codon coordinate as the sorted key is sufficient: every
+                # other coordinate is checked before counting.
+                left = bisect_left(starts, span_start)
+                right = bisect_right(starts, span_end)
+                for index in range(left, right):
+                    codon_min, codon_max = spans[index]
+                    if codon_min < span_start or codon_max > span_end:
+                        continue
+                    pos = starts[index]
+                    self._accumulate_read_at_position(read, pos, entries[pos])
 
         self.protein_variants = {}
         self._protein_result_list = []
-        for protein, entries in jobs:
+        for protein, entries, _starts, _spans in jobs:
             self.variants = entries
             for pos in self.variants:
                 self.calculate_ratios_nucleotide(pos)
@@ -134,8 +231,8 @@ class SamContainer:
         codon_coords = entry.get("codon_coords")
         if codon_coords is None:
             codon_coords = (pos, pos + 1, pos + 2)
-        if not any(read.covers(coord) for coord in codon_coords):
-            return
+        # ``codon_at`` returns None when any of the three coordinates is outside
+        # the read's aligned span, so a separate covers() sweep is unnecessary.
         codon = read.codon_at(pos, positions=codon_coords)
         if not codon or len(codon) < 3:
             return
@@ -179,14 +276,15 @@ class SamContainer:
         part coordinates (for example positions 10, 11, 12 of 1-10;11-30).
         Incomplete trailing bases at the end of the protein are dropped.
         """
-        coding_bases: list[int] = []
+        positions: list[tuple] = []
+        pending: list[int] = []
         for interval in protein.intervals:
-            coding_bases.extend(range(interval.start, interval.end + 1))
-
-        positions = []
-        for i in range(0, len(coding_bases) // 3 * 3, 3):
-            codon_coords = (coding_bases[i], coding_bases[i + 1], coding_bases[i + 2])
-            positions.append((codon_coords[0], protein.record_id, codon_coords))
+            for coordinate in range(interval.start, interval.end + 1):
+                pending.append(coordinate)
+                if len(pending) == 3:
+                    codon_coords = (pending[0], pending[1], pending[2])
+                    positions.append((codon_coords[0], protein.record_id, codon_coords))
+                    pending.clear()
         return positions
 
     def calculate_ratios_nucleotide(self, position: int) -> None:
@@ -361,26 +459,73 @@ class SamContainer:
         return pairs
 
     @staticmethod
-    def _add_positions(parent: ET.Element, entries: dict[int, dict]) -> None:
+    def _position_element(pos: int, entry: dict) -> ET.Element:
+        position_elem = ET.Element("Position", index=str(pos))
+        ET.SubElement(position_elem, "Depth").text = str(entry["depth"])
+        ET.SubElement(position_elem, "FwCover").text = str(entry["fw_depth"])
+        ET.SubElement(position_elem, "RvCover").text = str(entry["rv_depth"])
+        variants_elem = ET.SubElement(position_elem, "Variants")
+        for variant in entry["variants"].values():
+            # describe each variant using XML attributes for diagnostics
+            var_elem = ET.SubElement(variants_elem, "Variant", codon=variant.codon)
+            var_elem.set("count", str(variant.count))
+            var_elem.set("fw_reads", str(variant.fw_reads))
+            var_elem.set("rv_reads", str(variant.rv_reads))
+        return position_elem
+
+    @classmethod
+    def _iter_position_xml(cls, entries: dict[int, dict]) -> Iterator[str]:
+        """Serialise one position at a time so the full XML tree is never held."""
         for pos, entry in sorted(entries.items()):
-            position_elem = ET.SubElement(parent, "Position", index=str(pos))
-            ET.SubElement(position_elem, "Depth").text = str(entry["depth"])
-            ET.SubElement(position_elem, "FwCover").text = str(entry["fw_depth"])
-            ET.SubElement(position_elem, "RvCover").text = str(entry["rv_depth"])
-            variants_elem = ET.SubElement(position_elem, "Variants")
-            for variant in entry["variants"].values():
-                # describe each variant using XML attributes for diagnostics
-                var_elem = ET.SubElement(variants_elem, "Variant", codon=variant.codon)
-                var_elem.set("count", str(variant.count))
-                var_elem.set("fw_reads", str(variant.fw_reads))
-                var_elem.set("rv_reads", str(variant.rv_reads))
+            yield ET.tostring(
+                cls._position_element(pos, entry),
+                encoding="unicode",
+                short_empty_elements=True,
+            )
+
+    @staticmethod
+    def _open_tag(tag: str, **attributes: str) -> str:
+        """Return the opening tag for an empty element, in ElementTree style."""
+        empty = ET.tostring(
+            ET.Element(tag, attributes), encoding="unicode", short_empty_elements=True
+        )
+        # ElementTree serialises an empty element as ``<tag ... />``.
+        return empty[:-3] + ">"
+
+    def _write_xml_tree(
+        self,
+        sample_name: str,
+        reference: FullReference,
+        output_path: Path,
+        protein_pairs: Sequence[tuple[str, dict[int, dict]]],
+        *,
+        wrap_proteins: bool,
+    ) -> None:
+        with open(output_path, "w", encoding="utf-8", newline="") as handle:
+            handle.write("<?xml version='1.0' encoding='utf-8'?>\n")
+            handle.write(
+                self._open_tag(
+                    "SamContainer", sample=sample_name, reference=reference.id
+                )
+            )
+            for protein_name, entries in protein_pairs:
+                if wrap_proteins:
+                    handle.write(self._open_tag("Protein", name=protein_name))
+                for chunk in self._iter_position_xml(entries):
+                    handle.write(chunk)
+                if wrap_proteins:
+                    handle.write("</Protein>")
+            handle.write("</SamContainer>")
 
     def write_xml(self, sample_name: str, reference: FullReference, output_path: Path) -> None:
         """Dump the per-position state of the (first) protein into XML for diagnostics."""
-        root = ET.Element("SamContainer", sample=sample_name, reference=reference.id)
-        self._add_positions(root, self.variants)
-        tree = ET.ElementTree(root)
-        tree.write(output_path, encoding="utf-8", xml_declaration=True)
+        self._write_xml_tree(
+            sample_name,
+            reference,
+            output_path,
+            [("", self.variants)],
+            wrap_proteins=False,
+        )
 
     def write_xml_proteins(
         self,
@@ -393,12 +538,13 @@ class SamContainer:
 
         For a single protein use :meth:`write_xml`, whose layout is unchanged.
         """
-        root = ET.Element("SamContainer", sample=sample_name, reference=reference.id)
-        for protein_name, entries in self._output_pairs(protein_names):
-            protein_elem = ET.SubElement(root, "Protein", name=protein_name)
-            self._add_positions(protein_elem, entries)
-        tree = ET.ElementTree(root)
-        tree.write(output_path, encoding="utf-8", xml_declaration=True)
+        self._write_xml_tree(
+            sample_name,
+            reference,
+            output_path,
+            self._output_pairs(protein_names),
+            wrap_proteins=True,
+        )
 
     def write_stats(
         self,

{codonyat-1.3.1 → codonyat-1.3.2}/aa_caller/runner.py

@@ -90,7 +90,6 @@ def call_variants(
         min_baseq=min_baseq,
         collapsed_read_counts=collapsed_read_counts,
     )
-    container.load()
     proteins = resolve_protein_targets(protein_spec, reference)
     protein_names = [item.name for item in proteins]
     container.calculate_for_proteins(proteins, reference)

codonyat-1.3.2/aa_caller/sam.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+__all__ = ["SamEntry"]
+
+import re
+from bisect import bisect_right
+from collections.abc import Sequence
+
+from .models import Qual
+
+# Compiled once at module load — reused across every SamEntry instance.
+_CIGAR_RE = re.compile(r"(\d+)([MIDNSHP=X])")
+_AMPLICON_RE = re.compile(r"(Amp_[0-9]+)")
+
+# Sentinel returned by the CIGAR lookup for reference positions that the read
+# does not span. A read index of -1 means the reference base is deleted/skipped.
+_MISSING = None
+
+
+class SamEntry:
+    """Wraps a SAM record with convenience helpers used during variant aggregation.
+
+    The CIGAR is represented as a small list of reference/query blocks instead
+    of a ``{reference_position: read_position}`` dictionary. The dictionary
+    version cost ~100 KB per 1 kb read, which made whole-SAM loading impractical
+    for real sample sizes. Blocks are indexed with ``bisect`` and use O(number
+    of CIGAR ops) memory per read.
+    """
+
+    def __init__(self, line: str, collapsed_read_counts: bool = False) -> None:
+        """Parse a single SAM line and cache derived attributes that the pipeline needs."""
+        self.raw = line.strip()
+        self.fields = self.raw.split("\t")
+        self.identifier = self.fields[0]
+        self.flag = int(self.fields[1])
+        self.reference = self.fields[2]
+        self.coordinate = int(self.fields[3])
+        self.map_quality = int(self.fields[4])
+        self.cigar = self.fields[5]
+        self.sequence = self.fields[9]
+        self.quality_string = self.fields[10]
+        self.options = self.fields[11:]
+        self.orientation = self._determine_orientation()
+        self.collapsed_read_counts = collapsed_read_counts
+        self.occurences = self._parse_occurences()
+
+        cigar_ops = _CIGAR_RE.findall(self.cigar)
+        self._reference_covered_length = self._compute_reference_covered_length(cigar_ops)
+        self._reference_end = (
+            self.coordinate + self._reference_covered_length - 1
+            if self._reference_covered_length
+            else self.coordinate - 1
+        )
+        self._cigar_blocks, self._block_starts = self._build_cigar_blocks(cigar_ops)
+
+        # Quality decoding is only needed when --min-baseq is enabled. Keep the
+        # raw string (already part of ``fields``) and build the numeric array lazily.
+        self._quality_cache: Qual | None = None
+        self.amplicon = self._parse_amplicon()
+
+    @property
+    def reference_end(self) -> int:
+        """Last reference position spanned by the CIGAR (inclusive)."""
+        return self._reference_end
+
+    @property
+    def _quality(self) -> Qual:
+        """Lazily decode the SAM quality string on first use."""
+        if self._quality_cache is None:
+            self._quality_cache = Qual(self.quality_string, "sanger")
+        return self._quality_cache
+
+    def _determine_orientation(self) -> str:
+        """Return whether the read is mapped to the forward or reverse strand."""
+        if self.flag & 16:
+            return "R"
+        return "F"
+
+    def _parse_occurences(self) -> int:
+        """Return how many observations this SAM row represents.
+
+        By default each row counts once. With ``collapsed_read_counts``, a
+        read name ending in ``_<digits>`` is treated as that many duplicates.
+        """
+        if not self.collapsed_read_counts:
+            return 1
+        parts = self.identifier.split("_")
+        tail = parts[-1]
+        if tail.isdigit():
+            return max(1, int(tail))
+        return 1
+
+    @staticmethod
+    def _compute_reference_covered_length(cigar_ops: list[tuple[str, str]]) -> int:
+        """Sum the CIGAR operations that consume reference bases to get coverage."""
+        total = 0
+        for length, op in cigar_ops:
+            if op in "MDN=X":
+                total += int(length)
+        return total
+
+    def _build_cigar_blocks(
+        self, cigar_ops: list[tuple[str, str]]
+    ) -> tuple[list[tuple[int, int, int, bool]], list[int]]:
+        """Build compact (ref_start, ref_end, read_start, is_gap) query blocks.
+
+        The previous implementation stored one dict entry per reference base.
+        Blocks keep exactly the same lookup semantics with much less memory:
+        reference positions outside every block are absent, positions inside a
+        D/N block map to a gap, and M/=/X positions map linearly to the query.
+        """
+        blocks: list[tuple[int, int, int, bool]] = []
+        starts: list[int] = []
+        ref_pos = self.coordinate
+        read_pos = 0
+        for length_str, op in cigar_ops:
+            length = int(length_str)
+            if op in "M=X":
+                blocks.append((ref_pos, ref_pos + length, read_pos, False))
+                starts.append(ref_pos)
+                ref_pos += length
+                read_pos += length
+            elif op == "I":
+                # I consumes the query only; D/N consume the reference only.
+                read_pos += length
+            elif op in "DN":
+                blocks.append((ref_pos, ref_pos + length, -1, True))
+                starts.append(ref_pos)
+                ref_pos += length
+            elif op == "S":
+                read_pos += length
+            # H and P consume neither
+        return blocks, starts
+
+    def _block_index(self, reference_position: int) -> int | None:
+        """Return the CIGAR block covering ``reference_position``, or None."""
+        index = bisect_right(self._block_starts, reference_position) - 1
+        if index < 0:
+            return _MISSING
+        if reference_position >= self._cigar_blocks[index][1]:
+            return _MISSING
+        return index
+
+    def _read_index(self, reference_position: int) -> int | None:
+        """Map a reference position to a query index, -1 for a gap, or None.
+
+        ``None`` means the position is outside the aligned reference span.
+        """
+        index = self._block_index(reference_position)
+        if index is None:
+            return _MISSING
+        ref_start, _ref_end, read_start, is_gap = self._cigar_blocks[index]
+        if is_gap:
+            return -1
+        return read_start + (reference_position - ref_start)
+
+    def _parse_amplicon(self) -> str:
+        """Extract the amplicon tag embedded in the read identifier, if present."""
+        match = _AMPLICON_RE.search(self.identifier)
+        if match:
+            return match.group(1)
+        return "Amp_NONE"
+
+    def covers(self, position: int) -> bool:
+        """Check whether this read spans the requested reference position."""
+        return self.coordinate <= position <= self._reference_end
+
+    def _codon_ref_positions(
+        self, position: int, positions: Sequence[int] | None = None
+    ) -> tuple[int, int, int]:
+        """Resolve the three reference bases of a codon.
+
+        ``positions`` is the actual part coordinates (needed when a codon
+        crosses a multi-interval junction). Consecutive ``position..+2`` is
+        used only when the caller does not supply them.
+        """
+        if positions is not None:
+            coords = tuple(int(p) for p in positions)
+            if len(coords) != 3:
+                raise ValueError("codon positions must contain exactly three coordinates")
+            return coords[0], coords[1], coords[2]
+        return position, position + 1, position + 2
+
+    def codon_at(self, position: int, positions: Sequence[int] | None = None) -> str | None:
+        """Return the codon at the given reference coordinates using the CIGAR-aware mapping."""
+        coords = self._codon_ref_positions(position, positions)
+
+        # Fast path: the common consecutive codon fully inside one M/=/X block.
+        if coords[1] == coords[0] + 1 and coords[2] == coords[0] + 2:
+            block = self._block_index(coords[0])
+            if block is not None:
+                ref_start, ref_end, read_start, is_gap = self._cigar_blocks[block]
+                if not is_gap and coords[2] < ref_end:
+                    start = read_start + (coords[0] - ref_start)
+                    return self.sequence[start : start + 3]
+
+        bases = []
+        for ref_pos in coords:
+            read_idx = self._read_index(ref_pos)
+            if read_idx is None:
+                return None
+            bases.append("-" if read_idx < 0 else self.sequence[read_idx])
+        return "".join(bases)
+
+    def codon_qualities_at(
+        self, position: int, positions: Sequence[int] | None = None
+    ) -> list[float] | None:
+        """Return Phred-like qualities for the three codon bases, or None if any is missing/gapped."""
+        quals: list[float] = []
+        for ref_pos in self._codon_ref_positions(position, positions):
+            read_idx = self._read_index(ref_pos)
+            if read_idx is None or read_idx < 0:
+                return None
+            quals.append(self._quality.return_quality_by_pos(read_idx))
+        return quals
+
+    def is_mapped(self) -> bool:
+        """True when the read is not flagged as unmapped."""
+        return not (self.flag & 4)

{codonyat-1.3.1 → codonyat-1.3.2}/aa_caller/stats_writer.py

@@ -10,7 +10,6 @@ from .genetic_code import codon_to_aminoacid
 from .metrics import (
     classify_flags,
     diversity_from_codon_counts,
-    mean_or_zero,
     wilson_ci,
 )
 from .reference import FullReference
@@ -70,7 +69,11 @@ def write_stats_tsv(
         writer = csv.DictWriter(handle, fieldnames=STATS_FIELDS, delimiter="\t")
         writer.writeheader()
         for protein_name, entries in protein_pairs:
-            codon_divs: list[dict[str, float]] = []
+            # Running sums for the gene-level row: storing one dict per codon
+            # would scale with protein length for no benefit.
+            n_codons = 0
+            sum_shannon = sum_shannon_norm = 0.0
+            sum_gini = sum_pi_nt = sum_pi_aa = 0.0
             ordered = sorted(
                 entries.items(),
                 key=lambda item: (item[1].get("aa_pos", item[0]), item[0]),
@@ -84,7 +87,12 @@ def write_stats_tsv(
                 codon_counts = {variant.codon: float(variant.count) for variant in entry["variants"].values()}
                 diversity = diversity_from_codon_counts(codon_counts)
                 if diversity["n_valid"] > 0:
-                    codon_divs.append(diversity)
+                    n_codons += 1
+                    sum_shannon += diversity["shannon"]
+                    sum_shannon_norm += diversity["shannon_norm"]
+                    sum_gini += diversity["gini_simpson"]
+                    sum_pi_nt += diversity["pi_nt"]
+                    sum_pi_aa += diversity["pi_aa"]
 
                 for variant in entry["variants"].values():
                     freq = (variant.count / depth) if depth else 0.0
@@ -181,12 +189,12 @@ def write_stats_tsv(
                     "SB_P": _blank(),
                     "FLAGS": _blank(),
                     "COVERAGE": _blank(),
-                    "SHANNON": _fmt(mean_or_zero(d["shannon"] for d in codon_divs)),
-                    "SHANNON_NORM": _fmt(mean_or_zero(d["shannon_norm"] for d in codon_divs)),
-                    "GINI_SIMPSON": _fmt(mean_or_zero(d["gini_simpson"] for d in codon_divs)),
-                    "PI_NT": _fmt(mean_or_zero(d["pi_nt"] for d in codon_divs)),
-                    "PI_AA": _fmt(mean_or_zero(d["pi_aa"] for d in codon_divs)),
+                    "SHANNON": _fmt(sum_shannon / n_codons if n_codons else 0.0),
+                    "SHANNON_NORM": _fmt(sum_shannon_norm / n_codons if n_codons else 0.0),
+                    "GINI_SIMPSON": _fmt(sum_gini / n_codons if n_codons else 0.0),
+                    "PI_NT": _fmt(sum_pi_nt / n_codons if n_codons else 0.0),
+                    "PI_AA": _fmt(sum_pi_aa / n_codons if n_codons else 0.0),
                     "N_TYPES": _blank(),
-                    "N_CODONS": len(codon_divs),
+                    "N_CODONS": n_codons,
                 }
             )

{codonyat-1.3.1 → codonyat-1.3.2}/aa_caller/validators.py

@@ -33,16 +33,20 @@ def validate_reference_file(
     ``protein_name`` may be one name, a comma-separated list, or ``all``
     (which only requires the FASTA to be readable).
     """
-    records = list(SeqIO.parse(str(path), "fasta"))
-    if not records:
+    record_count = 0
+    annotated_names: set[str] = set()
+    for record in SeqIO.parse(str(path), "fasta"):
+        record_count += 1
+        if annotation_path is None:
+            annotated_names.update(
+                protein.name for protein in proteins_from_fasta_record(record)
+            )
+    if record_count == 0:
         raise ValueError(f"Reference file {path} is empty or not FASTA")
 
     if annotation_path:
         return
 
-    annotated_names = {
-        protein.name for record in records for protein in proteins_from_fasta_record(record)
-    }
     for name in protein_name.split(","):
         name = name.strip()
         if not name or name.lower() == "all":

{codonyat-1.3.1 → codonyat-1.3.2}/codonyat.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codonyat
-Version: 1.3.1
+Version: 1.3.2
 Summary: codon-yat — A codon-aware (Yet Another) amino acid variant typer from SAM alignments of viral NGS data.
 Author-email: Marc Noguera Julian <info@treetopunder.com>
 License-Expression: MIT

{codonyat-1.3.1 → codonyat-1.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codonyat"
-version = "1.3.1"
+version = "1.3.2"
 description = "codon-yat — A codon-aware (Yet Another) amino acid variant typer from SAM alignments of viral NGS data."
 readme = "README.md"
 requires-python = ">=3.10"

codonyat-1.3.1/aa_caller/aavf.py

@@ -1,165 +0,0 @@
-"""AAVF v1.0 writer. Research use only. Never emits CAT or SRVL."""
-
-from __future__ import annotations
-
-from collections import defaultdict
-from collections.abc import Sequence
-from datetime import date
-from pathlib import Path
-
-from .constants import PACKAGE_VERSION
-from .genetic_code import codon_to_aminoacid
-from .metrics import classify_flags, is_acgt_codon
-from .models import Variant
-from .reference import FullReference
-
-_AAVF_AA = frozenset("ACDEFGHIKLMNPQRSTVWYX*")
-
-
-def aavf_amino_acid(codon: str) -> str:
-    """Map a codon to an AAVF amino-acid letter (``*`` = stop, ``X`` = other)."""
-    aa = codon_to_aminoacid(codon)
-    if aa == "_":
-        return "*"
-    if aa in _AAVF_AA:
-        return aa
-    return "X"
-
-
-def mark_changed_bases(ref_codon: str, alt_codon: str) -> str:
-    """Lowercase matches to the reference codon; uppercase substitutions.
-
-    Matches the AAVF v1.0 examples (``RC=aaa;AC=aaC``).
-    """
-    ref = ref_codon.lower()
-    alt = alt_codon.lower()
-    marked = []
-    for i, base in enumerate(alt):
-        if i < len(ref) and base == ref[i]:
-            marked.append(base)
-        else:
-            marked.append(base.upper())
-    return "".join(marked)
-
-
-def _fmt_float(value: float) -> str:
-    return f"{value:.6g}"
-
-
-def write_aavf(
-    sample_name: str,
-    reference: FullReference,
-    output_path: Path,
-    protein_pairs: Sequence[tuple[str, dict[int, dict]]],
-    *,
-    min_freq: float,
-    min_coverage: int,
-    sb_alpha: float,
-    file_date: str | None = None,
-) -> None:
-    """Write an AAVF v1.0 file for the counted proteins.
-
-    FILTER codes are the item-1 flags ``lowfreq``, ``sb`` and ``lowcov``.
-    CAT and SRVL are never written. Partial / gapped codons map to ``X``.
-    True amino-acid indels are not called.
-    """
-    dated = file_date or date.today().strftime("%Y%m%d")
-    fasta_name = Path(reference.path).name
-    contig_lines = [
-        f"##contig=<ID={record_id.replace(':', '|')},length={len(reference.sequences[record_id])}>"
-        for record_id in reference.record_ids
-    ]
-    lines = [
-        "##fileformat=AAVFv1.0",
-        f"##fileDate={dated}",
-        f"##source=codonyat-{PACKAGE_VERSION} (research use only)",
-        f"##reference={fasta_name}",
-        *contig_lines,
-        '##INFO=<ID=RC,Number=1,Type=String,Description="Reference codon">',
-        '##INFO=<ID=AC,Number=.,Type=String,Description="Alternate codon(s) encoding ALT">',
-        '##INFO=<ID=ACC,Number=.,Type=Integer,Description="Alternate codon counts, same order as AC">',
-        '##INFO=<ID=ACF,Number=.,Type=Float,Description="Alternate codon frequencies, same order as AC">',
-        '##INFO=<ID=FWC,Number=1,Type=Integer,Description="Forward-strand coverage at the codon">',
-        '##INFO=<ID=RVC,Number=1,Type=Integer,Description="Reverse-strand coverage at the codon">',
-        '##INFO=<ID=SR,Number=1,Type=Float,Description="Forward/reverse coverage ratio at the codon">',
-        '##FILTER=<ID=lowfreq,Description="ALT frequency below --min-freq">',
-        '##FILTER=<ID=sb,Description="Strand-bias Fisher p-value below --sb-alpha">',
-        '##FILTER=<ID=lowcov,Description="Codon coverage below --min-coverage">',
-        "#CHROM\tGENE\tPOS\tREF\tALT\tFILTER\tALT_FREQ\tCOVERAGE\tINFO",
-    ]
-
-    for protein_name, entries in protein_pairs:
-        # aa_pos then genomic position; keeps GENE blocks contiguous.
-        ordered = sorted(
-            entries.items(),
-            key=lambda item: (item[1].get("aa_pos", item[0]), item[0]),
-        )
-        for pos, entry in ordered:
-            depth = int(entry["depth"])
-            if depth <= 0:
-                continue
-            record_id = str(entry.get("record_id", reference.id)).replace(":", "|")
-            gene = protein_name.replace(":", "|")
-            aa_pos = int(entry.get("aa_pos", 0)) or "."
-            ref_codon = reference.get_seq_at(
-                pos, 3, entry.get("record_id"), positions=entry.get("codon_coords")
-            )
-            ref_aa = aavf_amino_acid(ref_codon) if ref_codon else "X"
-            fw_depth = int(entry["fw_depth"])
-            rv_depth = int(entry["rv_depth"])
-            sr = (fw_depth / rv_depth) if rv_depth else 0.0
-
-            by_aa: dict[str, list[Variant]] = defaultdict(list)
-            for variant in entry["variants"].values():
-                by_aa[aavf_amino_acid(variant.codon)].append(variant)
-
-            for alt_aa, variants in by_aa.items():
-                alt_count = sum(v.count for v in variants)
-                alt_fw = sum(v.fw_reads for v in variants)
-                alt_rv = sum(v.rv_reads for v in variants)
-                alt_freq = (alt_count / depth) if depth else 0.0
-                flags, _p = classify_flags(
-                    freq=alt_freq,
-                    coverage=depth,
-                    fw=alt_fw,
-                    rv=alt_rv,
-                    other_fw=fw_depth - alt_fw,
-                    other_rv=rv_depth - alt_rv,
-                    min_freq=min_freq,
-                    min_coverage=min_coverage,
-                    sb_alpha=sb_alpha,
-                )
-                filter_field = ";".join(flags) if flags else "PASS"
-                ac_parts = []
-                acc_parts = []
-                acf_parts = []
-                for variant in variants:
-                    codon = variant.codon
-                    labelled = mark_changed_bases(ref_codon, codon) if is_acgt_codon(codon) else codon.lower()
-                    ac_parts.append(labelled)
-                    acc_parts.append(str(int(variant.count)))
-                    acf_parts.append(_fmt_float(variant.count / depth if depth else 0.0))
-                info = (
-                    f"RC={ref_codon.lower()};"
-                    f"AC={','.join(ac_parts)};"
-                    f"ACC={','.join(acc_parts)};"
-                    f"ACF={','.join(acf_parts)};"
-                    f"FWC={fw_depth};RVC={rv_depth};SR={_fmt_float(sr)}"
-                )
-                lines.append(
-                    "\t".join(
-                        [
-                            record_id,
-                            gene,
-                            str(aa_pos),
-                            ref_aa,
-                            alt_aa,
-                            filter_field,
-                            _fmt_float(alt_freq),
-                            str(depth),
-                            info,
-                        ]
-                    )
-                )
-
-    output_path.write_text("\n".join(lines) + "\n")

codonyat-1.3.1/aa_caller/sam.py

@@ -1,153 +0,0 @@
-from __future__ import annotations
-
-__all__ = ["SamEntry"]
-
-import re
-from collections.abc import Sequence
-
-from .models import Qual
-
-# Compiled once at module load — reused across every SamEntry instance.
-_CIGAR_RE = re.compile(r"(\d+)([MIDNSHP=X])")
-
-
-class SamEntry:
-    """Wraps a SAM record with convenience helpers used during variant aggregation."""
-
-    def __init__(self, line: str, collapsed_read_counts: bool = False) -> None:
-        """Parse a single SAM line and cache derived attributes that the pipeline needs."""
-        self.raw = line.strip()
-        self.fields = self.raw.split("\t")
-        self.identifier = self.fields[0]
-        self.flag = int(self.fields[1])
-        self.reference = self.fields[2]
-        self.coordinate = int(self.fields[3])
-        self.map_quality = int(self.fields[4])
-        self.cigar = self.fields[5]
-        self.sequence = self.fields[9]
-        self.quality_string = self.fields[10]
-        self.options = self.fields[11:]
-        self.orientation = self._determine_orientation()
-        self.collapsed_read_counts = collapsed_read_counts
-        self.occurences = self._parse_occurences()
-        self._reference_covered_length = self._compute_reference_covered_length()
-        self._ref_to_read = self._build_ref_to_read_map()
-        self._quality = Qual(self.quality_string, "sanger")
-        self.amplicon = self._parse_amplicon()
-
-    def _determine_orientation(self) -> str:
-        """Return whether the read is mapped to the forward or reverse strand."""
-        if self.flag & 16:
-            return "R"
-        return "F"
-
-    def _parse_occurences(self) -> int:
-        """Return how many observations this SAM row represents.
-
-        By default each row counts once. With ``collapsed_read_counts``, a
-        read name ending in ``_<digits>`` is treated as that many duplicates.
-        """
-        if not self.collapsed_read_counts:
-            return 1
-        parts = self.identifier.split("_")
-        tail = parts[-1]
-        if tail.isdigit():
-            return max(1, int(tail))
-        return 1
-
-    def _compute_reference_covered_length(self) -> int:
-        """Sum the CIGAR operations that consume reference bases to get coverage."""
-        ops = _CIGAR_RE.findall(self.cigar)
-        total = 0
-        for length, op in ops:
-            if op in "MDN=X":
-                total += int(length)
-        return total
-
-    def _build_ref_to_read_map(self) -> dict[int, int | None]:
-        """Walk the CIGAR string and build a mapping from reference positions to read positions.
-
-        CIGAR operations:
-        - M/=/X: consume both reference and query
-        - I: consume query only (skip in reference mapping)
-        - D/N: consume reference only (map to None = gap)
-        - S: consume query only (skip in reference mapping)
-        - H/P: consume neither
-        """
-        ref_to_read: dict[int, Optional[int]] = {}
-        ops = _CIGAR_RE.findall(self.cigar)
-        ref_pos = self.coordinate
-        read_pos = 0
-        for length_str, op in ops:
-            length = int(length_str)
-            if op in "M=X":
-                for i in range(length):
-                    ref_to_read[ref_pos + i] = read_pos + i
-                ref_pos += length
-                read_pos += length
-            elif op == "I":
-                read_pos += length
-            elif op in "DN":
-                for i in range(length):
-                    ref_to_read[ref_pos + i] = None
-                ref_pos += length
-            elif op == "S":
-                read_pos += length
-            # H and P consume neither
-        return ref_to_read
-
-    def _parse_amplicon(self) -> str:
-        """Extract the amplicon tag embedded in the read identifier, if present."""
-        match = re.search(r"(Amp_[0-9]+)", self.identifier)
-        if match:
-            return match.group(1)
-        return "Amp_NONE"
-
-    def covers(self, position: int) -> bool:
-        """Check whether this read spans the requested reference position."""
-        return self.coordinate <= position <= self.coordinate + self._reference_covered_length - 1
-
-    def _codon_ref_positions(
-        self, position: int, positions: Sequence[int] | None = None
-    ) -> tuple[int, int, int]:
-        """Resolve the three reference bases of a codon.
-
-        ``positions`` is the actual part coordinates (needed when a codon
-        crosses a multi-interval junction). Consecutive ``position..+2`` is
-        used only when the caller does not supply them.
-        """
-        if positions is not None:
-            coords = tuple(int(p) for p in positions)
-            if len(coords) != 3:
-                raise ValueError("codon positions must contain exactly three coordinates")
-            return coords[0], coords[1], coords[2]
-        return position, position + 1, position + 2
-
-    def codon_at(self, position: int, positions: Sequence[int] | None = None) -> str | None:
-        """Return the codon at the given reference coordinates using the CIGAR-aware mapping."""
-        bases = []
-        for ref_pos in self._codon_ref_positions(position, positions):
-            read_idx = self._ref_to_read.get(ref_pos)
-            if read_idx is None and ref_pos in self._ref_to_read:
-                bases.append("-")
-            elif read_idx is None:
-                return None
-            else:
-                bases.append(self.sequence[read_idx])
-        return "".join(bases)
-
-    def codon_qualities_at(
-        self, position: int, positions: Sequence[int] | None = None
-    ) -> list[float] | None:
-        """Return Phred-like qualities for the three codon bases, or None if any is missing/gapped."""
-        quals: list[float] = []
-        for ref_pos in self._codon_ref_positions(position, positions):
-            read_idx = self._ref_to_read.get(ref_pos)
-            if read_idx is None:
-                return None
-            quals.append(self._quality.return_quality_by_pos(read_idx))
-        return quals
-
-    def is_mapped(self) -> bool:
-        """True when the read is not flagged as unmapped."""
-        return not (self.flag & 4)