Skip to main content

tests Documentation Status

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.

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)

Source distribution for abstar 0.9.0
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)

Table of built distributions (wheels) for abstar 0.9.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

0.9.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page