abstar
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
Install
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 abstar
On 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.
Use
Annotate one FASTA or FASTQ file into a project directory:
abstar run path/to/sequences.fasta path/to/project_directory
Directories are discovered recursively:
abstar run path/to/input_directory path/to/project_directory
Use -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.
Test
Install the development test environment:
python -m pip install -r requirements-test.txt
The ordinary fast gate and the complete suite are:
python -m pytest -m "not integration and not e2e and not slow" -q
python -m pytest -q
The integration and end-to-end gate uses real bundled executables and databases:
python -m pytest -m "integration or e2e" -q
Contributor 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.
Metadata
Release files for abstar 0.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| abstar-0.9.0.tar.gz | 825.3 kB | With provenance | Details for abstar-0.9.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| abstar-0.9.0-py3-none-any.whl | Python 3 | none | any | Details for abstar-0.9.0-py3-none-any.whl |
Total release size: 1.8 MB
Release files / abstar-0.9.0.tar.gz
| Download URL | abstar-0.9.0.tar.gz |
|---|---|
| Size | 825.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5f6aa66a968936cc07494dce8ee90ab93d4b2298da2646878a5328f7e826462a
|
|
BLAKE2b-256 checksum How to use checksums |
1464acd7dd3217cf191a8553de5f07cd997959c7f8aa680f6aab3a72176f2653
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / abstar-0.9.0-py3-none-any.whl
| Download URL | abstar-0.9.0-py3-none-any.whl |
|---|---|
| Size | 941.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ee32352cd11ecfc0e8677a67414b3ac802590869a4b1aeed90e5125e6ffb4c11
|
|
BLAKE2b-256 checksum How to use checksums |
d9df332ca28e4bb7fd41be128e51ab9443f4f5245ee59198a9c79c5d1a8c94aa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for abstar 0.9.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for abstar-0.9.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.