codonyat 0.1.0__tar.gz

codonyat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 codonyat contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codonyat-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: codonyat
+Version: 0.1.0
+Summary: codon-yat — A codon-aware amino acid variant typer from SAM alignments of viral NGS data.
+Author-email: Marc Noguera Julian <info@treetopunder.com>
+Project-URL: Source, https://github.com/mnoguera/aa_caller
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: biopython>=1.79
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# codonyat
+
+codon-yat — A codon-aware amino acid variant typer from SAM alignments of viral NGS data.
+
+A standalone Python package that performs amino acid variant calling, including:
+
+- SAM parsing that honors amplicon labels and strand orientation.
+- Ratio balancing, entropy tracking, and TSV/XML exporters mirroring the legacy Perl outputs.
+- Configurable CLI flags for strand ratio bounds and entropy sensitivity.
+
+- Works directly on viral genomic datasets generated by high-throughput NGS pipelines and relies on protein-level annotations so you can derive amino-acid variants without reimplementing parsing logic.
+ 
+## Highlights
+
+- Produces consistent TSV/XML diagnostics while adding 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.
+
+## Installation
+
+```bash
+pip install .
+```
+
+Or publish the package (e.g., via `twine`/PyPI) and install it like any other dependency.
+
+## CLI usage
+
+Once installed, the `codonyat` entry point is available:
+
+```bash
+codonyat /path/to/sample.sam /path/to/reference.fasta /path/to/amplicons.tsv
+```
+
+Supply `--ratio-upper`, `--ratio-lower`, and `--entropy-threshold` to tune the balancing heuristics.
+
+The CLI writes `[sam-file].tsv` (columns: FILE, REFERENCE, PROTEIN, VARIANT, POSITION, FREQ, FWCOV, RVCOV, TOTALCOV, RATIO) and `[sam-file].xml` (per-position `<Depth>`, `<FwCover>`, `<RvCover>`, `<Variants>`).
+
+## Package API
+
+Import `aa_caller` to reuse the core objects:
+
+```python
+from aa_caller import SamContainer, FullReference, parse_amplicons
+```
+
+The `SamContainer` constructor still accepts `ratio_upper`, `ratio_lower`, and `entropy_threshold` so you can reuse the balancing logic in scripts.
+
+### Python wrapper
+
+Use `call_variants` to run the full pipeline from Python without touching the CLI. It validates the inputs, builds the `SamContainer`, and writes the TSV/XML artifacts while returning a `VariantCallResult` you can inspect.
+
+```python
+from pathlib import Path
+
+from aa_caller import call_variants
+
+result = call_variants(
+	sam_path=Path("reads.sam"),
+	reference_path=Path("reference.fasta"),
+	amplicons_path=Path("amps.tsv"),
+	ratio_upper=3.2,
+)
+
+print(result.csv_path, result.xml_path)
+print(result.container.variants.keys())
+```
+
+If you already have an `argparse.Namespace` or mapping of the CLI arguments, `call_variants_from_args` adapts them directly.
+
+```python
+from argparse import Namespace
+
+args = Namespace(
+	sam_file="reads.sam",
+	reference_file="reference.fasta",
+	amplicons_file="amps.tsv",
+	ratio_upper=3.2,
+)
+
+call_variants_from_args(args)
+```
+
+### CLI wrapper
+
+This repository installs a lightweight runner at `codonyat-runner` that exposes the same entry arguments as `call_variants_from_args`. Use it when you prefer a small CLI shim over the full `codonyat` entry point:
+
+```bash
+codonyat-runner reads.sam reference.fasta amps.tsv --ratio-upper 3.1 --csv-path results.tsv
+```
+
+## Development
+
+Install the repository with the optional dev tooling so your local environment matches CI:
+
+```bash
+pip install --upgrade pip
+pip install -e .[dev]
+```
+
+Now you can run the same checks that land in [.github/workflows/python-tests.yml](.github/workflows/python-tests.yml#L1-L27):
+
+```bash
+ruff check .
+python -m pytest
+```
+
+The workflow installs `pytest` and `ruff`, runs the linter, and then executes the pytest suite on every push/PR against `main`.
+
+## Testing
+
+Run the upstream validation helpers with `pytest`:
+
+```bash
+python -m pytest
+```
+
+Keep the code tidy with `ruff` before committing:
+
+```bash
+ruff check .
+```

codonyat-0.1.0/README.md

@@ -0,0 +1,122 @@
+# codonyat
+
+codon-yat — A codon-aware amino acid variant typer from SAM alignments of viral NGS data.
+
+A standalone Python package that performs amino acid variant calling, including:
+
+- SAM parsing that honors amplicon labels and strand orientation.
+- Ratio balancing, entropy tracking, and TSV/XML exporters mirroring the legacy Perl outputs.
+- Configurable CLI flags for strand ratio bounds and entropy sensitivity.
+
+- Works directly on viral genomic datasets generated by high-throughput NGS pipelines and relies on protein-level annotations so you can derive amino-acid variants without reimplementing parsing logic.
+ 
+## Highlights
+
+- Produces consistent TSV/XML diagnostics while adding 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.
+
+## Installation
+
+```bash
+pip install .
+```
+
+Or publish the package (e.g., via `twine`/PyPI) and install it like any other dependency.
+
+## CLI usage
+
+Once installed, the `codonyat` entry point is available:
+
+```bash
+codonyat /path/to/sample.sam /path/to/reference.fasta /path/to/amplicons.tsv
+```
+
+Supply `--ratio-upper`, `--ratio-lower`, and `--entropy-threshold` to tune the balancing heuristics.
+
+The CLI writes `[sam-file].tsv` (columns: FILE, REFERENCE, PROTEIN, VARIANT, POSITION, FREQ, FWCOV, RVCOV, TOTALCOV, RATIO) and `[sam-file].xml` (per-position `<Depth>`, `<FwCover>`, `<RvCover>`, `<Variants>`).
+
+## Package API
+
+Import `aa_caller` to reuse the core objects:
+
+```python
+from aa_caller import SamContainer, FullReference, parse_amplicons
+```
+
+The `SamContainer` constructor still accepts `ratio_upper`, `ratio_lower`, and `entropy_threshold` so you can reuse the balancing logic in scripts.
+
+### Python wrapper
+
+Use `call_variants` to run the full pipeline from Python without touching the CLI. It validates the inputs, builds the `SamContainer`, and writes the TSV/XML artifacts while returning a `VariantCallResult` you can inspect.
+
+```python
+from pathlib import Path
+
+from aa_caller import call_variants
+
+result = call_variants(
+	sam_path=Path("reads.sam"),
+	reference_path=Path("reference.fasta"),
+	amplicons_path=Path("amps.tsv"),
+	ratio_upper=3.2,
+)
+
+print(result.csv_path, result.xml_path)
+print(result.container.variants.keys())
+```
+
+If you already have an `argparse.Namespace` or mapping of the CLI arguments, `call_variants_from_args` adapts them directly.
+
+```python
+from argparse import Namespace
+
+args = Namespace(
+	sam_file="reads.sam",
+	reference_file="reference.fasta",
+	amplicons_file="amps.tsv",
+	ratio_upper=3.2,
+)
+
+call_variants_from_args(args)
+```
+
+### CLI wrapper
+
+This repository installs a lightweight runner at `codonyat-runner` that exposes the same entry arguments as `call_variants_from_args`. Use it when you prefer a small CLI shim over the full `codonyat` entry point:
+
+```bash
+codonyat-runner reads.sam reference.fasta amps.tsv --ratio-upper 3.1 --csv-path results.tsv
+```
+
+## Development
+
+Install the repository with the optional dev tooling so your local environment matches CI:
+
+```bash
+pip install --upgrade pip
+pip install -e .[dev]
+```
+
+Now you can run the same checks that land in [.github/workflows/python-tests.yml](.github/workflows/python-tests.yml#L1-L27):
+
+```bash
+ruff check .
+python -m pytest
+```
+
+The workflow installs `pytest` and `ruff`, runs the linter, and then executes the pytest suite on every push/PR against `main`.
+
+## Testing
+
+Run the upstream validation helpers with `pytest`:
+
+```bash
+python -m pytest
+```
+
+Keep the code tidy with `ruff` before committing:
+
+```bash
+ruff check .
+```

codonyat-0.1.0/aa_caller/__init__.py

@@ -0,0 +1,16 @@
+"""Light wrapper to expose the RT variant caller as a package."""
+
+from .app import main, FullReference, SamContainer, SamEntry, parse_amplicons
+from .runner import VariantCallResult, call_variants, call_variants_from_args, runner_cli
+
+__all__ = [
+	"call_variants",
+	"call_variants_from_args",
+	"runner_cli",
+	"VariantCallResult",
+	"main",
+	"FullReference",
+	"SamContainer",
+	"SamEntry",
+	"parse_amplicons",
+]

codonyat-0.1.0/aa_caller/__main__.py

@@ -0,0 +1,4 @@
+from .app import main
+
+if __name__ == "__main__":
+    main()