Importing Data

ProtSpace accepts two kinds of input:

• .parquetbundle, a prepared dataset containing projections and annotations. Loads entirely in your browser.
• .fasta / .fa / .fna, raw protein sequences. These are prepared into a bundle by the ProtSpace prep backend, then opened automatically. See FASTA Upload (Instant Prep).

Both the drop zone and the Import button accept either kind.

Drag and Drop (Recommended)

The easiest way to load data:

1. Locate your .parquetbundle or FASTA file on your computer
2. Drag it onto the scatterplot canvas
3. Drop when you see the drop indicator
4. Data loads automatically

Drop Anywhere

You can drop the file anywhere on the scatterplot area - it doesn't need to be a specific location.

Import Button

Alternatively, use the Import button in the control bar:

1. Click the Import button in the top-right corner
2. Select your .parquetbundle or FASTA file from the file picker
3. Click Open

FASTA Upload (Instant Prep)

Drop a FASTA file and ProtSpace prepares it for you, no Colab notebook, no local install.

Accepted extensions are exactly .fasta, .fa, and .fna. Compressed (.gz) and other sequence extensions are not accepted.

What happens

1. Pre-checks run in your browser. ProtSpace checks the file size and counts sequences before uploading, so an out-of-range file fails immediately instead of wasting an upload.
2. The file is uploaded to the prep backend, which queues it as a job.
3. A progress overlay appears, titled Preparing FASTA…, with a Cancel button. The status line underneath tracks the job: Position N in queue… while waiting, then the embedding step (the longest phase, the bar creeps forward while it runs), then Projecting…, then Bundling…. If a job runs longer than expected the status changes to Still working, large jobs can take a few minutes…. Going to another dataset meanwhile with the browser's Back or Forward cancels the preparation, as Cancel does.
4. The finished bundle opens automatically. ProtSpace downloads it and loads it into the scatterplot; there is no second click.

Limits

Limit	Value
Sequences per file	20 minimum, 1,500 maximum
Residues per sequence	2,000
Total residues	1,500,000
Upload size	8 MB
Backend job timeout	420 seconds (7 minutes)
Submissions per client	5 per 15 minutes (default)

The backend also rejects files with duplicate sequence identifiers, and sequences containing non-protein characters.

FASTA upload leaves your computer

Loading a .parquetbundle is fully local. Uploading a FASTA is not, the sequences are sent to the prep backend for processing. Prepared bundles are single-use downloads and are deleted from the server after you download them, or after one hour if you don't.

What the backend produces

The prep service runs the same steps as the Python CLI, with fixed defaults:

• Embeddings from the prot_t5 model (computed via the Biocentral service)
• Projections PCA_2 and UMAP_2
• Annotations from the default annotation group

FASTA headers are normalised to their parsed identifier before processing, so a header like >sp|P12345|NAME_HUMAN appears in ProtSpace as P12345.

To choose a different embedder, projection methods, or annotation set, prepare the data yourself with Google Colab or the Python CLI.

Requirements and larger datasets

FASTA upload only works on a deployment that runs the prep backend. protspace.app has it enabled. If you self-host, you need to:

• run the prep service, the protspace-prep service in docker-compose.yml, built from apps/prep/
• build the web app with VITE_PREP_API_BASE pointing at that service

Without both, a FASTA drop fails with an upload error. There is no capability probe, the app always attempts the upload.

For datasets beyond these limits, use the Colab notebook or the Python CLI instead, then import the resulting .parquetbundle.

What Happens When You Load Data

After successfully loading a file:

1. Scatterplot populates: All proteins appear as colored points
2. View restored or initialized: ProtSpace uses the annotation and projection named in the URL if the dataset has them, and the first available options if it doesn't
3. Settings restored: Previously saved or bundled customizations are applied
4. Legend appears: Shows all categories with color assignments
5. Ready to explore: You can now pan, zoom, and interact with the data

A bundle prepared with --stats also lights up separation scores: score strips above the legend and a Separation section in the projection metadata panel. That is a property of the file, not a setting you toggle.

Loading Time

Small datasets (< 10K proteins) load instantly. Larger datasets may take a few seconds to process and render.

Data & Settings Persistence

All persistence is local to your browser, stored datasets and settings are never sent to a server. (The one time data leaves your machine is a FASTA upload, described above.)

• Your dataset is remembered: The last imported file is saved in your browser's Origin Private File System (OPFS) and automatically restored when you revisit ProtSpace. Choosing an example from the Import menu (see Example Datasets) replaces it and clears the stored file. Opening an example through a ?dataset= link does not touch the stored file — the app returns to it once you drop the parameter.
• Settings persist per dataset: Legend customizations (colors, shapes, hidden categories, sort order) and export options are saved in browser storage for each dataset. The shape size you pick is saved once for the whole dataset, not per annotation. When you reload or revisit the same dataset, your settings are restored, except for the examples (next point).
• Examples always reopen in their curated state: Examples are the exception. Each time an example loads — from the Import menu, a link, Back/Forward or a reload — it opens with its curated legend settings and tooltip fields, and changes you made to it are discarded. Contours don't carry over either: an example chosen from the Import menu opens with contours off, as its plain ?dataset= link does, and Back returns to the previous dataset with its contours. To keep a customized example, export it as a .parquetbundle with the legend settings included and import that file; it then persists like any import. Keep the file: an imported copy counts as the same dataset as the example, so opening the example again resets the copy's saved settings until you import the file again.
• Annotation and projection persist in the URL: ProtSpace keeps the currently selected annotation and projection in the page URL as query parameters (annotation=... and projection=...). Refreshing the page, using the browser's back/forward buttons, or sharing the link will restore the same view when those options exist in the active dataset. A bare /explore URL stays unchanged on first load; ProtSpace only writes view params after you change the selection or when it needs to normalize an invalid URL value. The Contours mode is kept the same way, as density=auto for Auto or density=on for Always; with contours off the parameter is left out.
• File-embedded settings take priority: If a .parquetbundle includes saved settings (via the export dialog's "Include legend/export settings" options), those are applied on import, replacing any previously stored settings for that dataset.
• Starting fresh: To reset all settings for a dataset, re-import a .parquetbundle that has embedded settings, or clear site data in your browser settings. For an example, just open it again.

URL-backed view state

If the URL points to an annotation or projection that does not exist in the currently loaded dataset, ProtSpace falls back to the example's curated view, or to the dataset's first annotation or projection for your own imports, and updates the URL to match. An unrecognized density value is treated as Off and removed.

Automatic dataset restore requires OPFS

ProtSpace uses the Origin Private File System (OPFS) to restore your last imported dataset after a page reload.

OPFS may be unavailable in private/incognito browsing mode, when browser storage is restricted, or in older browsers that do not support it.

ProtSpace still works normally without OPFS. Your dataset loads for the current session, but you will need to import it again after reloading the page.

When a Previous Load Crashed

If a previous session failed to finish loading a dataset (the browser crashed, the tab was closed mid-load, or the file was read but the plot failed to draw it), ProtSpace shows a recovery banner above the scatterplot when you return. The banner names the file that didn't finish and offers three actions:

• Try again, re-attempts the load from the stored copy. Useful if the previous failure was transient (network hiccup, momentary browser stall).
• Load default, replaces the stored file with the startup demo, a small set of venom toxins. Use this if you don't need to recover the specific file.
• Clear stored data, deletes the stored file without loading anything. Choose this if the file is corrupt or you'd rather import a fresh copy yourself.

After three failed retries the banner shifts tone, recommending you clear or load the demo rather than continue retrying.

A file that ProtSpace cannot read, such as a corrupt bundle or a FASTA file whose preparation fails, is never stored, so it leaves browser storage as it was: your next visit starts as it would have without that import, and no banner offers the file that failed. A stored copy that can no longer be read is cleared, and the startup demo loads in its place with a notice.

Why a banner instead of just retrying?

Auto-retry would loop forever on a genuinely broken file. The banner makes the failure visible and lets you choose the recovery path that fits the situation.

Need a Data File?

If you only have sequences, drop the FASTA straight onto the scatterplot, see FASTA Upload (Instant Prep). To build a .parquetbundle yourself:

• Using Google Colab - No installation required (recommended)
• Using Python CLI - For local processing or automation

Or open the Import menu's Examples section and choose the startup demo or one of the datasets behind the ProtSpace paper's figures; Example Datasets says what each one contains and how it was built. To try transferred annotations and separation scores together, choose Snake three-finger toxins (EAT).