codonyat 1.3.0__tar.gz → 1.3.2__tar.gz

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

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: codonyat
-Version: 1.3.0
+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
 Project-URL: Source, https://github.com/mnoguera/codonyat
 Project-URL: Documentation, https://mnoguera.github.io/codonyat/
 Project-URL: Issues, https://github.com/mnoguera/codonyat/issues
-Project-URL: Nextflow pipeline (nf-codonyat), https://github.com/sjoclaudi/nf-codonyat
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -54,13 +53,6 @@ pip install codonyat
 
 Requires Python 3.10 or newer. The only runtime dependency is Biopython.
 
-## Running it in a workflow
-
-This repository contains only the Python package. To run codonyat on many samples
-(from FASTQ or SAM, with read QC, trimming, alignment and a merged report), use the
-separate Nextflow pipeline **[nf-codonyat](https://github.com/sjoclaudi/nf-codonyat)**,
-which installs this package from PyPI.
-
 ## CLI usage
 
 Once installed, the `codonyat` entry point is available:
@@ -90,6 +82,7 @@ codonyat sample.sam reference.fasta amplicons.tsv --annotation annotations.tsv -
 | `--min-freq` | `0.01` | Frequency floor (fraction) for `lowfreq` / AAVF FILTER |
 | `--min-coverage` | `10` | Coverage floor for `lowcov` / AAVF FILTER |
 | `--sb-alpha` | `0.05` | Fisher p-value cutoff for the `sb` flag |
+| `--collapsed-read-counts` | off | Treat a read name ending in `_<digits>` as a collapsed duplicate count. Off by default: each SAM row counts once |
 
 ### Output
 

{codonyat-1.3.0 → codonyat-1.3.2}/README.md

@@ -25,13 +25,6 @@ pip install codonyat
 
 Requires Python 3.10 or newer. The only runtime dependency is Biopython.
 
-## Running it in a workflow
-
-This repository contains only the Python package. To run codonyat on many samples
-(from FASTQ or SAM, with read QC, trimming, alignment and a merged report), use the
-separate Nextflow pipeline **[nf-codonyat](https://github.com/sjoclaudi/nf-codonyat)**,
-which installs this package from PyPI.
-
 ## CLI usage
 
 Once installed, the `codonyat` entry point is available:
@@ -61,6 +54,7 @@ codonyat sample.sam reference.fasta amplicons.tsv --annotation annotations.tsv -
 | `--min-freq` | `0.01` | Frequency floor (fraction) for `lowfreq` / AAVF FILTER |
 | `--min-coverage` | `10` | Coverage floor for `lowcov` / AAVF FILTER |
 | `--sb-alpha` | `0.05` | Fisher p-value cutoff for the `sb` flag |
+| `--collapsed-read-counts` | off | Treat a read name ending in `_<digits>` as a collapsed duplicate count. Off by default: each SAM row counts once |
 
 ### Output
 

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.0 → codonyat-1.3.2}/aa_caller/app.py

@@ -20,6 +20,7 @@ from .models import Amplicon, Protein, Qual, Variant  # noqa: F401
 from .reference import (  # noqa: F401
     FullReference,
     parse_protein_spec,
+    proteins_from_fasta_record,
     resolve_protein_targets,
     resolve_proteins,
 )

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

@@ -106,9 +106,8 @@ def main() -> None:
         ratio_lower=args.ratio_lower,
         entropy_threshold=args.entropy_threshold,
         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.0 → codonyat-1.3.2}/aa_caller/cli_options.py

@@ -9,7 +9,7 @@ from .constants import DEFAULT_MIN_COVERAGE, DEFAULT_MIN_FREQ, DEFAULT_SB_ALPHA
 
 
 def add_research_output_args(parser: ArgumentParser) -> None:
-    """Attach opt-in 1.3.0 flags. Defaults leave TSV/XML unchanged."""
+    """Attach opt-in 1.3.x flags. Defaults leave TSV/XML unchanged."""
     parser.add_argument(
         "--min-baseq",
         type=float,
@@ -50,3 +50,12 @@ def add_research_output_args(parser: ArgumentParser) -> None:
         default=DEFAULT_SB_ALPHA,
         help="Fisher exact p-value cutoff for the sb (strand-bias) flag (default: 0.05).",
     )
+    parser.add_argument(
+        "--collapsed-read-counts",
+        action="store_true",
+        default=False,
+        help=(
+            "If set, treat a read name ending in _<digits> as a collapsed duplicate "
+            "count (that many observations). Off by default: each SAM row counts once."
+        ),
+    )

{codonyat-1.3.0 → 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.0"
+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.0 → 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."""
 
@@ -25,10 +85,14 @@ class SamContainer:
         ratio_lower: float,
         entropy_threshold: float,
         min_baseq: float | None = None,
+        collapsed_read_counts: bool = False,
     ) -> 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]]] = []
@@ -36,16 +100,16 @@ class SamContainer:
         self.ratio_lower = ratio_lower
         self.entropy_threshold = entropy_threshold
         self.min_baseq = min_baseq
+        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)
-                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
@@ -81,19 +145,28 @@ 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
-            for pos, record_id in self._get_codon_positions(protein, reference):
+            for pos, record_id, codon_coords in self._get_codon_positions(protein, reference):
                 aa_pos += 1
                 entries[pos] = {
                     "variants": {},
@@ -103,19 +176,46 @@ class SamContainer:
                     "amplicons": {},
                     "record_id": record_id,
                     "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)
@@ -128,13 +228,16 @@ class SamContainer:
 
     def _accumulate_read_at_position(self, read: SamEntry, pos: int, entry: dict) -> None:
         """Add one mapped read's codon to a protein position, if it covers it."""
-        if not read.covers(pos):
-            return
-        codon = read.codon_at(pos)
+        codon_coords = entry.get("codon_coords")
+        if codon_coords is None:
+            codon_coords = (pos, pos + 1, pos + 2)
+        # ``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
         if self.min_baseq is not None:
-            quals = read.codon_qualities_at(pos)
+            quals = read.codon_qualities_at(pos, positions=codon_coords)
             if quals is None or any(qual < self.min_baseq for qual in quals):
                 return
         depth_increment = read.occurences
@@ -166,27 +269,22 @@ class SamContainer:
         amp_position["depth"] += depth_increment
 
     def _get_codon_positions(self, protein, reference: FullReference) -> list[tuple]:
-        """Generate list of (position, record_id) tuples for all codons in the protein.
+        """Generate (start, record_id, codon_coords) for every codon in the protein.
 
-        Handles multi-interval proteins including frameshifts.
+        Coding bases are concatenated in interval order so the reading frame is
+        carried across parts. A codon that sits on a junction keeps the actual
+        part coordinates (for example positions 10, 11, 12 of 1-10;11-30).
+        Incomplete trailing bases at the end of the protein are dropped.
         """
-        positions = []
-        current_offset = 0
-
+        positions: list[tuple] = []
+        pending: list[int] = []
         for interval in protein.intervals:
-            interval_length = interval.end - interval.start + 1
-            pos = interval.start
-
-            while pos <= interval.end:
-                remaining_in_interval = interval.end - pos + 1
-                if remaining_in_interval >= 3:
-                    positions.append((pos, protein.record_id))
-                    pos += 3
-                else:
-                    break
-
-            current_offset += interval_length
-
+            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,