altar-conservation 0.3.0__tar.gz

altar_conservation-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_conservation-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_conservation-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,103 @@
+# 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/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-0.3.0/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()