codonyat 1.2.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codonyat
-Version: 1.2.0
+Version: 1.3.0
 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
@@ -37,13 +37,14 @@ A Python package for codon-level amino acid variant calling from SAM alignments
 - CIGAR-aware codon extraction that correctly handles insertions, deletions, and soft clips.
 - Ratio balancing, entropy tracking, and TSV/XML exporters mirroring the legacy Perl outputs.
 - Configurable CLI flags for strand ratio bounds, entropy sensitivity, and target protein.
+- Opt-in research statistics (Wilson CI, strand-bias test, diversity indices) and AAVF v1.0. Research use only.
 
 ## Highlights
 
 - Produces consistent TSV/XML diagnostics while exposing Python objects (`SamContainer`, `FullReference`, etc.) that downstream tooling can import.
 - Validates every input file before parsing to surface malformed SAM/FASTA/amplicon data early.
 - Logs per-position entropy and strand balance for easier debugging in CI or local runs.
-- Supports any protein target via `--protein` (defaults to RT).
+- Supports any protein target via `--protein` (one name, a comma-separated list, or `all`; defaults to RT).
 
 ## Installation
 
@@ -79,10 +80,16 @@ codonyat sample.sam reference.fasta amplicons.tsv --annotation annotations.tsv -
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--annotation` | None | Optional TSV annotation file (record, protein, description, intervals, strand) |
-| `--protein` | `RT` | Target protein name (must match a FASTA header or TSV annotation) |
+| `--protein` | `RT` | Protein(s) to analyse: one name, a comma-separated list (e.g. `PR,RT,INT`, counted in a single pass) or `all` (every protein annotated in the reference header or TSV). Names must match the FASTA header annotations |
 | `--ratio-upper` | `3.162` | Upper bound for strand-ratio balancing |
 | `--ratio-lower` | `0.316` | Lower bound for strand-ratio balancing |
 | `--entropy-threshold` | `0.0` | Minimum Shannon entropy to mark a position as diverse |
+| `--min-baseq` | off | Count a codon only if all 3 bases have Phred-like quality ≥ this value |
+| `--stats` | off | Optional stats TSV (CI, strand-bias, flags, diversity) |
+| `--aavf` | off | Optional AAVF v1.0 path (no CAT/SRVL) |
+| `--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 |
 
 ### Output
 
@@ -94,6 +101,25 @@ The CLI writes two files alongside the input SAM:
   - Rows are ordered by genomic position (codon index) along the protein's intervals
   - For multi-interval proteins, this follows the biological reading order through all segments
 - `[sam-file].xml` — per-position `<Depth>`, `<FwCover>`, `<RvCover>`, `<Variants>`
+  - With several proteins, each protein's positions are wrapped in `<Protein name="…">`; single-protein XML is unchanged
+
+Default TSV/XML are byte-identical to 1.2.1 when the opt-in flags are omitted.
+
+### Research statistics (opt-in)
+
+`--stats PATH` writes a sidecar TSV with `LEVEL` = `variant`, `codon`, or `gene`:
+
+- **variant**: frequency as a fraction, Wilson 95% CI, Fisher strand-bias p, flags (`lowfreq`, `sb`, `lowcov`)
+- **codon / gene**: Shannon entropy (raw and normalised), Gini–Simpson, nucleotide π, amino-acid π
+
+`--aavf PATH` writes AAVF v1.0. FILTER is taken from the flags above. The file
+does not contain resistance or surveillance fields. Formulas and citations:
+[docs/methods.md](docs/methods.md).
+
+```bash
+codonyat-runner reads.sam reference.fasta amps.tsv \
+  --protein all --stats sample.stats.tsv --aavf sample.aavf
+```
 
 ### Reference FASTA format
 
@@ -152,7 +178,7 @@ result = call_variants(
     sam_path=Path("reads.sam"),
     reference_path=Path("reference.fasta"),
     amplicons_path=Path("amps.tsv"),
-    protein="RT",
+    protein="PR,RT,INT",  # or "all", "RT", or ["PR", "RT"]
     ratio_upper=3.2,
 )
 
@@ -181,7 +207,7 @@ call_variants_from_args(args)
 A lightweight runner at `codonyat-runner` exposes the same arguments as `call_variants_from_args`:
 
 ```bash
-codonyat-runner reads.sam reference.fasta amps.tsv --protein RT --ratio-upper 3.1 --csv-path results.tsv
+codonyat-runner reads.sam reference.fasta amps.tsv --protein PR,RT,INT --ratio-upper 3.1 --csv-path results.tsv
 ```
 
 ## Development
@@ -214,9 +240,13 @@ codonyat/
 │   ├── models.py         # Protein, Amplicon, Variant, Qual dataclasses
 │   ├── validators.py     # Input file validation
 │   ├── genetic_code.py   # Codon translation table
-│   └── constants.py      # Default thresholds
+│   ├── constants.py      # Default thresholds
+│   ├── metrics.py        # Wilson CI, Fisher, diversity indices
+│   ├── stats_writer.py   # --stats TSV
+│   └── aavf.py           # AAVF v1.0 writer
 ├── tests/                # pytest suite (unit + integration)
 ├── docs/index.html       # Project page (GitHub Pages)
+├── docs/methods.md       # Formulas and citations for 1.3.0 outputs
 └── pyproject.toml        # Package metadata
 ```
 

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

@@ -8,13 +8,14 @@ A Python package for codon-level amino acid variant calling from SAM alignments
 - CIGAR-aware codon extraction that correctly handles insertions, deletions, and soft clips.
 - Ratio balancing, entropy tracking, and TSV/XML exporters mirroring the legacy Perl outputs.
 - Configurable CLI flags for strand ratio bounds, entropy sensitivity, and target protein.
+- Opt-in research statistics (Wilson CI, strand-bias test, diversity indices) and AAVF v1.0. Research use only.
 
 ## Highlights
 
 - Produces consistent TSV/XML diagnostics while exposing Python objects (`SamContainer`, `FullReference`, etc.) that downstream tooling can import.
 - Validates every input file before parsing to surface malformed SAM/FASTA/amplicon data early.
 - Logs per-position entropy and strand balance for easier debugging in CI or local runs.
-- Supports any protein target via `--protein` (defaults to RT).
+- Supports any protein target via `--protein` (one name, a comma-separated list, or `all`; defaults to RT).
 
 ## Installation
 
@@ -50,10 +51,16 @@ codonyat sample.sam reference.fasta amplicons.tsv --annotation annotations.tsv -
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--annotation` | None | Optional TSV annotation file (record, protein, description, intervals, strand) |
-| `--protein` | `RT` | Target protein name (must match a FASTA header or TSV annotation) |
+| `--protein` | `RT` | Protein(s) to analyse: one name, a comma-separated list (e.g. `PR,RT,INT`, counted in a single pass) or `all` (every protein annotated in the reference header or TSV). Names must match the FASTA header annotations |
 | `--ratio-upper` | `3.162` | Upper bound for strand-ratio balancing |
 | `--ratio-lower` | `0.316` | Lower bound for strand-ratio balancing |
 | `--entropy-threshold` | `0.0` | Minimum Shannon entropy to mark a position as diverse |
+| `--min-baseq` | off | Count a codon only if all 3 bases have Phred-like quality ≥ this value |
+| `--stats` | off | Optional stats TSV (CI, strand-bias, flags, diversity) |
+| `--aavf` | off | Optional AAVF v1.0 path (no CAT/SRVL) |
+| `--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 |
 
 ### Output
 
@@ -65,6 +72,25 @@ The CLI writes two files alongside the input SAM:
   - Rows are ordered by genomic position (codon index) along the protein's intervals
   - For multi-interval proteins, this follows the biological reading order through all segments
 - `[sam-file].xml` — per-position `<Depth>`, `<FwCover>`, `<RvCover>`, `<Variants>`
+  - With several proteins, each protein's positions are wrapped in `<Protein name="…">`; single-protein XML is unchanged
+
+Default TSV/XML are byte-identical to 1.2.1 when the opt-in flags are omitted.
+
+### Research statistics (opt-in)
+
+`--stats PATH` writes a sidecar TSV with `LEVEL` = `variant`, `codon`, or `gene`:
+
+- **variant**: frequency as a fraction, Wilson 95% CI, Fisher strand-bias p, flags (`lowfreq`, `sb`, `lowcov`)
+- **codon / gene**: Shannon entropy (raw and normalised), Gini–Simpson, nucleotide π, amino-acid π
+
+`--aavf PATH` writes AAVF v1.0. FILTER is taken from the flags above. The file
+does not contain resistance or surveillance fields. Formulas and citations:
+[docs/methods.md](docs/methods.md).
+
+```bash
+codonyat-runner reads.sam reference.fasta amps.tsv \
+  --protein all --stats sample.stats.tsv --aavf sample.aavf
+```
 
 ### Reference FASTA format
 
@@ -123,7 +149,7 @@ result = call_variants(
     sam_path=Path("reads.sam"),
     reference_path=Path("reference.fasta"),
     amplicons_path=Path("amps.tsv"),
-    protein="RT",
+    protein="PR,RT,INT",  # or "all", "RT", or ["PR", "RT"]
     ratio_upper=3.2,
 )
 
@@ -152,7 +178,7 @@ call_variants_from_args(args)
 A lightweight runner at `codonyat-runner` exposes the same arguments as `call_variants_from_args`:
 
 ```bash
-codonyat-runner reads.sam reference.fasta amps.tsv --protein RT --ratio-upper 3.1 --csv-path results.tsv
+codonyat-runner reads.sam reference.fasta amps.tsv --protein PR,RT,INT --ratio-upper 3.1 --csv-path results.tsv
 ```
 
 ## Development
@@ -185,9 +211,13 @@ codonyat/
 │   ├── models.py         # Protein, Amplicon, Variant, Qual dataclasses
 │   ├── validators.py     # Input file validation
 │   ├── genetic_code.py   # Codon translation table
-│   └── constants.py      # Default thresholds
+│   ├── constants.py      # Default thresholds
+│   ├── metrics.py        # Wilson CI, Fisher, diversity indices
+│   ├── stats_writer.py   # --stats TSV
+│   └── aavf.py           # AAVF v1.0 writer
 ├── tests/                # pytest suite (unit + integration)
 ├── docs/index.html       # Project page (GitHub Pages)
+├── docs/methods.md       # Formulas and citations for 1.3.0 outputs
 └── pyproject.toml        # Package metadata
 ```
 

{codonyat-1.2.0 → codonyat-1.3.0}/aa_caller/__init__.py

@@ -1,6 +1,7 @@
 """Light wrapper to expose the RT variant caller as a package."""
 
 from .cli import main
+from .constants import PACKAGE_VERSION
 from .container import SamContainer
 from .reference import FullReference
 from .runner import (
@@ -23,3 +24,5 @@ __all__ = [
     "SamEntry",
     "parse_amplicons",
 ]
+
+__version__ = PACKAGE_VERSION

codonyat-1.3.0/aa_caller/aavf.py

@@ -0,0 +1,163 @@
+"""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"))
+            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.2.0 → codonyat-1.3.0}/aa_caller/app.py

@@ -6,14 +6,23 @@ Existing code that does ``from aa_caller.app import X`` continues to work.
 from .cli import main  # noqa: F401
 from .constants import (  # noqa: F401
     DEFAULT_ENTROPY_THRESHOLD,
+    DEFAULT_MIN_COVERAGE,
+    DEFAULT_MIN_FREQ,
     DEFAULT_PROTEIN,
     DEFAULT_RATIO_LOWER,
     DEFAULT_RATIO_UPPER,
+    DEFAULT_SB_ALPHA,
+    PACKAGE_VERSION,
 )
 from .container import SamContainer  # noqa: F401
 from .genetic_code import GENETIC_CODE, codon_to_aminoacid  # noqa: F401
 from .models import Amplicon, Protein, Qual, Variant  # noqa: F401
-from .reference import FullReference  # noqa: F401
+from .reference import (  # noqa: F401
+    FullReference,
+    parse_protein_spec,
+    resolve_protein_targets,
+    resolve_proteins,
+)
 from .sam import SamEntry  # noqa: F401
 from .validators import (  # noqa: F401
     parse_amplicons,

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

@@ -4,6 +4,7 @@ import argparse
 import logging
 from pathlib import Path
 
+from .cli_options import add_research_output_args
 from .constants import (
     DEFAULT_ENTROPY_THRESHOLD,
     DEFAULT_PROTEIN,
@@ -11,7 +12,7 @@ from .constants import (
     DEFAULT_RATIO_UPPER,
 )
 from .container import SamContainer
-from .reference import FullReference
+from .reference import FullReference, parse_protein_spec, resolve_protein_targets
 from .validators import (
     parse_amplicons,
     validate_amplicon_file,
@@ -58,8 +59,13 @@ def main() -> None:
         "--protein",
         type=str,
         default=DEFAULT_PROTEIN,
-        help="Target protein name to analyze (default: RT).",
+        help=(
+            "Protein(s) to analyze: one name (default: RT), a comma-separated list "
+            "(e.g. PR,RT,INT; all counted in one pass over the SAM) or 'all' for "
+            "every protein annotated in the reference header."
+        ),
     )
+    add_research_output_args(parser)
     args = parser.parse_args()
 
     if not args.sam_file.exists():
@@ -73,7 +79,13 @@ def main() -> None:
 
     logger.info("Validating input formats before parsing")
     validate_sam_file(args.sam_file)
-    validate_reference_file(args.reference_file, protein_name=args.protein, annotation_path=args.annotation)
+    try:
+        parse_protein_spec(args.protein)
+    except ValueError as exc:
+        parser.error(str(exc))
+    validate_reference_file(
+        args.reference_file, protein_name=args.protein, annotation_path=args.annotation
+    )
     validate_amplicon_file(args.amplicons_file)
 
     logger.info("Reading amplicon configuration")
@@ -81,6 +93,11 @@ def main() -> None:
 
     logger.info("Loading reference")
     reference = FullReference(args.reference_file, annotation_path=args.annotation)
+    try:
+        proteins = resolve_protein_targets(args.protein, reference)
+    except ValueError as exc:
+        parser.error(str(exc))
+    protein_names = [protein.name for protein in proteins]
 
     logger.info("Parsing SAM entries")
     container = SamContainer(
@@ -88,15 +105,44 @@ def main() -> None:
         ratio_upper=args.ratio_upper,
         ratio_lower=args.ratio_lower,
         entropy_threshold=args.entropy_threshold,
+        min_baseq=args.min_baseq,
     )
     container.load()
 
-    logger.info("Calculating %s variant frequencies", args.protein)
-    container.calculate_variant_frequencies(args.protein, reference)
+    logger.info("Calculating %s variant frequencies", ",".join(protein_names))
+    container.calculate_for_proteins(proteins, reference)
 
     csv_path = args.sam_file.with_suffix(args.sam_file.suffix + ".tsv")
     xml_path = args.sam_file.with_suffix(args.sam_file.suffix + ".xml")
     logger.info("Writing TSV results")
-    container.write_csv(str(args.sam_file), reference, csv_path, protein_name=args.protein)
-    logger.info("Writing XML dump")
-    container.write_xml(str(args.sam_file), reference, xml_path)
+    if len(proteins) == 1:
+        container.write_csv(str(args.sam_file), reference, csv_path, protein_name=protein_names[0])
+        logger.info("Writing XML dump")
+        container.write_xml(str(args.sam_file), reference, xml_path)
+    else:
+        container.write_csv_proteins(str(args.sam_file), reference, csv_path, protein_names)
+        logger.info("Writing XML dump")
+        container.write_xml_proteins(str(args.sam_file), reference, xml_path, protein_names)
+
+    if args.stats:
+        logger.info("Writing stats TSV")
+        container.write_stats(
+            str(args.sam_file),
+            reference,
+            args.stats,
+            protein_names,
+            min_freq=args.min_freq,
+            min_coverage=args.min_coverage,
+            sb_alpha=args.sb_alpha,
+        )
+    if args.aavf:
+        logger.info("Writing AAVF")
+        container.write_aavf(
+            str(args.sam_file),
+            reference,
+            args.aavf,
+            protein_names,
+            min_freq=args.min_freq,
+            min_coverage=args.min_coverage,
+            sb_alpha=args.sb_alpha,
+        )

codonyat-1.3.0/aa_caller/cli_options.py

@@ -0,0 +1,52 @@
+"""Shared opt-in CLI flags for research statistics and AAVF."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from pathlib import Path
+
+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."""
+    parser.add_argument(
+        "--min-baseq",
+        type=float,
+        default=None,
+        help=(
+            "If set, count a codon only when all three bases have Phred-like "
+            "quality ≥ this value (e.g. 20). Off by default so TSV/XML stay "
+            "byte-identical to 1.2.1."
+        ),
+    )
+    parser.add_argument(
+        "--stats",
+        type=Path,
+        default=None,
+        help="Optional stats TSV (Wilson 95%% CI, strand-bias p, flags, diversity).",
+    )
+    parser.add_argument(
+        "--aavf",
+        type=Path,
+        default=None,
+        help="Optional AAVF v1.0 path. Research use only; CAT/SRVL are omitted.",
+    )
+    parser.add_argument(
+        "--min-freq",
+        type=float,
+        default=DEFAULT_MIN_FREQ,
+        help="Frequency floor (fraction 0–1) for the lowfreq flag / AAVF FILTER (default: 0.01).",
+    )
+    parser.add_argument(
+        "--min-coverage",
+        type=int,
+        default=DEFAULT_MIN_COVERAGE,
+        help="Coverage floor for the lowcov flag / AAVF FILTER (default: 10).",
+    )
+    parser.add_argument(
+        "--sb-alpha",
+        type=float,
+        default=DEFAULT_SB_ALPHA,
+        help="Fisher exact p-value cutoff for the sb (strand-bias) flag (default: 0.05).",
+    )

codonyat-1.3.0/aa_caller/constants.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+DEFAULT_RATIO_UPPER = 3.16227766
+DEFAULT_RATIO_LOWER = 0.316227766
+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"
+WILSON_Z_95 = 1.959963984540054  # Φ^{-1}(0.975)
+DEFAULT_MIN_FREQ = 0.01
+DEFAULT_MIN_COVERAGE = 10
+DEFAULT_SB_ALPHA = 0.05