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:
Latest release

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.12.0.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.12.0-py3-none-any.whl (774.1 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: protspace-4.12.0.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.12.0.tar.gz
Algorithm Hash digest
SHA256 54fbd596dc7980962598746d43ba51039bb1d94f376eb34a4be75a3d0aa9a9c1
MD5 40806da63a28046b65e740a4e225ddbc
BLAKE2b-256 ccd258af428566d9c848d391f125bf0c42f736c238a6d68f8e1d8bf13342b1ac

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: protspace-4.12.0-py3-none-any.whl
  • Upload date:
  • Size: 774.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.12.0-py3-none-any.whl
Algorithm Hash digest
SHA256 0ebd14dbbcaf3f0248bd150f698b6f7b227112d38ef4446d11ec52a5ea05744f
MD5 1d71375515151ce46ff2d6a00b9bae68
BLAKE2b-256 bd37f22edaa6d27b714ee8b5d1f5b7818c577ed77c14fd123fac4b20713b72ff

See more details on using hashes here.

Provenance

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

This release

4.12.0 This release

2 files

4.11.3

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