codonyat 1.2.1__tar.gz → 1.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. {codonyat-1.2.1/codonyat.egg-info → codonyat-1.3.0}/PKG-INFO +31 -2
  2. {codonyat-1.2.1 → codonyat-1.3.0}/README.md +30 -1
  3. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/__init__.py +3 -0
  4. codonyat-1.3.0/aa_caller/aavf.py +163 -0
  5. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/app.py +4 -0
  6. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/cli.py +26 -0
  7. codonyat-1.3.0/aa_caller/cli_options.py +52 -0
  8. codonyat-1.3.0/aa_caller/constants.py +13 -0
  9. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/container.py +59 -0
  10. codonyat-1.3.0/aa_caller/metrics.py +198 -0
  11. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/runner.py +51 -0
  12. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/sam.py +11 -0
  13. codonyat-1.3.0/aa_caller/stats_writer.py +192 -0
  14. {codonyat-1.2.1 → codonyat-1.3.0/codonyat.egg-info}/PKG-INFO +31 -2
  15. {codonyat-1.2.1 → codonyat-1.3.0}/codonyat.egg-info/SOURCES.txt +7 -1
  16. {codonyat-1.2.1 → codonyat-1.3.0}/pyproject.toml +1 -1
  17. codonyat-1.3.0/tests/test_metrics.py +154 -0
  18. codonyat-1.3.0/tests/test_v1_3_0_features.py +290 -0
  19. codonyat-1.2.1/aa_caller/constants.py +0 -6
  20. {codonyat-1.2.1 → codonyat-1.3.0}/LICENSE +0 -0
  21. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/__main__.py +0 -0
  22. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/genetic_code.py +0 -0
  23. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/models.py +0 -0
  24. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/reference.py +0 -0
  25. {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/validators.py +0 -0
  26. {codonyat-1.2.1 → codonyat-1.3.0}/codonyat.egg-info/dependency_links.txt +0 -0
  27. {codonyat-1.2.1 → codonyat-1.3.0}/codonyat.egg-info/entry_points.txt +0 -0
  28. {codonyat-1.2.1 → codonyat-1.3.0}/codonyat.egg-info/requires.txt +0 -0
  29. {codonyat-1.2.1 → codonyat-1.3.0}/codonyat.egg-info/top_level.txt +0 -0
  30. {codonyat-1.2.1 → codonyat-1.3.0}/setup.cfg +0 -0
  31. {codonyat-1.2.1 → codonyat-1.3.0}/tests/test_app.py +0 -0
  32. {codonyat-1.2.1 → codonyat-1.3.0}/tests/test_integration.py +0 -0
  33. {codonyat-1.2.1 → codonyat-1.3.0}/tests/test_protein_selection.py +0 -0
  34. {codonyat-1.2.1 → codonyat-1.3.0}/tests/test_v1_2_0_features.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: codonyat
3
- Version: 1.2.1
3
+ Version: 1.3.0
4
4
  Summary: codon-yat — A codon-aware (Yet Another) amino acid variant typer from SAM alignments of viral NGS data.
5
5
  Author-email: Marc Noguera Julian <info@treetopunder.com>
6
6
  License-Expression: MIT
@@ -37,6 +37,7 @@ A Python package for codon-level amino acid variant calling from SAM alignments
37
37
  - CIGAR-aware codon extraction that correctly handles insertions, deletions, and soft clips.
38
38
  - Ratio balancing, entropy tracking, and TSV/XML exporters mirroring the legacy Perl outputs.
39
39
  - Configurable CLI flags for strand ratio bounds, entropy sensitivity, and target protein.
40
+ - Opt-in research statistics (Wilson CI, strand-bias test, diversity indices) and AAVF v1.0. Research use only.
40
41
 
41
42
  ## Highlights
42
43
 
@@ -83,6 +84,12 @@ codonyat sample.sam reference.fasta amplicons.tsv --annotation annotations.tsv -
83
84
  | `--ratio-upper` | `3.162` | Upper bound for strand-ratio balancing |
84
85
  | `--ratio-lower` | `0.316` | Lower bound for strand-ratio balancing |
85
86
  | `--entropy-threshold` | `0.0` | Minimum Shannon entropy to mark a position as diverse |
87
+ | `--min-baseq` | off | Count a codon only if all 3 bases have Phred-like quality ≥ this value |
88
+ | `--stats` | off | Optional stats TSV (CI, strand-bias, flags, diversity) |
89
+ | `--aavf` | off | Optional AAVF v1.0 path (no CAT/SRVL) |
90
+ | `--min-freq` | `0.01` | Frequency floor (fraction) for `lowfreq` / AAVF FILTER |
91
+ | `--min-coverage` | `10` | Coverage floor for `lowcov` / AAVF FILTER |
92
+ | `--sb-alpha` | `0.05` | Fisher p-value cutoff for the `sb` flag |
86
93
 
87
94
  ### Output
88
95
 
@@ -96,6 +103,24 @@ The CLI writes two files alongside the input SAM:
96
103
  - `[sam-file].xml` — per-position `<Depth>`, `<FwCover>`, `<RvCover>`, `<Variants>`
97
104
  - With several proteins, each protein's positions are wrapped in `<Protein name="…">`; single-protein XML is unchanged
98
105
 
106
+ Default TSV/XML are byte-identical to 1.2.1 when the opt-in flags are omitted.
107
+
108
+ ### Research statistics (opt-in)
109
+
110
+ `--stats PATH` writes a sidecar TSV with `LEVEL` = `variant`, `codon`, or `gene`:
111
+
112
+ - **variant**: frequency as a fraction, Wilson 95% CI, Fisher strand-bias p, flags (`lowfreq`, `sb`, `lowcov`)
113
+ - **codon / gene**: Shannon entropy (raw and normalised), Gini–Simpson, nucleotide π, amino-acid π
114
+
115
+ `--aavf PATH` writes AAVF v1.0. FILTER is taken from the flags above. The file
116
+ does not contain resistance or surveillance fields. Formulas and citations:
117
+ [docs/methods.md](docs/methods.md).
118
+
119
+ ```bash
120
+ codonyat-runner reads.sam reference.fasta amps.tsv \
121
+ --protein all --stats sample.stats.tsv --aavf sample.aavf
122
+ ```
123
+
99
124
  ### Reference FASTA format
100
125
 
101
126
  The reference FASTA supports both single-record and multi-record files. Protein annotations can be provided either in the FASTA header or via a separate TSV file.
@@ -215,9 +240,13 @@ codonyat/
215
240
  │ ├── models.py # Protein, Amplicon, Variant, Qual dataclasses
216
241
  │ ├── validators.py # Input file validation
217
242
  │ ├── genetic_code.py # Codon translation table
218
- │ └── constants.py # Default thresholds
243
+ │ ├── constants.py # Default thresholds
244
+ │ ├── metrics.py # Wilson CI, Fisher, diversity indices
245
+ │ ├── stats_writer.py # --stats TSV
246
+ │ └── aavf.py # AAVF v1.0 writer
219
247
  ├── tests/ # pytest suite (unit + integration)
220
248
  ├── docs/index.html # Project page (GitHub Pages)
249
+ ├── docs/methods.md # Formulas and citations for 1.3.0 outputs
221
250
  └── pyproject.toml # Package metadata
222
251
  ```
223
252
 
@@ -8,6 +8,7 @@ A Python package for codon-level amino acid variant calling from SAM alignments
8
8
  - CIGAR-aware codon extraction that correctly handles insertions, deletions, and soft clips.
9
9
  - Ratio balancing, entropy tracking, and TSV/XML exporters mirroring the legacy Perl outputs.
10
10
  - Configurable CLI flags for strand ratio bounds, entropy sensitivity, and target protein.
11
+ - Opt-in research statistics (Wilson CI, strand-bias test, diversity indices) and AAVF v1.0. Research use only.
11
12
 
12
13
  ## Highlights
13
14
 
@@ -54,6 +55,12 @@ codonyat sample.sam reference.fasta amplicons.tsv --annotation annotations.tsv -
54
55
  | `--ratio-upper` | `3.162` | Upper bound for strand-ratio balancing |
55
56
  | `--ratio-lower` | `0.316` | Lower bound for strand-ratio balancing |
56
57
  | `--entropy-threshold` | `0.0` | Minimum Shannon entropy to mark a position as diverse |
58
+ | `--min-baseq` | off | Count a codon only if all 3 bases have Phred-like quality ≥ this value |
59
+ | `--stats` | off | Optional stats TSV (CI, strand-bias, flags, diversity) |
60
+ | `--aavf` | off | Optional AAVF v1.0 path (no CAT/SRVL) |
61
+ | `--min-freq` | `0.01` | Frequency floor (fraction) for `lowfreq` / AAVF FILTER |
62
+ | `--min-coverage` | `10` | Coverage floor for `lowcov` / AAVF FILTER |
63
+ | `--sb-alpha` | `0.05` | Fisher p-value cutoff for the `sb` flag |
57
64
 
58
65
  ### Output
59
66
 
@@ -67,6 +74,24 @@ The CLI writes two files alongside the input SAM:
67
74
  - `[sam-file].xml` — per-position `<Depth>`, `<FwCover>`, `<RvCover>`, `<Variants>`
68
75
  - With several proteins, each protein's positions are wrapped in `<Protein name="…">`; single-protein XML is unchanged
69
76
 
77
+ Default TSV/XML are byte-identical to 1.2.1 when the opt-in flags are omitted.
78
+
79
+ ### Research statistics (opt-in)
80
+
81
+ `--stats PATH` writes a sidecar TSV with `LEVEL` = `variant`, `codon`, or `gene`:
82
+
83
+ - **variant**: frequency as a fraction, Wilson 95% CI, Fisher strand-bias p, flags (`lowfreq`, `sb`, `lowcov`)
84
+ - **codon / gene**: Shannon entropy (raw and normalised), Gini–Simpson, nucleotide π, amino-acid π
85
+
86
+ `--aavf PATH` writes AAVF v1.0. FILTER is taken from the flags above. The file
87
+ does not contain resistance or surveillance fields. Formulas and citations:
88
+ [docs/methods.md](docs/methods.md).
89
+
90
+ ```bash
91
+ codonyat-runner reads.sam reference.fasta amps.tsv \
92
+ --protein all --stats sample.stats.tsv --aavf sample.aavf
93
+ ```
94
+
70
95
  ### Reference FASTA format
71
96
 
72
97
  The reference FASTA supports both single-record and multi-record files. Protein annotations can be provided either in the FASTA header or via a separate TSV file.
@@ -186,9 +211,13 @@ codonyat/
186
211
  │ ├── models.py # Protein, Amplicon, Variant, Qual dataclasses
187
212
  │ ├── validators.py # Input file validation
188
213
  │ ├── genetic_code.py # Codon translation table
189
- │ └── constants.py # Default thresholds
214
+ │ ├── constants.py # Default thresholds
215
+ │ ├── metrics.py # Wilson CI, Fisher, diversity indices
216
+ │ ├── stats_writer.py # --stats TSV
217
+ │ └── aavf.py # AAVF v1.0 writer
190
218
  ├── tests/ # pytest suite (unit + integration)
191
219
  ├── docs/index.html # Project page (GitHub Pages)
220
+ ├── docs/methods.md # Formulas and citations for 1.3.0 outputs
192
221
  └── pyproject.toml # Package metadata
193
222
  ```
194
223
 
@@ -1,6 +1,7 @@
1
1
  """Light wrapper to expose the RT variant caller as a package."""
2
2
 
3
3
  from .cli import main
4
+ from .constants import PACKAGE_VERSION
4
5
  from .container import SamContainer
5
6
  from .reference import FullReference
6
7
  from .runner import (
@@ -23,3 +24,5 @@ __all__ = [
23
24
  "SamEntry",
24
25
  "parse_amplicons",
25
26
  ]
27
+
28
+ __version__ = PACKAGE_VERSION
@@ -0,0 +1,163 @@
1
+ """AAVF v1.0 writer. Research use only. Never emits CAT or SRVL."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections import defaultdict
6
+ from collections.abc import Sequence
7
+ from datetime import date
8
+ from pathlib import Path
9
+
10
+ from .constants import PACKAGE_VERSION
11
+ from .genetic_code import codon_to_aminoacid
12
+ from .metrics import classify_flags, is_acgt_codon
13
+ from .models import Variant
14
+ from .reference import FullReference
15
+
16
+ _AAVF_AA = frozenset("ACDEFGHIKLMNPQRSTVWYX*")
17
+
18
+
19
+ def aavf_amino_acid(codon: str) -> str:
20
+ """Map a codon to an AAVF amino-acid letter (``*`` = stop, ``X`` = other)."""
21
+ aa = codon_to_aminoacid(codon)
22
+ if aa == "_":
23
+ return "*"
24
+ if aa in _AAVF_AA:
25
+ return aa
26
+ return "X"
27
+
28
+
29
+ def mark_changed_bases(ref_codon: str, alt_codon: str) -> str:
30
+ """Lowercase matches to the reference codon; uppercase substitutions.
31
+
32
+ Matches the AAVF v1.0 examples (``RC=aaa;AC=aaC``).
33
+ """
34
+ ref = ref_codon.lower()
35
+ alt = alt_codon.lower()
36
+ marked = []
37
+ for i, base in enumerate(alt):
38
+ if i < len(ref) and base == ref[i]:
39
+ marked.append(base)
40
+ else:
41
+ marked.append(base.upper())
42
+ return "".join(marked)
43
+
44
+
45
+ def _fmt_float(value: float) -> str:
46
+ return f"{value:.6g}"
47
+
48
+
49
+ def write_aavf(
50
+ sample_name: str,
51
+ reference: FullReference,
52
+ output_path: Path,
53
+ protein_pairs: Sequence[tuple[str, dict[int, dict]]],
54
+ *,
55
+ min_freq: float,
56
+ min_coverage: int,
57
+ sb_alpha: float,
58
+ file_date: str | None = None,
59
+ ) -> None:
60
+ """Write an AAVF v1.0 file for the counted proteins.
61
+
62
+ FILTER codes are the item-1 flags ``lowfreq``, ``sb`` and ``lowcov``.
63
+ CAT and SRVL are never written. Partial / gapped codons map to ``X``.
64
+ True amino-acid indels are not called.
65
+ """
66
+ dated = file_date or date.today().strftime("%Y%m%d")
67
+ fasta_name = Path(reference.path).name
68
+ contig_lines = [
69
+ f"##contig=<ID={record_id.replace(':', '|')},length={len(reference.sequences[record_id])}>"
70
+ for record_id in reference.record_ids
71
+ ]
72
+ lines = [
73
+ "##fileformat=AAVFv1.0",
74
+ f"##fileDate={dated}",
75
+ f"##source=codonyat-{PACKAGE_VERSION} (research use only)",
76
+ f"##reference={fasta_name}",
77
+ *contig_lines,
78
+ '##INFO=<ID=RC,Number=1,Type=String,Description="Reference codon">',
79
+ '##INFO=<ID=AC,Number=.,Type=String,Description="Alternate codon(s) encoding ALT">',
80
+ '##INFO=<ID=ACC,Number=.,Type=Integer,Description="Alternate codon counts, same order as AC">',
81
+ '##INFO=<ID=ACF,Number=.,Type=Float,Description="Alternate codon frequencies, same order as AC">',
82
+ '##INFO=<ID=FWC,Number=1,Type=Integer,Description="Forward-strand coverage at the codon">',
83
+ '##INFO=<ID=RVC,Number=1,Type=Integer,Description="Reverse-strand coverage at the codon">',
84
+ '##INFO=<ID=SR,Number=1,Type=Float,Description="Forward/reverse coverage ratio at the codon">',
85
+ '##FILTER=<ID=lowfreq,Description="ALT frequency below --min-freq">',
86
+ '##FILTER=<ID=sb,Description="Strand-bias Fisher p-value below --sb-alpha">',
87
+ '##FILTER=<ID=lowcov,Description="Codon coverage below --min-coverage">',
88
+ "#CHROM\tGENE\tPOS\tREF\tALT\tFILTER\tALT_FREQ\tCOVERAGE\tINFO",
89
+ ]
90
+
91
+ for protein_name, entries in protein_pairs:
92
+ # aa_pos then genomic position; keeps GENE blocks contiguous.
93
+ ordered = sorted(
94
+ entries.items(),
95
+ key=lambda item: (item[1].get("aa_pos", item[0]), item[0]),
96
+ )
97
+ for pos, entry in ordered:
98
+ depth = int(entry["depth"])
99
+ if depth <= 0:
100
+ continue
101
+ record_id = str(entry.get("record_id", reference.id)).replace(":", "|")
102
+ gene = protein_name.replace(":", "|")
103
+ aa_pos = int(entry.get("aa_pos", 0)) or "."
104
+ ref_codon = reference.get_seq_at(pos, 3, entry.get("record_id"))
105
+ ref_aa = aavf_amino_acid(ref_codon) if ref_codon else "X"
106
+ fw_depth = int(entry["fw_depth"])
107
+ rv_depth = int(entry["rv_depth"])
108
+ sr = (fw_depth / rv_depth) if rv_depth else 0.0
109
+
110
+ by_aa: dict[str, list[Variant]] = defaultdict(list)
111
+ for variant in entry["variants"].values():
112
+ by_aa[aavf_amino_acid(variant.codon)].append(variant)
113
+
114
+ for alt_aa, variants in by_aa.items():
115
+ alt_count = sum(v.count for v in variants)
116
+ alt_fw = sum(v.fw_reads for v in variants)
117
+ alt_rv = sum(v.rv_reads for v in variants)
118
+ alt_freq = (alt_count / depth) if depth else 0.0
119
+ flags, _p = classify_flags(
120
+ freq=alt_freq,
121
+ coverage=depth,
122
+ fw=alt_fw,
123
+ rv=alt_rv,
124
+ other_fw=fw_depth - alt_fw,
125
+ other_rv=rv_depth - alt_rv,
126
+ min_freq=min_freq,
127
+ min_coverage=min_coverage,
128
+ sb_alpha=sb_alpha,
129
+ )
130
+ filter_field = ";".join(flags) if flags else "PASS"
131
+ ac_parts = []
132
+ acc_parts = []
133
+ acf_parts = []
134
+ for variant in variants:
135
+ codon = variant.codon
136
+ labelled = mark_changed_bases(ref_codon, codon) if is_acgt_codon(codon) else codon.lower()
137
+ ac_parts.append(labelled)
138
+ acc_parts.append(str(int(variant.count)))
139
+ acf_parts.append(_fmt_float(variant.count / depth if depth else 0.0))
140
+ info = (
141
+ f"RC={ref_codon.lower()};"
142
+ f"AC={','.join(ac_parts)};"
143
+ f"ACC={','.join(acc_parts)};"
144
+ f"ACF={','.join(acf_parts)};"
145
+ f"FWC={fw_depth};RVC={rv_depth};SR={_fmt_float(sr)}"
146
+ )
147
+ lines.append(
148
+ "\t".join(
149
+ [
150
+ record_id,
151
+ gene,
152
+ str(aa_pos),
153
+ ref_aa,
154
+ alt_aa,
155
+ filter_field,
156
+ _fmt_float(alt_freq),
157
+ str(depth),
158
+ info,
159
+ ]
160
+ )
161
+ )
162
+
163
+ output_path.write_text("\n".join(lines) + "\n")
@@ -6,9 +6,13 @@ Existing code that does ``from aa_caller.app import X`` continues to work.
6
6
  from .cli import main # noqa: F401
7
7
  from .constants import ( # noqa: F401
8
8
  DEFAULT_ENTROPY_THRESHOLD,
9
+ DEFAULT_MIN_COVERAGE,
10
+ DEFAULT_MIN_FREQ,
9
11
  DEFAULT_PROTEIN,
10
12
  DEFAULT_RATIO_LOWER,
11
13
  DEFAULT_RATIO_UPPER,
14
+ DEFAULT_SB_ALPHA,
15
+ PACKAGE_VERSION,
12
16
  )
13
17
  from .container import SamContainer # noqa: F401
14
18
  from .genetic_code import GENETIC_CODE, codon_to_aminoacid # noqa: F401
@@ -4,6 +4,7 @@ import argparse
4
4
  import logging
5
5
  from pathlib import Path
6
6
 
7
+ from .cli_options import add_research_output_args
7
8
  from .constants import (
8
9
  DEFAULT_ENTROPY_THRESHOLD,
9
10
  DEFAULT_PROTEIN,
@@ -64,6 +65,7 @@ def main() -> None:
64
65
  "every protein annotated in the reference header."
65
66
  ),
66
67
  )
68
+ add_research_output_args(parser)
67
69
  args = parser.parse_args()
68
70
 
69
71
  if not args.sam_file.exists():
@@ -103,6 +105,7 @@ def main() -> None:
103
105
  ratio_upper=args.ratio_upper,
104
106
  ratio_lower=args.ratio_lower,
105
107
  entropy_threshold=args.entropy_threshold,
108
+ min_baseq=args.min_baseq,
106
109
  )
107
110
  container.load()
108
111
 
@@ -120,3 +123,26 @@ def main() -> None:
120
123
  container.write_csv_proteins(str(args.sam_file), reference, csv_path, protein_names)
121
124
  logger.info("Writing XML dump")
122
125
  container.write_xml_proteins(str(args.sam_file), reference, xml_path, protein_names)
126
+
127
+ if args.stats:
128
+ logger.info("Writing stats TSV")
129
+ container.write_stats(
130
+ str(args.sam_file),
131
+ reference,
132
+ args.stats,
133
+ protein_names,
134
+ min_freq=args.min_freq,
135
+ min_coverage=args.min_coverage,
136
+ sb_alpha=args.sb_alpha,
137
+ )
138
+ if args.aavf:
139
+ logger.info("Writing AAVF")
140
+ container.write_aavf(
141
+ str(args.sam_file),
142
+ reference,
143
+ args.aavf,
144
+ protein_names,
145
+ min_freq=args.min_freq,
146
+ min_coverage=args.min_coverage,
147
+ sb_alpha=args.sb_alpha,
148
+ )
@@ -0,0 +1,52 @@
1
+ """Shared opt-in CLI flags for research statistics and AAVF."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from argparse import ArgumentParser
6
+ from pathlib import Path
7
+
8
+ from .constants import DEFAULT_MIN_COVERAGE, DEFAULT_MIN_FREQ, DEFAULT_SB_ALPHA
9
+
10
+
11
+ def add_research_output_args(parser: ArgumentParser) -> None:
12
+ """Attach opt-in 1.3.0 flags. Defaults leave TSV/XML unchanged."""
13
+ parser.add_argument(
14
+ "--min-baseq",
15
+ type=float,
16
+ default=None,
17
+ help=(
18
+ "If set, count a codon only when all three bases have Phred-like "
19
+ "quality ≥ this value (e.g. 20). Off by default so TSV/XML stay "
20
+ "byte-identical to 1.2.1."
21
+ ),
22
+ )
23
+ parser.add_argument(
24
+ "--stats",
25
+ type=Path,
26
+ default=None,
27
+ help="Optional stats TSV (Wilson 95%% CI, strand-bias p, flags, diversity).",
28
+ )
29
+ parser.add_argument(
30
+ "--aavf",
31
+ type=Path,
32
+ default=None,
33
+ help="Optional AAVF v1.0 path. Research use only; CAT/SRVL are omitted.",
34
+ )
35
+ parser.add_argument(
36
+ "--min-freq",
37
+ type=float,
38
+ default=DEFAULT_MIN_FREQ,
39
+ help="Frequency floor (fraction 0–1) for the lowfreq flag / AAVF FILTER (default: 0.01).",
40
+ )
41
+ parser.add_argument(
42
+ "--min-coverage",
43
+ type=int,
44
+ default=DEFAULT_MIN_COVERAGE,
45
+ help="Coverage floor for the lowcov flag / AAVF FILTER (default: 10).",
46
+ )
47
+ parser.add_argument(
48
+ "--sb-alpha",
49
+ type=float,
50
+ default=DEFAULT_SB_ALPHA,
51
+ help="Fisher exact p-value cutoff for the sb (strand-bias) flag (default: 0.05).",
52
+ )
@@ -0,0 +1,13 @@
1
+ from __future__ import annotations
2
+
3
+ DEFAULT_RATIO_UPPER = 3.16227766
4
+ DEFAULT_RATIO_LOWER = 0.316227766
5
+ DEFAULT_ENTROPY_THRESHOLD = 0.0
6
+ DEFAULT_PROTEIN = "RT"
7
+
8
+ # Opt-in research statistics (v1.3.0). Unused unless --stats / --aavf / --min-baseq is set.
9
+ PACKAGE_VERSION = "1.3.0"
10
+ WILSON_Z_95 = 1.959963984540054 # Φ^{-1}(0.975)
11
+ DEFAULT_MIN_FREQ = 0.01
12
+ DEFAULT_MIN_COVERAGE = 10
13
+ DEFAULT_SB_ALPHA = 0.05
@@ -24,6 +24,7 @@ class SamContainer:
24
24
  ratio_upper: float,
25
25
  ratio_lower: float,
26
26
  entropy_threshold: float,
27
+ min_baseq: float | None = None,
27
28
  ) -> None:
28
29
  """Initialize the container with the SAM path, ratio window, and entropy threshold."""
29
30
  self.sam_path = sam_path
@@ -34,6 +35,7 @@ class SamContainer:
34
35
  self.ratio_upper = ratio_upper
35
36
  self.ratio_lower = ratio_lower
36
37
  self.entropy_threshold = entropy_threshold
38
+ self.min_baseq = min_baseq
37
39
 
38
40
  def load(self) -> None:
39
41
  """Load every mapped read from the SAM file so they can be aggregated."""
@@ -90,7 +92,9 @@ class SamContainer:
90
92
  jobs: list[tuple[Protein, dict[int, dict]]] = []
91
93
  for protein in proteins:
92
94
  entries: dict[int, dict] = {}
95
+ aa_pos = 0
93
96
  for pos, record_id in self._get_codon_positions(protein, reference):
97
+ aa_pos += 1
94
98
  entries[pos] = {
95
99
  "variants": {},
96
100
  "fw_depth": 0,
@@ -98,6 +102,7 @@ class SamContainer:
98
102
  "depth": 0,
99
103
  "amplicons": {},
100
104
  "record_id": record_id,
105
+ "aa_pos": aa_pos,
101
106
  }
102
107
  jobs.append((protein, entries))
103
108
 
@@ -128,6 +133,10 @@ class SamContainer:
128
133
  codon = read.codon_at(pos)
129
134
  if not codon or len(codon) < 3:
130
135
  return
136
+ if self.min_baseq is not None:
137
+ quals = read.codon_qualities_at(pos)
138
+ if quals is None or any(qual < self.min_baseq for qual in quals):
139
+ return
131
140
  depth_increment = read.occurences
132
141
  variants: dict[str, Variant] = entry["variants"]
133
142
  if read.orientation == "F":
@@ -390,3 +399,53 @@ class SamContainer:
390
399
  self._add_positions(protein_elem, entries)
391
400
  tree = ET.ElementTree(root)
392
401
  tree.write(output_path, encoding="utf-8", xml_declaration=True)
402
+
403
+ def write_stats(
404
+ self,
405
+ sample_name: str,
406
+ reference: FullReference,
407
+ output_path: Path,
408
+ protein_names: Sequence[str],
409
+ *,
410
+ min_freq: float,
411
+ min_coverage: int,
412
+ sb_alpha: float,
413
+ ) -> None:
414
+ """Write the opt-in stats TSV (Wilson CI, strand bias, diversity)."""
415
+ from .stats_writer import write_stats_tsv
416
+
417
+ write_stats_tsv(
418
+ sample_name,
419
+ reference,
420
+ output_path,
421
+ self._output_pairs(protein_names),
422
+ min_freq=min_freq,
423
+ min_coverage=min_coverage,
424
+ sb_alpha=sb_alpha,
425
+ )
426
+
427
+ def write_aavf(
428
+ self,
429
+ sample_name: str,
430
+ reference: FullReference,
431
+ output_path: Path,
432
+ protein_names: Sequence[str],
433
+ *,
434
+ min_freq: float,
435
+ min_coverage: int,
436
+ sb_alpha: float,
437
+ file_date: str | None = None,
438
+ ) -> None:
439
+ """Write the opt-in AAVF v1.0 file. Research use only; no CAT/SRVL."""
440
+ from .aavf import write_aavf as _write_aavf
441
+
442
+ _write_aavf(
443
+ sample_name,
444
+ reference,
445
+ output_path,
446
+ self._output_pairs(protein_names),
447
+ min_freq=min_freq,
448
+ min_coverage=min_coverage,
449
+ sb_alpha=sb_alpha,
450
+ file_date=file_date,
451
+ )