protspace 2.2.0

A visualisation tool for protein embeddings from pLMs

ProtSpace

ProtSpace is a visualization tool for exploring protein embeddings or similarity matrices along their 3D protein structures. It allows users to interactively visualize high-dimensional protein language model data in 2D or 3D space, color-code proteins based on various features, and view protein structures when available.

🌐 Try Online

Web Interface: https://protspace.rostlab.org/

🚀 Quick Start with Google Colab

Note: Use Chrome or Firefox for best experience.

1. Explore Pre-computed Visualizations:

2. Generate Protein Embeddings:

3. Full Pipeline Demo:

4. Pfam & Clan Explorer:

📦 Installation

# Basic installation (backend - dimensionality reduction only)
pip install protspace

# Full installation (backend + frontend - including visualization interface)
pip install "protspace[frontend]"

🎯 Usage

1. Query UniProt directly

# Search and analyze proteins from UniProt with available protein features
protspace-query -q "insulin AND organism_id:9606 AND reviewed:true" -o output_dir -m pca2,umap3

2. Process local data

# Process your own embeddings or similarity matrices with the protein features you want
protspace-local -i embeddings.h5 -f signal_peptide,pfam -o output_dir -m pca2,pca3

3. Launch visualization

# Auto-detects JSON files or Arrow directories
protspace output_dir
protspace output.json

Access at http://localhost:8050

✨ Features

• Interactive visualization: 2D/3D plots with multiple dimensionality reduction methods (PCA, UMAP, t-SNE, MDS, PaCMAP)
• Feature-based styling: Color-code and shape proteins by various features
• Structure integration: View 3D protein structures alongside embeddings
• Search & highlight: Find and highlight specific proteins
• Export options: High-quality SVG (2D) and interactive HTML (3D)
• Responsive interface: Works on desktop and mobile

📊 Example Outputs

2D Scatter Plot

3D Interactive Plot

View 3D Example

🔧 Advanced Usage

Command Options

protspace-query (UniProt search):

• -q, --query: UniProt search query (required)
• -o, --output: Output directory (required)
• -f, --features: Features to extract (comma-separated)
• -m, --methods: Reduction methods (e.g., pca2,umap3,tsne2)
• --non-binary: Use legacy JSON format
• --keep-tmp: Keep temporary files

protspace-local (Local data):

• -i, --input: HDF5 embeddings or CSV similarity matrix (required)
• -o, --output: Output directory (required)
• -f, --features: Features to extract (comma-separated) (legacy usage: csv metadata file path)
• -m, --methods: Reduction methods (e.g., pca2,umap3,tsne2)
• --non-binary: Use legacy JSON format

Method Parameters

Fine-tune dimensionality reduction:

• UMAP: --n_neighbors 15 --min_dist 0.1
• t-SNE: --perplexity 30 --learning_rate 200
• PaCMAP: --mn_ratio 0.5 --fp_ratio 2.0
• MDS: --n_init 4 --max_iter 300 --eps 1e-3

Custom Styling

protspace-feature-colors input.json output.json --feature_styles '{
  "feature_name": {
    "colors": {"value1": "#FF0000", "value2": "#00FF00"},
    "shapes": {"value1": "circle", "value2": "square"}
  }
}'

Available shapes: circle, circle-open, cross, diamond, diamond-open, square, square-open, x

📁 File Formats

Input

• UniProt queries: Text queries using UniProt syntax
• Embeddings: HDF5 files (.h5, .hdf5)
• Similarity matrices: CSV files with symmetric matrices
• Metadata: CSV with 'identifier' column + feature columns
• Structures: ZIP files containing PDB/CIF files

Output

• Default: Parquet files (projections_data.parquet, projections_metadata.parquet, selected_features.parquet)
• Legacy: JSON format with --non-binary flag
• Temporary files: FASTA sequences, similarity matrices, all features (with --keep-tmp)

📝 Citation

@article{SENONER2025168940,
title = {ProtSpace: A Tool for Visualizing Protein Space},
journal = {Journal of Molecular Biology},
pages = {168940},
year = {2025},
issn = {0022-2836},
doi = {https://doi.org/10.1016/j.jmb.2025.168940},
url = {https://www.sciencedirect.com/science/article/pii/S0022283625000063},
author = {Tobias Senoner and Tobias Olenyi and Michael Heinzinger and Anton Spannagl and George Bouras and Burkhard Rost and Ivan Koludarov}
}