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 13, 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 13, 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.2.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.2-py3-none-any.whl (770.1 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: protspace-4.11.2.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.2.tar.gz
Algorithm Hash digest
SHA256 3a042ba8181a0b2290ed148d2b4044c9fd201bda7c33dbbce500053dfc8fc59a
MD5 478a0f89d499dd6d1f4a239a6897d2fa
BLAKE2b-256 bb752882975d88c1186421d5411a46aea58e1ec9aa59a76ab9df634b9ca4eb31

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: protspace-4.11.2-py3-none-any.whl
  • Upload date:
  • Size: 770.1 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.2-py3-none-any.whl
Algorithm Hash digest
SHA256 3dc4f11e63bb170667a349e4bc52a22ae4ea7bddaed965e7c2e1ec76d9200b2f
MD5 e844f5c0adec2ccb7cfb8279f04aea3b
BLAKE2b-256 546a3b27134d1d193fddbad421ee0caf9872b505b4125d3a1a40baa0488e18dc

See more details on using hashes here.

Provenance

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

This release

4.11.2 This release

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