Metadata-Version: 2.5
Name: protspace
Version: 4.12.0
Summary: Prepare protein language model (pLM) embeddings for interactive exploration at protspace.app — embed, project, annotate, transfer labels (EAT), and bundle.
Project-URL: Homepage, https://protspace.app
Project-URL: Repository, https://github.com/tsenoner/protspace
Project-URL: Documentation, https://protspace.app/docs/
Project-URL: Issues, https://github.com/tsenoner/protspace/issues
Project-URL: Changelog, https://github.com/tsenoner/protspace/blob/main/apps/protspace/CHANGELOG.md
Author-email: Tobias Senoner <tobias.senoner@tum.de>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: biocentral-api>=1.2.1
Requires-Dist: h5py>=3.12.1
Requires-Dist: numpy>=1.23.0
Requires-Dist: pacmap>=0.8.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: protlabel>=4.4.0
Requires-Dist: pyarrow>=20.0.0
Requires-Dist: requests>=2.32.4
Requires-Dist: rich>=13.8.0
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: typer>=0.24.1
Requires-Dist: umap-learn>=0.5.10
Provides-Extra: frontend
Requires-Dist: dash-bootstrap-components>=1.6.0; extra == 'frontend'
Requires-Dist: dash-daq>=0.5.0; extra == 'frontend'
Requires-Dist: dash-iconify>=0.1.2; extra == 'frontend'
Requires-Dist: dash-molstar>=1.3.0; extra == 'frontend'
Requires-Dist: dash>=3; extra == 'frontend'
Requires-Dist: kaleido!=0.2.1.post1,>=0.2.1; extra == 'frontend'
Requires-Dist: plotly>=5.24.1; extra == 'frontend'
Provides-Extra: local
Requires-Dist: einops>=0.8.2; extra == 'local'
Requires-Dist: protobuf>=3.20; extra == 'local'
Requires-Dist: sentencepiece>=0.2.2; extra == 'local'
Requires-Dist: torch>=2.4; extra == 'local'
Requires-Dist: transformers>=5.13.1; extra == 'local'
Provides-Extra: similarity
Requires-Dist: pymmseqs>=1.2.0; extra == 'similarity'
Description-Content-Type: text/markdown

# ProtSpace

[![PyPI version](https://badge.fury.io/py/protspace.svg)](https://badge.fury.io/py/protspace)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://pepy.tech/badge/protspace)](https://pepy.tech/project/protspace)
[![DOI (preprint)](https://img.shields.io/badge/bioRxiv-10.64898%2F2026.05.04.722720-b31b1b)](https://doi.org/10.64898/2026.05.04.722720)
[![DOI (JMB)](https://img.shields.io/badge/DOI-10.1016%2Fj.jmb.2025.168940-blue)](https://doi.org/10.1016/j.jmb.2025.168940)

ProtSpace maps the **embedding space** of protein language models (pLMs) to reveal relationships that sequence similarity misses. This Python package **prepares** your data — embed sequences, project to 2D, overlay biological annotations (UniProt, InterPro, AlphaFold/TED, ML predictions), and transfer labels from the nearest neighbour in embedding space (EAT) — then bundles everything into a `.parquetbundle` you explore interactively at [protspace.app](https://protspace.app), nothing uploaded. Similarity matrices are supported as input too.

- **Multiple projections**: linear and non-linear dimensionality reduction (PCA, UMAP, t-SNE, and more)
- **Automatic annotations**: UniProt, InterPro, Taxonomy, TED domains, and Biocentral predictions
- **Quality metrics** _(opt-in)_: annotation-based cluster-validity + faithfulness (local & global) via `--stats`
- **Annotation transfer** _(EAT)_: fill missing annotations from the nearest reference proteins in embedding space via `protspace transfer`
- **Structure viewer**: Integrated protein structure visualization
- **Export**: PNG, PDF, SVG, HTML

## 🌐 Try Online

**[ProtSpace web app](https://protspace.app/explore)**: fast 2D explorer optimized for large datasets — drag & drop the `.parquetbundle` this package produces and it is parsed in your browser, nothing uploaded. Small FASTA files can also be dropped directly and prepared for you. Source lives in the same repo under [`apps/web/`](https://github.com/tsenoner/protspace/tree/main/apps/web).

## 🚀 Google Colab Notebooks

**Note**: Use Chrome or Firefox for best experience.

1. **Generate Protein Embeddings**: [![Open Embeddings In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tsenoner/protspace/blob/main/apps/protspace/notebooks/ClickThrough_GenerateEmbeddings.ipynb)

2. **Prepare ProtSpace Bundle**: [![Open Preparation In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tsenoner/protspace/blob/main/apps/protspace/notebooks/ProtSpace_Preparation.ipynb)

3. **Transfer Annotations (EAT)**: [![Open Transfer In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tsenoner/protspace/blob/main/apps/protspace/notebooks/ProtSpace_Transfer.ipynb)


## 📦 Installation

```bash
pip install protspace
```

**Optional extras**

| Extra | Install | Needed for |
| --- | --- | --- |
| `local` | `pip install "protspace[local]"` | on-device embedding (`--backend local`) instead of the Biocentral API |
| `similarity` | `pip install "protspace[similarity]"` | MMseqs2 sequence-similarity projections (`-s/--similarity`) |
| `frontend` | `pip install "protspace[frontend]"` | the local Dash viewer (`protspace serve`) |

> **Upgrading an existing install:** `-s/--similarity` used to work out of the box because
> MMseqs2 shipped in the base install. It now lives in the `similarity` extra, so add
> `pip install "protspace[similarity]"` if you use that flag. Nothing else changes: the base
> install got smaller, and on macOS and Linux the extra installs from a prebuilt wheel
> rather than compiling from source.

## 🎯 Quick Start

### 1. Prepare data

```bash
# From HDF5 embeddings
protspace prepare -i embeddings.h5 -m pca2,umap2 -o output

# From FASTA (auto-embeds via Biocentral API)
protspace prepare -i sequences.fasta -e prot_t5 -m pca2 -o output

# Multi-model comparison (compare across pLMs)
protspace prepare -i sequences.fasta -e prot_t5,esm2_650m,ankh_base -m pca2,umap2 -o output

# Combine datasets (same embedding name → proteins are unioned)
protspace prepare -i species_a.h5:prot_t5 -i species_b.h5:prot_t5 -m umap2 -o output
```

### 2. Explore results

Open the generated `.parquetbundle` at [protspace.app/explore](https://protspace.app/explore) — it is read locally in your browser.

### 3. Power-user workflow (individual steps)

```bash
protspace embed -i sequences.fasta -e prot_t5 -e esm2_3b -o embeddings/
protspace project -i embeddings/prot_t5.h5 -i embeddings/esm2_3b.h5 -m pca2,umap2 -o projections/
protspace annotate -i embeddings/prot_t5.h5 -a default -o annotations.parquet
protspace stats -i embeddings/prot_t5.h5 -p projections/ -o statistics.parquet   # optional: quality metrics
protspace bundle -p projections/ -a annotations.parquet -s statistics.parquet -o output.parquetbundle
protspace transfer -b output.parquetbundle -e embeddings/prot_t5.h5 -t superfamily -o transferred.parquetbundle   # optional: fill gaps via EAT
```

Or compute quality metrics inline during `prepare` with `--stats` (opt-in): annotation-based cluster-validity + faithfulness per projection. See the [CLI Reference](https://protspace.app/docs/guide/python-cli).

Fill missing annotation values from the nearest annotated protein in embedding space with [`protspace transfer`](https://protspace.app/docs/guide/python-cli) — Embedding Annotation Transfer (EAT).

## 📊 Example Output

![2D Example](https://raw.githubusercontent.com/tsenoner/protspace/main/apps/protspace/docs/protspace_example.png)

## ✨ Annotations

Use `-a` to color-code proteins by UniProt, InterPro, Taxonomy, TED domain, and Biocentral prediction annotations. Groups (`default`, `all`, `uniprot`, `interpro`, `taxonomy`, `ted`, `biocentral`) and individual names can be mixed freely. If `-a` is omitted, the `default` group is used.

```bash
protspace prepare -i data.h5 -m pca2                              # default annotations
protspace prepare -i data.h5 -a default,interpro,kingdom -m pca2  # mix groups + individual
```

## 📖 Documentation

Full documentation lives at **[protspace.app/docs](https://protspace.app/docs/)**:

- [CLI Reference](https://protspace.app/docs/guide/python-cli) — commands, options, method parameters
- [Annotation Reference](https://protspace.app/docs/guide/annotations) — every annotation, its group, data source, and output format
- [Annotation Styling](https://protspace.app/docs/guide/styling) — custom colors, shapes, sort modes, and the `--generate-template` workflow
- [Bundle Format](https://protspace.app/docs/guide/data-format) — what is inside a `.parquetbundle`

## 🧩 Where this fits

`protspace` is the data-preparation half of ProtSpace. It lives in the
[protspace monorepo](https://github.com/tsenoner/protspace) alongside the web explorer:

| Piece                                                                                | What it does                                                    |
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| **`protspace`** (this package, [`apps/protspace/`](https://github.com/tsenoner/protspace/tree/main/apps/protspace)) | Embed, project, annotate, bundle — produces `.parquetbundle`     |
| **Web explorer** ([`apps/web/`](https://github.com/tsenoner/protspace/tree/main/apps/web))                          | Opens a `.parquetbundle` at [protspace.app/explore](https://protspace.app/explore) |

Issues and pull requests for both go to
[github.com/tsenoner/protspace](https://github.com/tsenoner/protspace/issues).

## 📝 Citation

If you use ProtSpace, please cite the web application preprint (latest):

Senoner T, Vahidi P, Olenyi T, Senoner F, Sisman G, Kahl E, Rost B, Koludarov I. ProtSpace: Protein Universe in Your Browser. *bioRxiv*, 2026. [doi:10.64898/2026.05.04.722720](https://doi.org/10.64898/2026.05.04.722720)

The original, peer-reviewed ProtSpace publication:

Senoner T, Olenyi T, Heinzinger M, Spannagl A, Bouras G, Rost B, Koludarov I. ProtSpace: A Tool for Visualizing Protein Space. *Journal of Molecular Biology*, 437(15), 168940, 2025. [doi:10.1016/j.jmb.2025.168940](https://doi.org/10.1016/j.jmb.2025.168940)
