abstar assigns immunoglobulin and T-cell receptor germline genes and produces
detailed V(D)J annotations. It supports the command line, a Python API, and
AIRR TSV and Parquet output.
- Source: github.com/brineylab/abstar
- Documentation: abstar.readthedocs.org
- Package: pypi.org/project/abstar
- Container: hub.docker.com/r/brineylab/datascience
abstar supports Python 3.10 through 3.13. The tested dependency ranges include
abutils>=0.6.1, polars>=1.6, and pyarrow>=16.1.
pip install abstarOn Apple Silicon, Parasail needs source-build prerequisites. See the macOS installation instructions.
MMseqs2 and fastp executables are provided through abutils; no separate
system installation is required for the normal packaged workflow.
Annotate one FASTA or FASTQ file into a project directory:
abstar run path/to/sequences.fasta path/to/project_directoryDirectories are discovered recursively:
abstar run path/to/input_directory path/to/project_directoryUse -o parquet, or repeat -o to write both formats. Use --receptor tcr
for TCR annotation. Run abstar run --help for merging, UMI, germline database,
and performance options.
The API preserves the input category:
import abstar
from abutils import Sequence
one = abstar.run(Sequence("N", id="one"))
many = abstar.run([Sequence("N", id="first"), Sequence("N", id="second")])
frame = abstar.run("sequences.fasta", as_dataframe=True)One input record returns one abutils.Sequence when it annotates or is unassigned; multiple records return a list,
including when only one is assigned; as_dataframe=True always returns a Polars
DataFrame. Every returned or written row has annotation_status. Biological
non-assignment produces an unassigned row with failure_reason. A sequence
annotation exception is logged and omitted from the result; other records and
samples continue. An entirely failed input returns an empty list/DataFrame with
a warning and persistent diagnostics. Use strict=True or CLI --strict to
raise abstar.AnnotationRunError on sequence errors instead. Worker, input,
external-tool, and output failures still abort. partial_output_paths lists
retained artifacts for aborted runs.
Per-record diagnostics live in logs/<input-stem>/<encoded-id>__<row-key>.failed.
logs/failures.tsv indexes exact IDs, source files, exceptions, and diagnostic
paths; logs/run.json records versions, source hashes, and parameters. API calls
warn with the index location, including when no project directory was supplied.
Duplicate visible IDs and input ordering are preserved.
Every output (AIRR TSV, Parquet, and Python returns) targets the AIRR 2.0
Rearrangement schema with identical fields and meanings: 1-based closed
coordinates and the original, unmodified query as sequence; rev_comp
indicates that calls, alignments, and coordinates address its reverse
complement. The assembled V(D)J is in sequence_vdj / sequence_vdj_aa. TSV
writes T/F booleans and empty null cells. 0.9.0 changed coordinates and
sequence meanings from 0.8.x; see the
changelog and
output-format documentation.
Install the development test environment:
python -m pip install -r requirements-test.txtThe ordinary fast gate and the complete suite are:
python -m pytest -m "not integration and not e2e and not slow" -q
python -m pytest -qThe integration and end-to-end gate uses real bundled executables and databases:
python -m pytest -m "integration or e2e" -qContributor commands, coverage floors, focused AIRR/database gates, and the
optional external-corpus discovery command are documented in AGENTS.md. The
bulk published corpus is never required by ordinary CI.
A separate push/PR workflow runs the fixed, committed BCR subset in
test_data/bcr_corpus/. It checks record
conservation, internal annotation consistency, and exact regression baselines.
See the test debugging guide before changing expected
assignment results. This corpus is not repeated in the pytest version matrix
or included in installed Python distributions.