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.
