Using Google Colab

The easiest way to prepare your data for ProtSpace - no local installation required!

Overview

The Colab notebook converts protein embeddings into a visualization-ready .parquetbundle file:

1. Reads your embeddings from an HDF5 file (.h5)
2. Applies dimensionality reduction (PCA, UMAP, t-SNE, PaCMAP, MDS, LocalMAP)
3. Retrieves annotations from UniProt, InterPro, Taxonomy, TED, and Biocentral
4. Creates the .parquetbundle file ready for ProtSpace

Quickest path: drop a FASTA

If your ProtSpace deployment runs the prep backend, you can skip the notebook entirely: drag a .fasta / .fa / .fna file onto the Explore drop zone. The server embeds, projects, annotates, and bundles your sequences, and the visualization opens automatically.

Limits enforced on this path:

Limit	Value
Sequences per file	20 minimum, 1500 maximum
Residues per sequence	2000
Upload size	8 MB
Job wall-clock time	420 seconds (7 minutes)

Behind the scenes the service runs the same CLI subcommands you would run yourself: protspace embed -e prot_t5 and protspace annotate -a default in parallel, then protspace project -m pca2,umap2, then protspace bundle. You get exactly the PCA_2 and UMAP_2 projections. Use the notebook or the CLI for any non-default configuration (different embedder, additional projections, other annotation sources).

TIP

FASTA headers are normalized before embedding, so sp|P12345|NAME_HUMAN becomes P12345.

Self-hosting

There is no feature flag or capability probe, the drop zone always posts to /api/prepare. To enable this path on your own deployment you must run the prep service and build the web app with VITE_PREP_API_BASE pointing at it. Without both, a FASTA drop fails with an upload error.

Unlike .parquetbundle loading, this path uploads your sequences to a server. See Importing Data for the full in-app flow, progress reporting, and error handling.

Step 1: Get Protein Embeddings

You need an HDF5 file (.h5) containing protein embeddings. There are three ways to obtain this:

Option A: Download from UniProt (Recommended)

1. Go to uniprot.org
2. Search for proteins using UniProt query syntax (e.g., (ft_domain:phosphatase) AND (reviewed:true))
3. Click Download → Select Format Embeddings → Submit job
4. Download the results - check UniProt's Tools Dashboard for the prepared embedding file

Option B: Generate from FASTA

Use the dedicated embedding generation notebook:

This notebook:

• Takes a FASTA file as input
• Generates embeddings using various protein language models (ProtT5, ESM2, etc.)
• Outputs an HDF5 file ready for ProtSpace

Option C: Use Your Own Embeddings

For advanced users with custom embeddings, save them as an HDF5 file where each protein is stored as a dataset named by its identifier.

Step 2: Run the Notebook

1. Click the Colab badge at the top of this page to open the notebook
2. Run the first cell to install dependencies (~1 minute)
3. Upload your .h5 embeddings file

Step 3: Configure Options

Annotations

Choose which annotations to include. They come from five sources: UniProt, InterPro, Taxonomy, TED, and Biocentral (predicted).

See the Annotations reference for the complete per-column catalogue: what each annotation means, where it comes from, and which ones are predicted.

TIP

First-time taxonomy selection downloads a database (~1 minute).

Dimensionality Reduction

Choose which 2D projections to generate:

• PCA - Fast, initial overview
• UMAP - Best balance of speed and quality (recommended)
• t-SNE - Great for clusters, slower on large datasets
• PaCMAP - Alternative to t-SNE/UMAP
• MDS - Preserves pairwise distances
• LocalMAP - Local-first alternative to PaCMAP

Parameters (Optional)

Fine-tune settings for each method:

Method	Parameters
UMAP	N Neighbors, Min Dist
t-SNE	Perplexity, Learning Rate
PaCMAP	N Neighbors, MN Ratio, FP Ratio
MDS	N Init, Max Iter
LocalMAP	N Neighbors, MN Ratio, FP Ratio

Quality statistics (Optional)

Tick Compute quality statistics to score how well your annotations separate, and how faithfully each projection preserves the original embedding. This is the notebook's equivalent of the CLI's --stats flag. It is off by default, and the cost grows with dataset size.

ProtSpace renders these scores in the legend and the projection metadata panel. See Separation Scores.

Step 4: Generate and Download

1. Click Generate
2. Wait for processing (time depends on dataset size)
3. Download your .parquetbundle file

Optional: fill missing annotations (EAT)

The Preparation notebook has an Embedding Annotation Transfer panel below the Generate button. It fills blank annotation values on your query proteins from their nearest annotated neighbour in embedding space, with a reliability score attached. The Transfer notebook runs the same transfer on its own, using the protspace transfer CLI.

Transferred values get their own legend section and their own marker style in the plot, so you can always tell them apart from curated ones. See Transferred Annotations (EAT).

Step 5: Visualize in ProtSpace

1. Go to protspace.app/explore
2. Drag & drop your .parquetbundle file onto the scatterplot
3. Start exploring!

Tips

• Start small: Test with a subset of proteins first.
• PCA is fastest: All methods except PCA become significantly slower with larger datasets (quadratic or worse complexity).
• Try multiple methods: For best results, include both PCA and UMAP.

Alternative: Python CLI

For local processing, automation, or larger datasets, see the Python CLI guide.