altar-conservation 0.3.0__py3-none-any.whl

altar_conservation/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2026 Riya Sinha
+"""Base-wise conservation score tracks, such as UCSC phyloP 100-way, as Altar annotation sources."""
+
+from altar_conservation.source import ConservationAnnotationSource, PhyloP100wayAnnotationSource
+from altar_conservation.tracks import PHYLOP100WAY, PHYLOP100WAY_ANNOTATIONS, TRACKS, ConservationTrack
+
+
+__all__ = [
+    "PHYLOP100WAY",
+    "PHYLOP100WAY_ANNOTATIONS",
+    "TRACKS",
+    "ConservationAnnotationSource",
+    "ConservationTrack",
+    "PhyloP100wayAnnotationSource",
+]

altar_conservation/build_dataset.py

@@ -0,0 +1,319 @@
+# Copyright 2026 Riya Sinha
+"""Build a track's position score dataset from its upstream bigWig file, such as UCSC's ``hg38.phyloP100way.bw``.
+
+`build_dataset` checks the file's MD5 against the track's `upstream_md5`, then converts each primary contig
+(chr1-22, X, Y and M) in its own spawned process: the bigWig's records are read with pybigtools, their 0-based,
+half-open intervals become one row per base with a 1-based `pos` (`interval_rows`), and the rows are written with
+`altar.sources.PartitionedWriter` in the layout `altar.sources.POSITION_SCORE_METADATA` describes: Hive
+``chr=<contig>/``, 128,000-row groups, `pos` delta-encoded, the track, release and genome build in every footer.
+Records on other contigs (alts, unplaced scaffolds) are not kept. The output is a local directory; copy it to a
+bucket yourself.
+"""
+
+from __future__ import annotations
+import argparse
+import hashlib
+import itertools
+import multiprocessing
+import os
+import time
+from concurrent.futures import ProcessPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+import pyarrow as pa
+import pyarrow.parquet as pq
+from altar.sources import (
+    POSITION_SCORE_METADATA,
+    PartitionedWriter,
+    build_output,
+    position_score_release_fields,
+)
+
+from altar_conservation.tracks import TRACKS, ConservationTrack
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator, Mapping, Sequence
+
+
+PRIMARY_CONTIGS = (*(f"chr{number}" for number in range(1, 23)), "chrX", "chrY", "chrM")
+"""The contigs a position score dataset keeps, in UCSC's spelling, which is also Altar's."""
+SCHEMA = pa.schema(
+    [
+        pa.field("chr", pa.string(), nullable=False),
+        pa.field("pos", pa.int32(), nullable=False),
+        pa.field("score", pa.float32(), nullable=False),
+    ]
+)
+"""One row per scored base: the contig, the 1-based position and the score."""
+ROW_GROUP_ROWS = 128_000
+PARQUET_OPTIONS: dict[str, Any] = {
+    # `chr` repeats and scores take few distinct values; positions increase, so they are delta-encoded, which needs
+    # dictionary encoding off for `pos`.
+    "use_dictionary": ["chr", "score"],
+    "column_encoding": {"pos": "DELTA_BINARY_PACKED"},
+}
+_STEM = "scores"
+_LABEL = "position score"
+# How many bigWig records a worker converts at once.
+_CHUNK_RECORDS = 4_000_000
+_RECORD = np.dtype([("start", np.int64), ("end", np.int64), ("value", np.float64)])
+_MD5_BLOCK_BYTES = 8 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class ContigSummary:
+    """What one contig contributed: its rows, its file and the file's size and row groups."""
+
+    contig: str
+    rows: int
+    file: Path
+    bytes: int
+    row_groups: int
+
+
+@dataclass(frozen=True)
+class BuildSummary:
+    """What `build_dataset` wrote."""
+
+    track: str
+    contigs: tuple[ContigSummary, ...]
+    skipped_contigs: int
+    seconds: float
+
+    @property
+    def rows(self) -> int:
+        """Every row written."""
+        return sum(contig.rows for contig in self.contigs)
+
+    @property
+    def files(self) -> tuple[Path, ...]:
+        """The files written, one per contig."""
+        return tuple(contig.file for contig in self.contigs)
+
+    @property
+    def bytes(self) -> int:
+        """The bytes written."""
+        return sum(contig.bytes for contig in self.contigs)
+
+    @property
+    def row_groups(self) -> int:
+        """The row groups written."""
+        return sum(contig.row_groups for contig in self.contigs)
+
+
+def interval_rows(
+    starts: np.ndarray, ends: np.ndarray, values: np.ndarray, *, after: int = 0, label: str = "the input"
+) -> tuple[np.ndarray, np.ndarray]:
+    """Return the rows of bigWig records: each base's 1-based position (int32) and its score (float32).
+
+    A record is a 0-based, half-open interval `[start, end)` with one value; a record of several bases becomes one
+    row per base, and unscored bases between records have no row. The records must be sorted and must not overlap,
+    so positions strictly increase, and must start after the 1-based position `after`, the last row of the previous
+    chunk of the same contig. Raises `ValueError` naming `label` otherwise, or for a value that is not finite.
+    """
+    starts = np.asarray(starts, dtype=np.int64)
+    ends = np.asarray(ends, dtype=np.int64)
+    lengths = ends - starts
+    if (lengths < 1).any() or (starts < 0).any():
+        index = int(np.flatnonzero((lengths < 1) | (starts < 0))[0])
+        msg = f"{label} has an empty or negative interval [{starts[index]}, {ends[index]})"
+        raise ValueError(msg)
+    scores = np.asarray(values, dtype=np.float32)
+    if not np.isfinite(scores).all():
+        index = int(np.flatnonzero(~np.isfinite(scores))[0])
+        msg = f"{label} has a value that is not finite ({values[index]}) at [{starts[index]}, {ends[index]})"
+        raise ValueError(msg)
+    if len(starts) and int(lengths.max()) == 1:
+        positions = starts + 1  # one base per record, as UCSC's phyloP files store
+    else:
+        # Each base's offset from its record's first base, added to that base's 1-based position.
+        firsts = np.repeat(starts + 1, lengths)
+        offsets = np.arange(len(firsts), dtype=np.int64) - np.repeat(np.cumsum(lengths) - lengths, lengths)
+        positions = firsts + offsets
+        scores = np.repeat(scores, lengths)
+    if len(positions):
+        steps = np.diff(positions, prepend=after)
+        if (steps < 1).any():
+            index = int(np.flatnonzero(steps < 1)[0])
+            previous = after if index == 0 else int(positions[index - 1])
+            msg = (
+                f"{label} is not sorted, or has overlapping records: position {int(positions[index])} follows "
+                f"{previous}"
+            )
+            raise ValueError(msg)
+        if int(positions[-1]) > np.iinfo(np.int32).max:
+            msg = f"{label} has a position beyond int32: {int(positions[-1])}"
+            raise ValueError(msg)
+    return positions.astype(np.int32), scores
+
+
+def contig_batches(
+    contig: str, records: Iterable[tuple[int, int, float]], *, chunk_records: int = _CHUNK_RECORDS
+) -> Iterator[pa.Table]:
+    """Yield `contig`'s rows from its bigWig records, `(start, end, value)` in order, as tables of `SCHEMA`."""
+    iterator = iter(records)
+    after = 0
+    label = f"the bigWig's {contig}"
+    while True:
+        chunk = np.fromiter(itertools.islice(iterator, chunk_records), dtype=_RECORD)
+        if not len(chunk):
+            return
+        positions, scores = interval_rows(chunk["start"], chunk["end"], chunk["value"], after=after, label=label)
+        after = int(positions[-1])
+        yield pa.table(
+            [pa.repeat(pa.scalar(contig), len(positions)), pa.array(positions), pa.array(scores)], schema=SCHEMA
+        )
+
+
+def check_md5(path: str | os.PathLike[str], expected: str) -> None:
+    """Raise `ValueError` unless the file's MD5 is `expected`, reading it in blocks."""
+    digest = hashlib.md5(usedforsecurity=False)
+    with Path(path).open("rb") as handle:
+        while block := handle.read(_MD5_BLOCK_BYTES):
+            digest.update(block)
+    if digest.hexdigest() != expected.lower():
+        msg = f"{path} has MD5 {digest.hexdigest()}, not {expected}, the checksum its host publishes; download it again"
+        raise ValueError(msg)
+
+
+def build_dataset(
+    track: ConservationTrack,
+    bigwig: str | os.PathLike[str],
+    output: str | os.PathLike[str],
+    *,
+    overwrite: bool = False,
+    workers: int | None = None,
+) -> BuildSummary:
+    """Build `track`'s position score dataset from its upstream bigWig, a local file, in the local directory `output`.
+
+    The file's MD5 must be the track's `upstream_md5`. Each primary contig the file holds is converted in its own
+    spawned process, `workers` at a time (default: one per contig, up to the CPU count); other contigs are skipped.
+    `output` must be empty or absent; with `overwrite`, a previous build there is replaced. A failed build leaves
+    nothing behind.
+    """
+    started = time.monotonic()
+    source = Path(bigwig)
+    if not source.is_file():
+        msg = f"no bigWig file at {source}"
+        raise FileNotFoundError(msg)
+    check_md5(source, track.upstream_md5)
+    contigs = _contigs(source)
+    primary = [contig for contig in PRIMARY_CONTIGS if contig in contigs]
+    if not primary:
+        msg = f"{source} holds none of the primary contigs {', '.join(PRIMARY_CONTIGS)}"
+        raise ValueError(msg)
+    if workers is not None and workers < 1:
+        msg = f"workers must be positive, got {workers}"
+        raise ValueError(msg)
+    count = min(len(primary), workers or os.cpu_count() or 1)
+    metadata = track_metadata(track)
+    with build_output(Path(output), overwrite=overwrite, partition_column="chr", label=_LABEL) as directory:
+        tasks = [(source, directory, contig, metadata) for contig in primary]
+        summaries = _convert(tasks, count)
+    return BuildSummary(
+        track=track.name,
+        contigs=tuple(summary for summary in summaries if summary is not None),
+        skipped_contigs=len(contigs) - len(primary),
+        seconds=time.monotonic() - started,
+    )
+
+
+def track_metadata(track: ConservationTrack) -> dict[str, str]:
+    """Return the footer metadata every file of `track`'s dataset records (`POSITION_SCORE_METADATA`)."""
+    return POSITION_SCORE_METADATA.write(
+        position_score_release_fields(contract=track.contract, release=track.release, genome_build=track.genome_build)
+    )
+
+
+def _contigs(source: Path) -> dict[str, int]:
+    import pybigtools  # noqa: PLC0415 - the `build` extra
+
+    with pybigtools.open(str(source)) as reader:
+        return dict(reader.chroms())
+
+
+def _convert(tasks: Sequence[tuple[Path, Path, str, Mapping[str, str]]], count: int) -> list[ContigSummary | None]:
+    if count == 1:
+        return [_convert_contig(*task) for task in tasks]
+    # `spawn` starts each worker from a fresh interpreter: forking a process with threads running can deadlock it.
+    context = multiprocessing.get_context("spawn")
+    with ProcessPoolExecutor(max_workers=count, mp_context=context) as pool:
+        futures = [pool.submit(_convert_contig, *task) for task in tasks]
+        try:
+            return [future.result() for future in futures]
+        except BaseException:
+            for future in futures:
+                future.cancel()
+            raise
+
+
+def _convert_contig(source: Path, output: Path, contig: str, metadata: Mapping[str, str]) -> ContigSummary | None:
+    import pybigtools  # noqa: PLC0415 - the `build` extra
+
+    with pybigtools.open(str(source)) as reader:
+        return write_contig(output, contig, reader.records(contig), metadata)
+
+
+def write_contig(
+    output: Path, contig: str, records: Iterable[tuple[int, int, float]], metadata: Mapping[str, str]
+) -> ContigSummary | None:
+    """Write `contig`'s rows from its bigWig records to `output/chr=<contig>/`; return `None` if it has none.
+
+    `records` are `(start, end, value)`, 0-based and half-open, in order, as pybigtools reads them; `metadata` is
+    `track_metadata`'s. The file is written under a ``.partial`` name and renamed when it is complete.
+    """
+    writer = PartitionedWriter(
+        output,
+        _STEM,
+        schema=SCHEMA,
+        partition_column="chr",
+        row_group_rows=ROW_GROUP_ROWS,
+        metadata=metadata,
+        parquet_options=PARQUET_OPTIONS,
+    )
+    rows = 0
+    try:
+        for batch in contig_batches(contig, records):
+            writer.append_batch(contig, batch)
+            rows += batch.num_rows
+        files = writer.commit()
+    except BaseException:
+        writer.abort()
+        raise
+    if not files:
+        return None
+    [file] = files
+    return ContigSummary(
+        contig=contig,
+        rows=rows,
+        file=file,
+        bytes=file.stat().st_size,
+        row_groups=pq.ParquetFile(file).metadata.num_row_groups,
+    )
+
+
+def main() -> None:
+    """Run the conservation track builder command."""
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n", 1)[0])
+    parser.add_argument("--track", required=True, choices=sorted(TRACKS), help="The track to build")
+    parser.add_argument("--input", required=True, help="The track's upstream bigWig file, downloaded locally")
+    parser.add_argument("--output", required=True, help="The local directory to write the dataset to")
+    parser.add_argument("--overwrite", action="store_true", help="Replace a previous build in --output")
+    parser.add_argument("--workers", type=int, help="Contigs to convert at once, in processes (default: CPU count)")
+    args = parser.parse_args()
+    summary = build_dataset(TRACKS[args.track], args.input, args.output, overwrite=args.overwrite, workers=args.workers)
+    for contig in summary.contigs:
+        print(f"{contig.contig}\t{contig.rows}")  # noqa: T201 - command-line report
+    print(  # noqa: T201
+        f"wrote {summary.rows} rows of {summary.track} in {len(summary.files)} files and {summary.row_groups} row "
+        f"groups ({summary.bytes / 1e9:.2f} GB) to {args.output}; skipped {summary.skipped_contigs} non-primary "
+        f"contigs; {summary.seconds:.0f} s"
+    )
+
+
+if __name__ == "__main__":
+    main()

altar_conservation/source.py

@@ -0,0 +1,164 @@
+# Copyright 2026 Riya Sinha
+"""Conservation tracks as annotation sources, read from the published copy or an owned one.
+
+`ConservationAnnotationSource` is `altar.sources.PositionScoreAnnotationSource` bound to one `ConservationTrack`:
+it reads the track's position score dataset (the copy the Kundaje lab publishes by default, or an owned copy) and
+resolves run spec options with `PublishedDataset.select_copy`. Each published track is a one-line subclass that names
+its track, registered under the track's name: `PhyloP100wayAnnotationSource` is ``phylop100way``.
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, Self
+
+from altar.sources import (
+    AnnotationContract,
+    OwnedDatasetCopy,
+    OwnedTableCopy,
+    PositionScoreAnnotationSource,
+    PublishedDataset,
+    unknown_options_message,
+)
+
+from altar_conservation.tracks import PHYLOP100WAY, ConservationTrack
+
+
+if TYPE_CHECKING:
+    import os
+    from collections.abc import Mapping
+
+    from altar.connections import Connection
+    from altar.predicates import Predicate
+
+
+class ConservationAnnotationSource(PositionScoreAnnotationSource):
+    """Annotate variants with one conservation track's score, from its published copy or an owned copy.
+
+    A subclass names its `track` and registers under `track.name`. Build it with `from_options`. The identity is the
+    track's contract with the dataset's release and genome build, so the published copy, a pulled copy and a copy
+    built with ``altar-conservation-build`` from the same upstream file declare one identity; ``indels="max"`` adds
+    ``+indels-max`` to the release. A track exists on one genome build, which a subclass declares as its
+    `supported_genome_builds`: phyloP 100-way is hg38, so materialization joins it only to hg38 variants, and on
+    another assembly a model's dependency on it reads as missing.
+    """
+
+    track: ClassVar[ConservationTrack]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Declare the subclass's track's genome build as the one assembly it serves."""
+        super().__init_subclass__(**kwargs)
+        track = cls.__dict__.get("track")
+        if track is not None:
+            cls.supported_genome_builds = frozenset({track.genome_build})
+
+    # The run driver passes `connection` only to a `from_options` that names it, so the options are explicit.
+    @classmethod
+    def from_options(  # noqa: PLR0913 - each run spec option is a keyword
+        cls,
+        *,
+        dataset: str | os.PathLike[str] | None = None,
+        location: str | None = None,
+        storage_options: Mapping[str, Any] | None = None,
+        connection: Connection | None = None,
+        indels: Literal["skip", "max"] = "skip",
+        genome_build: str | None = None,
+        name: str | None = None,
+        prioritize_predicate: Predicate | None = None,
+        **unknown: object,
+    ) -> Self:
+        """Build the source from run spec options, over the published copy or an owned Parquet copy.
+
+        - With no `dataset`, the source reads the published copy (`published_dataset()`) where it is hosted:
+          anonymously, or with `connection`'s or `storage_options`' options, from the primary ``gcs`` location
+          unless `location` names another, such as ``"hf"`` (which needs `altar[hf]`).
+        - `dataset` is an owned copy, as a path or a URI: one ``altar pull <track> --to <dir>`` made, or one
+          ``altar-conservation-build`` wrote. It is read with `connection`'s storage options for it, or with
+          `storage_options`.
+
+        `indels` is ``"skip"`` (SNVs only, the default) or ``"max"`` (every variant, by the greatest score over the
+        bases it touches; see `PositionScoreAnnotationSource`). `genome_build`, when given, must be the dataset's.
+        `name` renames the source, and `prioritize_predicate`, which a spec cannot spell, makes it gate
+        `prioritized` when built in code. The source reads no BigQuery table, so it takes neither `table` nor
+        `release`, which names a table's release. A `table` raises `ValueError` that says to pull the dataset
+        instead. An unknown `location` raises `ValueError` naming the published locations, and an option not named
+        here raises `ValueError` listing the valid ones.
+        """
+        if "table" in unknown:
+            msg = (
+                f"{cls.track.name} source option table={unknown['table']!r} names a BigQuery table, but BigQuery "
+                f"tables aren't supported yet; pull the dataset with `altar pull {cls.name} --to <dir>` and use "
+                "`dataset=`"
+            )
+            raise ValueError(msg)
+        if unknown:
+            raise ValueError(
+                unknown_options_message(cls.track.name, cls.from_options, unknown, code_only=_CODE_ONLY_OPTIONS)
+            )
+        published = cls.published_dataset()
+        if location is not None and dataset is None:
+            _check_location(cls, published, location)
+        copy = published.select_copy(
+            cls.track.name,
+            dataset=dataset,
+            storage_options=storage_options,
+            connection=connection,
+            location=location,
+        )
+        assert not isinstance(copy, OwnedTableCopy)  # noqa: S101 - no table was passed, so it is a Parquet copy
+        uri = copy.dataset if isinstance(copy, OwnedDatasetCopy) else copy.uri
+        source = cls.from_dataset(
+            uri,
+            contract=cls.track.contract,
+            indels=indels,
+            genome_build=genome_build,
+            storage_options=copy.storage_options,
+            prioritize_predicate=prioritize_predicate,
+            name=name,
+        )
+        if dataset is None:
+            try:
+                # Reuses the footer `from_dataset` just read: nothing more is fetched.
+                published.check_release(uri, storage_options=copy.storage_options, all_files=False)
+            except ValueError as error:
+                msg = (
+                    f"the published {cls.track.name} dataset at {uri} is not release {published.release!r} on "
+                    f"{published.genome_build!r}, which this altar-conservation version reads ({error}); upgrade "
+                    "altar-conservation, or name an owned dataset"
+                )
+                raise ValueError(msg) from error
+        return source
+
+    @classmethod
+    def published_dataset(cls) -> PublishedDataset:
+        """Return the track's published copy, which `from_options` reads by default."""
+        return cls.track.published
+
+    @classmethod
+    def annotation_contract(cls) -> AnnotationContract:
+        """Return the track's contract, which every instance implements, for ``altar sources``."""
+        return cls.track.contract
+
+
+class PhyloP100wayAnnotationSource(ConservationAnnotationSource):
+    """Evolutionary conservation at each variant's bases, from UCSC's hg38 phyloP 100-way scores.
+
+    Positive scores mark bases that evolved more slowly than neutral across 100 vertebrates, negative faster. The
+    track is `PHYLOP100WAY`, registered as ``phylop100way``.
+    """
+
+    name = "phylop100way"
+    track = PHYLOP100WAY
+
+
+_CODE_ONLY_OPTIONS = ("prioritize_predicate",)
+"""`from_options` keywords a run spec cannot spell, because their values are Python objects."""
+
+
+def _check_location(source: type[ConservationAnnotationSource], published: PublishedDataset, location: str) -> None:
+    """Raise `ValueError` naming the published locations when `location` is not one of them."""
+    names = [published_location.name for published_location in published.locations]
+    if location not in names:
+        msg = f"the published {source.track.name} dataset has no location {location!r}; name one of: {', '.join(names)}"
+        raise ValueError(msg)
+
+
+__all__ = ["ConservationAnnotationSource", "PhyloP100wayAnnotationSource"]

altar_conservation/tracks.py

@@ -0,0 +1,87 @@
+# Copyright 2026 Riya Sinha
+"""The conservation tracks the binding builds and the Kundaje lab publishes: one entry per published track.
+
+A track is one upstream bigWig on one genome build, the `AnnotationContract` its scores implement (one float
+column), and where its position score dataset (`altar.sources.POSITION_SCORE_METADATA`) is published. Adding a track
+is an entry here, a source subclass, an entry point, a build and a publish.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+
+from altar.sources import (
+    POSITION_SCORE_METADATA,
+    AnnotationColumn,
+    AnnotationContract,
+    PublishedDataset,
+    PublishedLocation,
+    position_score_release_fields,
+)
+
+
+@dataclass(frozen=True)
+class ConservationTrack:
+    """One published base-wise conservation track.
+
+    `contract` declares the track's one float column, whose name is also the track's name, its source's registry
+    name and its builder's ``--track``. `release` labels the upstream file (UCSC's file date, ``YYYY-MM``),
+    `upstream_url` is where the bigWig is downloaded from and `upstream_md5` the checksum its host publishes, which
+    the builder checks. `published` is where the Kundaje lab hosts the built dataset.
+    """
+
+    contract: AnnotationContract
+    genome_build: str
+    release: str
+    upstream_url: str
+    upstream_md5: str
+    published: PublishedDataset
+
+    @property
+    def name(self) -> str:
+        """The track's name: its contract's one column, such as ``phylop100way``."""
+        return self.contract.columns[0].name
+
+
+def _published(contract: AnnotationContract, *, release: str, genome_build: str, path: str) -> PublishedDataset:
+    """Return the published copy of a track: the lab's bucket first, mirrored on Hugging Face."""
+    return PublishedDataset(
+        locations=(
+            PublishedLocation("gcs", f"gs://kundajelab-altar/conservation/{path}"),
+            PublishedLocation("hf", f"hf://datasets/altar-genomics/{path}"),
+        ),
+        identity=contract.identity(release=release, genome_build=genome_build),
+        release_metadata=POSITION_SCORE_METADATA,
+        release_fields=position_score_release_fields(contract=contract, release=release, genome_build=genome_build),
+        # A score is read by position, not by variant ID.
+        cluster_by=("chr", "pos"),
+    )
+
+
+PHYLOP100WAY_ANNOTATIONS = AnnotationContract(
+    source_id="org.kundajelab.altar.annotation.phylop100way",
+    schema_version="1.0.0",
+    columns=(AnnotationColumn(name="phylop100way", dtype="float", label="phyloP 100-way"),),
+)
+"""The phyloP 100-way annotation contract: one float column, ``phylop100way``.
+
+The value is UCSC's phyloP score over the 100-vertebrate alignment at the variant's base: a base-wise
+-log10 p-value of conservation (positive, slower evolution than neutral) or acceleration (negative, faster), from
+about -20 to 10. A source scoring indels takes the greatest score over the bases the variant touches. A contract
+names no genome build, so an hg19 copy would implement it too, under another identity.
+"""
+
+PHYLOP100WAY = ConservationTrack(
+    contract=PHYLOP100WAY_ANNOTATIONS,
+    genome_build="hg38",
+    release="2015-05",
+    upstream_url="https://hgdownload.soe.ucsc.edu/goldenPath/hg38/phyloP100way/hg38.phyloP100way.bw",
+    upstream_md5="43858006bdf98145b6fd239490bd0478",
+    published=_published(PHYLOP100WAY_ANNOTATIONS, release="2015-05", genome_build="hg38", path="phylop100way-hg38"),
+)
+"""UCSC hg38 phyloP 100-way (``hg38.phyloP100way.bw``, May 2015), published as ``phylop100way-hg38``."""
+
+TRACKS: dict[str, ConservationTrack] = {track.name: track for track in (PHYLOP100WAY,)}
+"""Every published track by name, as the builder's ``--track`` names it."""
+
+
+__all__ = ["PHYLOP100WAY", "PHYLOP100WAY_ANNOTATIONS", "TRACKS", "ConservationTrack"]

altar_conservation-0.3.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: altar-conservation
+Version: 0.3.0
+Summary: Base-wise conservation score tracks (UCSC phyloP) for Altar
+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[gcs]<0.4,>=0.3.0
+Provides-Extra: build
+Requires-Dist: pybigtools>=0.3.0; extra == 'build'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# altar-conservation
+
+This binding adds base-wise conservation scores to variants. Its one track today is UCSC's hg38 phyloP 100-way
+(`hg38.phyloP100way.bw`, May 2015): `phylop100way`, an annotation source (`PhyloP100wayAnnotationSource`), adds a
+`phylop100way` column, the phyloP score at the variant's base, from a Parquet copy of the track: the one the
+Kundaje lab publishes, or one you own. phyloP is a signed -log10 p-value: positive where a base evolves more slowly
+than neutral across 100 vertebrates (conserved), negative where it evolves faster.
+
+## Annotate variants from the published copy
+
+The Kundaje lab publishes the track in Altar's position score layout (`PHYLOP100WAY.published`):
+
+| Location | URI |
+| --- | --- |
+| `gcs` (default) | `gs://kundajelab-altar/conservation/phylop100way-hg38` |
+| `hf` | `hf://datasets/altar-genomics/phylop100way-hg38` ([dataset card](https://huggingface.co/datasets/altar-genomics/phylop100way-hg38)) |
+
+A run spec reads it with no options; the package depends on `altar[gcs]`, and the `hf` mirror needs `altar[hf]`:
+
+```toml
+[sources.phylop]
+type = "phylop100way"
+```
+
+Hugging Face limits anonymous requests, so a large cohort read with `location = "hf"` can stall; read the bucket, or
+pull a copy and name it with `dataset` ([published locations](https://kundajelab.github.io/altar/guides/published-datasets/#published-locations)).
+
+In Python:
+
+```python
+import asyncio
+
+from altar_conservation import PhyloP100wayAnnotationSource
+
+source = PhyloP100wayAnnotationSource.from_options()  # the published copy
+rows = asyncio.run(source.annotate(["chr7:140753336:A:T"]))
+rows["chr7:140753336:A:T"]["phylop100way"]  # 9.236
+```
+
+The contract is `org.kundajelab.altar.annotation.phylop100way` (version 1.0.0, `PHYLOP100WAY_ANNOTATIONS`), one
+float column `phylop100way`. The copy holds 2,837,915,604 scored bases of chr1–22, X, Y and M; a variant at an
+unscored base, or on any other contig (alternate, unlocalized or unplaced), has no row.
+
+`altar pull phylop100way --to <dir>` copies the published dataset (5.0 GB), checking each file's release; name the
+copy with `dataset`. The options:
+
+| Option | Meaning |
+| --- | --- |
+| `dataset` | An owned copy, as a path or a URI: a pulled copy, or one built with the builder below. |
+| `location` | `gcs` (default) or `hf`, for the published copy. |
+| `connection`, `storage_options` | How to reach a bucket. |
+| `indels` | `skip` (default) scores SNVs only; `max` scores every variant (below). |
+| `name` | Rename the source. |
+| `genome_build` | Optional; must be `hg38`. |
+| `prioritize_predicate` | In code only: a predicate over `phylop100way` that gates `prioritized`. |
+
+`table` is not read yet: BigQuery would scan the 2.8-billion-row table for every chunk of variants, so the source
+refuses it, before any other option, and asks for a pulled copy. An unknown option or `location` raises a
+`ValueError` that lists the valid ones.
+
+The track is on hg38 only. `altar run` stops before ingesting anything when the spec's `[run] genome_build` is
+another assembly, naming the source.
+
+With `indels = "max"`, a variant that is not an SNV is scored by the greatest score over the bases it touches, as
+VEP takes them: a deletion's deleted bases (after the padding base), the two bases an insertion falls between, or
+any other change's REF span. Unscored bases are ignored; a variant with none scored has no row. SNVs score the same
+either way. The identity is the contract with release `2015-05` and `hg38`; with `indels = "max"` the release is
+`2015-05+indels-max`, since it scores variants the default leaves out.
+
+## Build the dataset
+
+```console
+pip install "altar-conservation[build]"
+curl -O https://hgdownload.soe.ucsc.edu/goldenPath/hg38/phyloP100way/hg38.phyloP100way.bw
+altar-conservation-build --track phylop100way --input hg38.phyloP100way.bw --output /scratch/phylop100way-hg38
+```
+
+The `build` extra installs [pybigtools](https://github.com/jackh726/bigtools), which has wheels for Linux and
+macOS. The builder checks the file's MD5 against UCSC's `md5sum.txt`, then converts each primary contig in its own
+process (`--workers`, default one per contig up to the CPU count): it reads the contig's records, turns UCSC's 0-based
+intervals into one row per base with a 1-based `pos`, checks that positions strictly increase, and writes
+`chr=<contig>/scores.parquet` with `PartitionedWriter` in 128,000-row groups, `pos` delta-encoded, with the track,
+release and genome build in every footer. Other contigs are skipped. On a 64-core server the build took 72 s
+(15 s of it the MD5) and about 14 GB of memory across 25 processes, about 0.7 GB each. The output is a local
+directory; copy it to a bucket yourself.
+
+## Data terms and citation
+
+UCSC's phyloP files are "freely available for public use"; UCSC asks you to credit the data and cite the Genome
+Browser. Please cite:
+
+- Pollard KS, Hubisz MJ, Rosenbloom KR, Siepel A. Detection of nonneutral substitution rates on mammalian phylogenies. *Genome
+  Research* 2010;20(1):110–121. doi:10.1101/gr.097857.109.
+- Siepel A, et al. Evolutionarily conserved elements in vertebrate, insect, worm, and yeast genomes. *Genome
+  Research* 2005;15(8):1034–1050. doi:10.1101/gr.3715005.
+- The UCSC Genome Browser's latest database paper (<https://genome.ucsc.edu/cite.html>): Casper J, et al.
+  *Nucleic Acids Research* 2026. PMID 41251146.
+
+[Cite these data](https://kundajelab.github.io/altar/integrations/evidence/#cite-these-data) lists these with the
+other datasets Altar publishes.
+
+The binding ships no data. Its contract is its own; the source and layout come from `altar`, and the binding is
+tested against Altar's conformance suites.

altar_conservation-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+altar_conservation/__init__.py,sha256=mZFg8fFPXfd985kJrv-_0Kntxf9Cuzn82Bf4K1IeiXk,510
+altar_conservation/build_dataset.py,sha256=ioXyf8VaKJzohOZc_MsdM_NKTT62MG51rTsFXQs7uE8,13217
+altar_conservation/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+altar_conservation/source.py,sha256=p6KT7ajBG0bDnwNGCvjVT27-BlHl7XoEE5AjcRaQUUQ,7885
+altar_conservation/tracks.py,sha256=jce7ElYRWq_L89PgB21-1p-EveWZAeBWyGpsBRP4sDw,3823
+altar_conservation-0.3.0.dist-info/METADATA,sha256=c-Ef6Z-fAlDYypFvWjVUN2C8O7Z2KPvtRkiFGjfkUGs,6630
+altar_conservation-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+altar_conservation-0.3.0.dist-info/entry_points.txt,sha256=19Rg6OFs2NBf-EvtAAFV1CYDnAE7jbxAySUvlNvLvMc,174
+altar_conservation-0.3.0.dist-info/licenses/LICENSE,sha256=WXdDrQ5KT8NmZrPwFTmbpTbvtOUy9dCL9er44qckaj0,1067
+altar_conservation-0.3.0.dist-info/RECORD,,

altar_conservation-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

altar_conservation-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+altar-conservation-build = altar_conservation.build_dataset:main
+
+[altar.annotation_sources]
+phylop100way = altar_conservation:PhyloP100wayAnnotationSource

altar_conservation-0.3.0.dist-info/licenses/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.