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.
- {codonyat-1.2.1/codonyat.egg-info → codonyat-1.3.0}/PKG-INFO +31 -2
- {codonyat-1.2.1 → codonyat-1.3.0}/README.md +30 -1
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/__init__.py +3 -0
- codonyat-1.3.0/aa_caller/aavf.py +163 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/app.py +4 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/cli.py +26 -0
- codonyat-1.3.0/aa_caller/cli_options.py +52 -0
- codonyat-1.3.0/aa_caller/constants.py +13 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/container.py +59 -0
- codonyat-1.3.0/aa_caller/metrics.py +198 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/runner.py +51 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/sam.py +11 -0
- codonyat-1.3.0/aa_caller/stats_writer.py +192 -0
- {codonyat-1.2.1 → codonyat-1.3.0/codonyat.egg-info}/PKG-INFO +31 -2
- {codonyat-1.2.1 → codonyat-1.3.0}/codonyat.egg-info/SOURCES.txt +7 -1
- {codonyat-1.2.1 → codonyat-1.3.0}/pyproject.toml +1 -1
- codonyat-1.3.0/tests/test_metrics.py +154 -0
- codonyat-1.3.0/tests/test_v1_3_0_features.py +290 -0
- codonyat-1.2.1/aa_caller/constants.py +0 -6
- {codonyat-1.2.1 → codonyat-1.3.0}/LICENSE +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/__main__.py +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/genetic_code.py +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/models.py +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/reference.py +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/aa_caller/validators.py +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/codonyat.egg-info/dependency_links.txt +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/codonyat.egg-info/entry_points.txt +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/codonyat.egg-info/requires.txt +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/codonyat.egg-info/top_level.txt +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/setup.cfg +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/tests/test_app.py +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/tests/test_integration.py +0 -0
- {codonyat-1.2.1 → codonyat-1.3.0}/tests/test_protein_selection.py +0 -0
- {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.
|
|
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
|
-
│
|
|
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
|
-
│
|
|
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
|
+
)
|