ProtSpace

PyPI version Python 3.10+ License: MIT Downloads DOI (preprint) DOI (JMB)

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.

  1. Generate Protein Embeddings: Open Embeddings In Colab

  2. Prepare ProtSpace Bundle: Open Preparation In Colab

  3. Transfer Annotations (EAT): Open Transfer In Colab

📦 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/--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

# 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).

📊 Example Output

2D Example

✨ 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:

🧩 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

Project links

Data verified by PyPI on Aug 19, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (4.12.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for tsenoner from gravatar.com tsenoner

Credits

Author: Tobias Senoner

GitHub Statistics

Data verified by PyPI on Aug 19, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.12

Provides Extra

frontend local similarity

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

protspace-4.11.3.tar.gz (13.3 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

protspace-4.11.3-py3-none-any.whl (771.0 kB view details)

Uploaded Python 3

File details

Details for the file protspace-4.11.3.tar.gz.

File metadata

  • Download URL: protspace-4.11.3.tar.gz
  • Upload date:
  • Size: 13.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for protspace-4.11.3.tar.gz
Algorithm Hash digest
SHA256 7d90cf96d77d66894e79c84ea1c661968de1ef489bd0c438b4df19fe027a750f
MD5 664ce0e3bf1eeb5a02778ed919b8e035
BLAKE2b-256 2b031346e95e3e8880852fb32aa580333a3760d708ebd21947eae45b917e2dae

See more details on using hashes here.

Provenance

The following attestation bundles were made for protspace-4.11.3.tar.gz:

Publisher: protspace-publish.yml on tsenoner/protspace

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file protspace-4.11.3-py3-none-any.whl.

File metadata

  • Download URL: protspace-4.11.3-py3-none-any.whl
  • Upload date:
  • Size: 771.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for protspace-4.11.3-py3-none-any.whl
Algorithm Hash digest
SHA256 eb0faa1edc6d3217eaa51d154bf2833f336da295f03f90b24eede7ae1fa28a04
MD5 454957e8da067e8b100579249093aaf4
BLAKE2b-256 442c6b5b4cf26e2638d81687d731a0cb6313ffdeb63fee93d6efc669c5e39ffe

See more details on using hashes here.

Provenance

The following attestation bundles were made for protspace-4.11.3-py3-none-any.whl:

Publisher: protspace-publish.yml on tsenoner/protspace

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

4.12.0

2 files

This release

4.11.3 This release

2 files

4.11.2

2 files

4.11.1

2 files

4.11.0

2 files

4.10.3

2 files

4.10.2

2 files

4.10.1

2 files

4.10.0

2 files

4.9.1

2 files

4.9.0

2 files

4.8.2

2 files

4.8.1

2 files

4.8.0

2 files

4.7.2

2 files

4.7.1

2 files

4.7.0

2 files

4.6.0

2 files

4.5.0

2 files

4.4.0

2 files

4.3.1

2 files

4.3.0

2 files

4.2.0

2 files

4.1.0

2 files

4.0.2

2 files

4.0.1

2 files

4.0.0

2 files

3.3.1

2 files

3.3.0

2 files

3.2.0

2 files

3.1.1

2 files

3.1.0

2 files

3.0.0

2 files

2.3.0

2 files

2.2.0

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.1

2 files

2.0.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.8

2 files

1.1.7

2 files

1.1.6

2 files

1.1.5

2 files

1.1.4

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

0.14.9

2 files

0.14.8

2 files

0.14.7

2 files

0.14.6

2 files

0.14.5

2 files

0.14.4

2 files

0.14.3

2 files

0.14.2

2 files

0.14.1

2 files

0.14.0

2 files

0.13.0

2 files

0.12.0

2 files

0.11.1

2 files

0.11.0

2 files

0.10.6

2 files

0.10.5

2 files

0.10.4

2 files

0.10.3

2 files

0.9.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page