altar-borzoi 0.3.0__tar.gz

altar_borzoi-0.3.0/.gitignore

@@ -0,0 +1,33 @@
+*.pyc
+*~
+**/__pycache__/*
+*.swp
+.vscode/
+.idea/
+.DS_Store
+.env*
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+pytest.xml
+.hypothesis/
+.python-version
+.venv
+.venv-*/
+*.egg-info/
+build/
+dist/
+site/
+*.sqlite3
+*.log
+
+# Generated variant indexes and datasets. The small canonical gene table is tracked.
+altar/altar/variants/data/ccres.dnatree
+altar/altar/variants/data/region_annotations.parquet
+altar/altar/variants/data/variants.pkl.gz
+altar/altar/variants/data/region_provenance.json
+altar/altar/variants/data/raw/
+

altar_borzoi-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Riya Sinha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

altar_borzoi-0.3.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: altar-borzoi
+Version: 0.3.0
+Summary: Borzoi model binding for large-scale Altar variant-gene 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 Borzoi binding
+
+`altar-borzoi` is the lightweight control-plane binding for large-scale, gene-specific Borzoi variant
+scoring. It registers `BORZOI` in Altar's canonical model-plugin group without installing TensorFlow or the
+model's scientific runtime into the framework environment.
+
+One model instance pins the four published human replicate weights, official prediction parameters, the
+GTEx RNA target subset, GENCODE 41 gene annotation, selected output tracks, reverse-complement/shift
+ensembling, an immutable runtime image, and the hg38 reference identity. Each deterministic outer variant
+batch becomes one retryable GPU task. Within that task the runtime loads each replicate exactly once,
+streams small ref/alt tensor batches, and averages the official per-replicate scores through a disk-backed
+accumulator.
+
+The primary table contains the gene/target pair with the largest absolute `logSED` for each variant. The
+`gene_effects` detail table preserves mean `logSED` and `logD2` for every scored `(variant, gene, target)`
+tuple. The `altar-borzoi-resources` command fetches and records the published resources. The TensorFlow 2.15
+executor lives under `runtimes/borzoi`, and `DEFAULT_IMAGE` pins its published image by digest.

altar_borzoi-0.3.0/README.md

@@ -0,0 +1,17 @@
+# Altar Borzoi binding
+
+`altar-borzoi` is the lightweight control-plane binding for large-scale, gene-specific Borzoi variant
+scoring. It registers `BORZOI` in Altar's canonical model-plugin group without installing TensorFlow or the
+model's scientific runtime into the framework environment.
+
+One model instance pins the four published human replicate weights, official prediction parameters, the
+GTEx RNA target subset, GENCODE 41 gene annotation, selected output tracks, reverse-complement/shift
+ensembling, an immutable runtime image, and the hg38 reference identity. Each deterministic outer variant
+batch becomes one retryable GPU task. Within that task the runtime loads each replicate exactly once,
+streams small ref/alt tensor batches, and averages the official per-replicate scores through a disk-backed
+accumulator.
+
+The primary table contains the gene/target pair with the largest absolute `logSED` for each variant. The
+`gene_effects` detail table preserves mean `logSED` and `logD2` for every scored `(variant, gene, target)`
+tuple. The `altar-borzoi-resources` command fetches and records the published resources. The TensorFlow 2.15
+executor lives under `runtimes/borzoi`, and `DEFAULT_IMAGE` pins its published image by digest.

altar_borzoi-0.3.0/altar_borzoi/__init__.py

@@ -0,0 +1,33 @@
+# Copyright 2026 Riya Sinha
+"""Public Borzoi binding exports."""
+
+from altar_borzoi.plugin import (
+    DEFAULT_IMAGE,
+    GTEX_TARGET_COUNT,
+    GTEX_TARGET_MAX,
+    GTEX_TARGET_MIN,
+    KIND_SCORING,
+    OUTPUT_BIN_SIZE,
+    OUTPUT_BINS,
+    SEQUENCE_LENGTH,
+    BorzoiConfiguration,
+    BorzoiPlugin,
+    BorzoiRunInputs,
+    BorzoiShardKind,
+)
+
+
+__all__ = [
+    "DEFAULT_IMAGE",
+    "GTEX_TARGET_COUNT",
+    "GTEX_TARGET_MAX",
+    "GTEX_TARGET_MIN",
+    "KIND_SCORING",
+    "OUTPUT_BINS",
+    "OUTPUT_BIN_SIZE",
+    "SEQUENCE_LENGTH",
+    "BorzoiConfiguration",
+    "BorzoiPlugin",
+    "BorzoiRunInputs",
+    "BorzoiShardKind",
+]

altar_borzoi-0.3.0/altar_borzoi/plugin.py

@@ -0,0 +1,290 @@
+# Copyright 2026 Riya Sinha
+"""Backend-neutral Borzoi binding for gene-specific variant scoring."""
+
+from __future__ import annotations
+import enum
+from typing import TYPE_CHECKING, Any, cast
+
+from altar.execution import GpuPool, ResourceRequest
+from altar.models import (
+    ApiVersionRange,
+    ContainerImageDigest,
+    ContainerScoringPlan,
+    DetailSchema,
+    ModelConfiguration,
+    ModelPlugin,
+    OutputSelection,
+    PluginCapability,
+    PluginKind,
+    PluginManifest,
+    PrioritizationPolicy,
+    ReferenceGenomeRunInputs,
+    ResourceReference,
+    ResultField,
+    ResultSchema,
+    RuntimeIdentityPolicy,
+    RuntimeKind,
+    RuntimeRequirement,
+    ScoringRequest,
+    VariantClass,
+    VariantEligibility,
+    require_resource_digests,
+    require_strictly_increasing,
+    resource_transfer,
+    single_container_plan,
+)
+from altar.predicates import Abs, Col, Ge, Lit, Predicate
+from pydantic import Field, model_validator
+
+from altar_borzoi.resources import manifest_resources
+
+
+if TYPE_CHECKING:
+    import os
+
+
+SEQUENCE_LENGTH = 524_288
+OUTPUT_BIN_SIZE = 32
+OUTPUT_BINS = 16_352
+GTEX_TARGET_MIN = 7_522
+GTEX_TARGET_MAX = 7_610
+GTEX_TARGET_COUNT = GTEX_TARGET_MAX - GTEX_TARGET_MIN + 1
+PUBLISHED_REPLICATE_COUNT = 4
+MIN_SHIFT = -3
+MAX_SHIFT = 3
+DEFAULT_IMAGE = "riyavsinha/altar-borzoi@sha256:12872cd13da71705857a1a00e47901c244086aefcd5f6b63ae47474f5e94ee9a"
+
+
+class BorzoiShardKind(enum.StrEnum):
+    """Stable execution kind emitted by :class:`BorzoiPlugin`."""
+
+    SCORING = "borzoi_scoring"
+
+
+KIND_SCORING = BorzoiShardKind.SCORING
+_SCORE_RESOURCES = ResourceRequest(gpu=GpuPool.NORMAL_GPU, count=1, memory_gb=24)
+_LOG_SED_PRIORITIZE_THRESHOLD = 0.5
+
+
+class BorzoiConfiguration(ModelConfiguration):
+    """Immutable official Borzoi ensemble and gene-expression scoring settings."""
+
+    weights: tuple[ResourceReference, ...] = Field(min_length=PUBLISHED_REPLICATE_COUNT, max_length=4)
+    parameters: ResourceReference
+    target_metadata: ResourceReference
+    gene_annotation: ResourceReference
+    target_indices: tuple[int, ...] = Field(min_length=1)
+    reverse_complement: bool = True
+    shifts: tuple[int, ...] = (0,)
+    image: ContainerImageDigest = DEFAULT_IMAGE
+
+    @model_validator(mode="after")
+    def validate_resources_and_selection(self) -> BorzoiConfiguration:
+        require_resource_digests(self, owner="Borzoi")
+        weight_digests = [resource.digest for resource in self.weights]
+        if len(set(weight_digests)) != PUBLISHED_REPLICATE_COUNT:
+            msg = "Borzoi requires four distinct published replicate weight digests"
+            raise ValueError(msg)
+        require_strictly_increasing(
+            self.target_indices,
+            owner="Borzoi",
+            field="target_indices",
+            minimum=GTEX_TARGET_MIN,
+            maximum=GTEX_TARGET_MAX,
+        )
+        require_strictly_increasing(self.shifts, owner="Borzoi", field="shifts", minimum=MIN_SHIFT, maximum=MAX_SHIFT)
+        return self
+
+    @classmethod
+    def from_resource_manifest(
+        cls, path: str | os.PathLike[str], *, base_uri: str | None = None, **settings: Any
+    ) -> BorzoiConfiguration:
+        """Build a configuration from the ``borzoi.resources.json`` that ``altar-borzoi-resources`` wrote.
+
+        ``settings`` are the remaining configuration fields: ``target_indices``, and the optional
+        ``reverse_complement``, ``shifts`` and ``image``. See :func:`altar_borzoi.resources.manifest_resources`
+        for how ``base_uri`` locates the files.
+        """
+        resources = manifest_resources(path, base_uri=base_uri)
+        return cls(
+            weights=resources.weights,
+            parameters=resources.parameters,
+            target_metadata=resources.target_metadata,
+            gene_annotation=resources.gene_annotation,
+            **settings,
+        )
+
+
+class BorzoiRunInputs(ReferenceGenomeRunInputs):
+    """Per-run Borzoi inputs, restricted to the published human assembly."""
+
+    supported_genome_builds = frozenset({"hg38"})
+
+
+class BorzoiPlugin(ModelPlugin):
+    """Predicts how a variant changes the RNA-seq coverage of nearby genes in the tracks you select (logSED)."""
+
+    model_type = "BORZOI"
+    manifest = PluginManifest(
+        plugin_id="org.kundajelab.altar.model.borzoi",
+        kind=PluginKind.MODEL,
+        capabilities=frozenset({PluginCapability.SCORE, PluginCapability.MATERIALIZE_RESULTS}),
+        architecture="Borzoi",
+        plugin_version="0.0.2",
+        altar_api=ApiVersionRange("0.1.0", "0.2.0"),
+        configuration_schema_version="0.0.1",
+        result_schema=ResultSchema(
+            version="0.0.2",
+            fields=(
+                ResultField("top_gene_id", "str", "Top Gene", "Gene with largest absolute mean logSED"),
+                ResultField("top_gene_name", "str", "Top Gene Name", "GENCODE name of the top gene"),
+                ResultField("top_gene_strand", "str", "Top Gene Strand", "GENCODE strand of the top gene"),
+                ResultField("top_target_index", "int", "Top Target Index", "Original Borzoi output index"),
+                ResultField("top_target_id", "str", "Top Target", "Identifier of the top GTEx output"),
+                ResultField("top_target_label", "str", "Top Target Label", "Tissue label of the top output"),
+                ResultField("top_log_sed", "float", "Top logSED", "Mean signed gene expression log2 fold change"),
+                ResultField("top_log_d2", "float", "Top logD2", "Mean bin-level log-profile L2 distance"),
+                ResultField("n_genes_scored", "int", "Genes Scored", "Genes with exons in the prediction window"),
+                ResultField("n_effects_scored", "int", "Effects Scored", "Variant-gene-target effects emitted"),
+                ResultField("n_replicates", "int", "Replicates", "Published model replicates averaged"),
+            ),
+        ),
+        detail_schemas=(
+            DetailSchema(
+                name="gene_effects",
+                version="0.0.1",
+                description="Mean official Borzoi logSED/logD2 for each variant-gene-GTEx target tuple.",
+                fields=(
+                    ResultField("gene_id", "str", "Gene ID", "GENCODE gene identifier", False),
+                    ResultField("gene_name", "str", "Gene Name", "GENCODE gene name", False),
+                    ResultField("gene_strand", "str", "Gene Strand", "GENCODE gene strand", False),
+                    ResultField("target_index", "int", "Target Index", "Original Borzoi output index", False),
+                    ResultField("target_id", "str", "Target ID", "GTEx experiment identifier", False),
+                    ResultField("target_label", "str", "Target Label", "GTEx tissue label", False),
+                    ResultField("log_sed", "float", "logSED", "Mean signed expression log2 fold change", False),
+                    ResultField("log_d2", "float", "logD2", "Mean bin-level log-profile L2 distance", False),
+                    ResultField("n_replicates", "int", "Replicates", "Published model replicates averaged", False),
+                ),
+                key_fields=("gene_id", "target_index"),
+                # The runtime sets n_effects_scored to the number of gene_effects rows it emits per variant, so a
+                # cached variant with no gene in its window (0) is complete, not a miss on every preparation.
+                row_count_field="n_effects_scored",
+            ),
+        ),
+        # The Borzoi runtime substitutes one reference base; batch preparation filters out indels and MNVs.
+        variant_eligibility=VariantEligibility(frozenset({VariantClass.SNV})),
+        prioritization=PrioritizationPolicy(name="borzoi-logsed-effect-v1", version="0.0.1"),
+        runtimes=(
+            RuntimeRequirement(
+                name="model_runtime",
+                kind=RuntimeKind.CONTAINER_IMAGE,
+                policy=RuntimeIdentityPolicy.DIGEST_REQUIRED,
+            ),
+        ),
+    )
+    configuration_schema_id = "org.kundajelab.altar.model.borzoi.configuration"
+    configuration_model = BorzoiConfiguration
+    run_input_model = BorzoiRunInputs
+    default_output = OutputSelection(outputs=("scores", "gene_effects"), reducer="official_logsed_logd2_mean_v1")
+
+    def scoring_runtime_identities(self, configuration: ModelConfiguration) -> dict[str, str]:
+        """Record the configured Borzoi image as the scoring plan's one runtime."""
+        return {"model_runtime": self.parse_configuration_as(configuration, BorzoiConfiguration).image}
+
+    def build_scoring_plan(self, request: ScoringRequest) -> ContainerScoringPlan:
+        configuration = self.parse_configuration_as(request.configuration, BorzoiConfiguration)
+        run_inputs = self.parse_run_inputs_as(request.run_inputs, BorzoiRunInputs)
+        layout, resolver = request.layout, request.resolver
+        weight_logicals = tuple(
+            layout.model_resource_file(request.model_id, f"borzoi.f{index}.h5")
+            for index in range(PUBLISHED_REPLICATE_COUNT)
+        )
+        parameters_logical = layout.model_resource_file(request.model_id, "params_pred.json")
+        targets_logical = layout.model_resource_file(request.model_id, "targets_gtex.txt")
+        genes_logical = layout.model_resource_file(request.model_id, "gencode41_basic_nort.gtf")
+        genome_logical = layout.genome_fasta(request.genome_label)
+        variants_logical = layout.model_variants_file(request.job_id, request.model_id, request.scoring_batch)
+        primary_logical = layout.scoring_result_file(request.job_id, request.model_id, request.scoring_batch)
+        details_logical = layout.detail_result_file(
+            request.job_id, request.model_id, "gene_effects", request.scoring_batch
+        )
+        command = ["borzoi-score", "score"]
+        for weight_logical, weight in zip(weight_logicals, configuration.weights, strict=True):
+            command += [
+                "--weight",
+                resolver.resolve(weight_logical),
+                "--weight-digest",
+                cast("str", weight.digest),
+            ]
+        command += [
+            "--parameters",
+            resolver.resolve(parameters_logical),
+            "--parameters-digest",
+            cast("str", configuration.parameters.digest),
+            "--target-metadata",
+            resolver.resolve(targets_logical),
+            "--target-metadata-digest",
+            cast("str", configuration.target_metadata.digest),
+            "--gene-annotation",
+            resolver.resolve(genes_logical),
+            "--gene-annotation-digest",
+            cast("str", configuration.gene_annotation.digest),
+        ]
+        for target_index in configuration.target_indices:
+            command += ["--target-index", str(target_index)]
+        if configuration.reverse_complement:
+            command.append("--reverse-complement")
+        for shift in configuration.shifts:
+            command += ["--shift", str(shift)]
+        command += [
+            "--genome",
+            resolver.resolve(genome_logical),
+            "--genome-digest",
+            cast("str", run_inputs.genome.digest),
+            "--variants",
+            resolver.resolve(variants_logical),
+            "--primary-output",
+            resolver.resolve(primary_logical),
+            "--detail-output",
+            resolver.resolve(details_logical),
+        ]
+        inputs = [
+            resource_transfer(weight, logical, locality_key=request.model_id)
+            for logical, weight in zip(weight_logicals, configuration.weights, strict=True)
+        ]
+        inputs.extend(
+            (
+                resource_transfer(configuration.parameters, parameters_logical, locality_key=request.model_id),
+                resource_transfer(configuration.target_metadata, targets_logical, locality_key=request.model_id),
+                resource_transfer(configuration.gene_annotation, genes_logical, locality_key=request.model_id),
+                resource_transfer(run_inputs.genome, genome_logical),
+            )
+        )
+        return single_container_plan(
+            self,
+            request,
+            kind=KIND_SCORING,
+            image=configuration.image,
+            command=command,
+            resources=_SCORE_RESOURCES,
+            inputs=inputs,
+        )
+
+    def prioritize_predicate(self) -> Predicate:
+        return Ge(Abs(Col("top_log_sed")), Lit(_LOG_SED_PRIORITIZE_THRESHOLD))
+
+
+__all__ = [
+    "DEFAULT_IMAGE",
+    "GTEX_TARGET_COUNT",
+    "GTEX_TARGET_MAX",
+    "GTEX_TARGET_MIN",
+    "KIND_SCORING",
+    "OUTPUT_BINS",
+    "OUTPUT_BIN_SIZE",
+    "SEQUENCE_LENGTH",
+    "BorzoiConfiguration",
+    "BorzoiPlugin",
+    "BorzoiRunInputs",
+    "BorzoiShardKind",
+]

altar_borzoi-0.3.0/altar_borzoi/py.typed

@@ -0,0 +1 @@
+