codonyat 0.1.0

codon-yat — A codon-aware amino acid variant typer from SAM alignments of viral NGS data.

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

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:

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:

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.

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.

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:

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:

pip install --upgrade pip
pip install -e .[dev]

Now you can run the same checks that land in .github/workflows/python-tests.yml:

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:

python -m pytest

Keep the code tidy with ruff before committing:

ruff check .