Metadata-Version: 2.5
Name: altar-sei
Version: 0.3.0
Summary: Sei model binding for large-scale Altar variant scoring
Project-URL: Documentation, https://kundajelab.github.io/altar/
Author: Riya Sinha
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: altar<0.4,>=0.3.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# Altar Sei binding

`altar-sei` is the lightweight control-plane binding for high-throughput Sei variant scoring. It registers
`SEI` in Altar's canonical model-plugin group and does not install PyTorch, SciPy, the model architecture, or
the official resources.

Each model instance identifies the official checkpoint, projection vectors, histone-profile indices,
sequence-class metadata, and an immutable runtime image by SHA-256 digest. The image defaults to
`altar_sei.DEFAULT_IMAGE`, a published image validated against FunctionLab's official Sei framework
(`runtimes/sei/validation/cpu-official-81f595f.json`). The binding emits one independently retryable task for each staged batch, and the
runtime loads Sei once and microbatches every reference/alternate sequence pair. `prepare_scoring_batches`
cache-filters Sei batches when it is given the `DetailStore` that holds `sequence_class_effects`.

The primary row reports the class with the largest absolute effect while retaining its sign. The
`sequence_class_effects` detail table preserves all 40 published class effects. Effects reproduce the official
workflow: strand-averaged 21,907-profile predictions are nucleosome-occupancy adjusted as a reference/alternate
pair, projected onto the published class vectors, and subtracted as alternate minus reference.

The per-profile predictions behind those effects are an opt-in artifact. A run whose output selection is
`SeiPlugin.profile_effects_output` also writes `chromatin_profile_effects`: one `.npz` per batch
(`application/x-npz`) with `variant_ids`, the float32 `effects` matrix of strand-averaged alternate-minus-reference
predictions for all 21,907 profiles (before nucleosome adjustment, NaN for an unscorable variant), the
`profile_index` of each column, and `profile_names`, the published name of each column's profile, so a consumer
maps columns to profiles without the runtime or its resources. The names come from the official archive's
`target.names`, which `SeiConfiguration.target_names` identifies by digest; scores never read it, so only a run
that selects the artifact requires it and stages it. It is not part of the score lineage. Altar never decodes the archive; the scoring engine digests
the file and records it in an `ArtifactStore` with the variants it covers, and batch preparation treats a variant
without it as a cache miss. The default selection's command line is unchanged; selecting the artifact is a
different output selection and therefore a different score lineage. In an `altar run` spec, name the artifact in
the model's `output` and declare an `[artifact_store]`.

The initial runtime accepts SNVs on hg19 or hg38. The manifest declares SNV-only variant eligibility, so
Altar's batch preparation filters out and reports other variant classes before they reach the runtime. The
runtime records incomplete windows, reference mismatches, unsupported allele symbols, and unsupported IUPAC
window bases as null-score rows that keep the variant's identity, logs the reason, and continues to score valid
batch neighbors; the primary table holds scores only. Such a row has `n_classes_scored` 0 and no class rows. The
binding declares `n_classes_scored` as the row count of `sequence_class_effects`, so batch preparation counts
the variant as complete on later runs. It also writes a null-score row for an indel in a batch
staged without that filter, but Altar's scoring engine rejects that row and fails the
batch rather than store a score for a variant the manifest excludes. A repeated canonical variant fails the
batch, as in every other runtime. `N` bases in otherwise valid windows
use Selene's uniform encoding and are flagged in `contains_unk`. That is narrower than Selene's general indel
machinery and is explicit: unsupported alleles do not receive an unversioned alignment policy. The operational
`max_abs_class_effect >= 1` prioritization default is not a universal biological cutoff; consumers should
calibrate prioritization for their cohort and question.

The executor lives under `runtimes/sei`. The official Sei implementation and resources are restricted to
academic and research use; those terms apply independently of this MIT-licensed binding.
