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 .
```
