Metadata-Version: 2.5
Name: uupmap
Version: 0.0.3
Summary: Reader for UniWeave, a residue-level UniProt-to-UniProt mapping resource
Project-URL: Dataset, https://huggingface.co/datasets/ioChris/uniweave
Author: The UniWeave Authors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: alphafold,bioinformatics,protein structure,residue mapping,uniprot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: polars>=1.0
Description-Content-Type: text/markdown

# uupmap

`uupmap` reads [UniWeave](https://huggingface.co/datasets/ioChris/uniweave), a residue-level
UniProt-to-UniProt mapping resource. Every edge links two UniProt accessions by sequence
(MMseqs2) and/or structural (FoldSeek TM-align, ProstT5 3Di) similarity and carries the residue
correspondence between them, so a residue index in one protein can be carried over to its
counterpart in another.

This package is the reader only: it opens the published Parquet files and answers queries. It
depends on [Polars](https://pola.rs) and nothing else.

## Install

```bash
pip install uupmap
```

## Get the data

The artifacts are on Hugging Face (CC-BY-4.0). Each weekly release is tagged with its
`data_version`, so a release can be pinned with `revision=`:

```python
from pathlib import Path
from huggingface_hub import snapshot_download   # pip install huggingface_hub

d = Path(snapshot_download("ioChris/uniweave", repo_type="dataset"))
```

The release is about 0.4 GB: `edges.parquet`, `uniprots.parquet`, `sifts.parquet`,
`model_frames.parquet`, `stats.json` and `dataset_manifest.json`.

## Query

```python
from uupmap import UUPMap

m = UUPMap(d / "edges.parquet", d / "uniprots.parquet",
           model_frames_path=d / "model_frames.parquet")

# UniProt neighbours of a protein. Thresholds default to 1.0, so pass the ones you want.
for n in m.neighbors("P69905", seq_id_min=0.3, tm_min=0.5):
    print(n.unp_b, n.seq_identity, n.tm_score)

# Carry residue 87 of P69905 over to its neighbours.
for hit in m.expand_indices([("P69905", 87)], seq_id_min=0.3, tm_min=0.5):
    print(hit.unp_b, hit.idx_b, hit.cigar_source)

# Scores and channels behind one pair.
print(m.provenance("P69905", "P68871"))
```

`neighbors` and `expand_indices` accept `min_cov`, `min_plddt`, `require_both` (sequence and
structure must both pass) and `di_bits_per_res_min` (admits ProstT5 3Di edges, off by default).

### AlphaFold-DB residue numbering

Residue maps are in current UniProt numbering. An AlphaFold-DB model can be numbered against an
older version of its UniProt entry; `model_frames.parquet` records the correspondence, and
`m.unp_to_model(acc, positions)` / `m.model_to_unp(acc, residues)` translate lists of numbers
between the two for tools that open the model files themselves (`m.model_frame(acc)` is `None`
for an accession with no AFDB model checked). A frame describes one model file: before mapping
through a model you downloaded yourself, check that `uupmap.residue_frame.crc64(sequence)` of its
modelled sequence equals the frame's `model_crc64`.

## Version contract

Each release states which readers can read it. From the releases that carry them,
`dataset_manifest.json` has `uupmap_version` (the reader that built it), `artifact_format` and
`min_uupmap_version` in its `software` block. The installed package exposes the matching
constants:

```python
import json, uupmap

software = json.loads((d / "dataset_manifest.json").read_text())["software"]
print(uupmap.__version__, uupmap.ARTIFACT_FORMAT, uupmap.MIN_READER_VERSION)
print(software.get("min_uupmap_version"), software.get("artifact_format"))
```

Below 0.0.2, a coverage floor silently dropped the structure-only edges, most of the graph.
Use 0.0.2 or later.

## Licence

The code is Apache-2.0 (see `LICENSE` and `NOTICE`). The UniWeave data is CC-BY-4.0. A preprint
describing UniWeave is in preparation.
