ProtSpace
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, 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: 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/.
🚀 Google Colab Notebooks
Note: Use Chrome or Firefox for best experience.
-
Generate Protein Embeddings:
-
Prepare ProtSpace Bundle:
-
Transfer Annotations (EAT):
📦 Installation
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/--similarityused to work out of the box because MMseqs2 shipped in the base install. It now lives in thesimilarityextra, so addpip 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
# 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 — it is read locally in your browser.
3. Power-user workflow (individual steps)
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.
Fill missing annotation values from the nearest annotated protein in embedding space with protspace transfer — Embedding Annotation Transfer (EAT).
Bundles in the older v1/v2 format still open, but that support ends in protspace 5.0.0. Upgrade them with protspace convert old.parquetbundle new.parquetbundle (or --in-place).
📊 Example Output
✨ 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.
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:
- CLI Reference — commands, options, method parameters
- Annotation Reference — every annotation, its group, data source, and output format
- Annotation Styling — custom colors, shapes, sort modes, and the
--generate-templateworkflow - Bundle Format — what is inside a
.parquetbundle
🧩 Where this fits
protspace is the data-preparation half of ProtSpace. It lives in the
protspace monorepo alongside the web explorer:
| Piece | What it does |
|---|---|
protspace (this package, apps/protspace/) |
Embed, project, annotate, bundle — produces .parquetbundle |
Web explorer (apps/web/) |
Opens a .parquetbundle at protspace.app/explore |
Issues and pull requests for both go to github.com/tsenoner/protspace.
📝 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
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
1 maintainer
Metadata
1 maintainer
Release files for protspace 4.16.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| protspace-4.16.4.tar.gz | 13.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| protspace-4.16.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 14.2 MB
Release files / protspace-4.16.4.tar.gz
| Download URL | protspace-4.16.4.tar.gz |
|---|---|
| Size | 13.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
be6e7791a0b3d6eab05ea4b49f66a6bd067af61482bac3c96f681c8c14b71aae
|
|
BLAKE2b-256 checksum How to use checksums |
bd9a1ae9da36f6adafe41bd9d6942d7b24649510d1bd0cdc2718ffe33ea96bef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / protspace-4.16.4-py3-none-any.whl
| Download URL | protspace-4.16.4-py3-none-any.whl |
|---|---|
| Size | 838.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bab55cfbd2aa4c04f3e61c7065f90500711f5d4e3d402ba0cc231aba3f7624ac
|
|
BLAKE2b-256 checksum How to use checksums |
364b3aa8b6a87a089ce415ea101ba18f188f5f59e43ca8ae63a226beb5e53311
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency log
