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 no longer compiles MMseqs2 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 12, 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 12, 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.1.tar.gz (13.4 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.1-py3-none-any.whl (769.6 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: protspace-4.11.1.tar.gz
  • Upload date:
  • Size: 13.4 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.1.tar.gz
Algorithm Hash digest
SHA256 4a6482277477d81d84730b70fb65fdf5b34924e0125670731f0de7125c0e56b1
MD5 eae73bbb1a8cb55a49430bff369860ca
BLAKE2b-256 ccb0506dd0535f72f1f79c806feb833216f3f9ba99f07c750d1a73578410e42f

See more details on using hashes here.

Provenance

The following attestation bundles were made for protspace-4.11.1.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.1-py3-none-any.whl.

File metadata

  • Download URL: protspace-4.11.1-py3-none-any.whl
  • Upload date:
  • Size: 769.6 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.1-py3-none-any.whl
Algorithm Hash digest
SHA256 e71ba27311117a6ef569f6fade21c19a08f23859626879e9947e2c24c3b6a910
MD5 b0d4fa96938e9b6e429cf3f09a547244
BLAKE2b-256 e9a131da564a0e93099e44fbd2c4bb98ce1057761256cf7493bd39e168884c6d

See more details on using hashes here.

Provenance

The following attestation bundles were made for protspace-4.11.1-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

4.11.3

2 files

4.11.2

2 files

This release

4.11.1 This release

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