> ## Documentation Index
> Fetch the complete documentation index at: https://docs.purna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Spatial Omics Viewer

> Explore prepared single-cell data and spatial imagery, save cell selections and notes, and share data context with agents.

The Spatial Omics Viewer helps you explore prepared single-cell datasets and supported microscopy images inside your Purna workspace. Open a file from **Files** or a chat attachment to inspect it alongside your conversation.

![PBMC dataset open in Purna's Spatial Omics Viewer with a UMAP scatterplot, gene list, and cell sets beside the Files library](https://cms.purna.ai/_emdash/api/media/file/01M6GZCDNR448WZ670GNG522W5.01M6GZCF1DVVZ4KEXX0AGA6QE1.webp)

Explore a prepared UMAP embedding alongside gene and cell-group controls.

The available views depend on your data. An expression dataset does not necessarily contain an embedding, an image does not necessarily contain cell identities, and spatial coordinates alone do not link an image to your cells.

Opening a file does not calculate UMAP, normalize expression, identify cell types, segment tissue, or perform a scientific analysis.

## What you can explore

| View or capability | What you can do | What your data needs |
| - | - | - |
| Embeddings | Explore an existing UMAP, t-SNE, PCA, or another supported two-dimensional embedding | Prepared coordinates with matching cell identities |
| Gene expression | Search available genes and color cells by their supplied expression values | Feature identities and a supported numeric expression matrix |
| Cell groups | Select existing clusters or cell-type groups and compare their highlighting | Prepared categorical cell metadata |
| Heatmaps | Inspect expression across a prepared subset of genes | Expression data and a supported, manageable feature subset |
| Spatial imagery | Pan and zoom through prepared images and adjust available image layers or channels | Supported OME imagery with the required image metadata |
| Linked spatial exploration | Coordinate cell highlighting and expression with spatial locations where configured | A prepared configuration linking cell identities, coordinates, and any imagery |
| Personal annotations | Save cell selections, add your own labels, and record notes | A prepared dataset saved in **Files** with cell-selection controls |

Only available views are offered. A missing **Heatmap** or **Spatial** option can mean that the dataset lacks the required inputs, rather than that loading failed.

## Supported files

| File | Support and requirements |
| - | - |
| Processed AnnData `.h5ad` | Upload the processed file alone. Purna prepares it for viewing automatically when its contents are compatible. It needs a supported embedding or a usable prepared heatmap; raw counts alone are insufficient. |
| Prepared AnnData `.zarr.zip` | Contains one compatible AnnData store with cell identities and prepared viewing data. Use Zarr v2 for predictable compatibility. |
| AnnData archive named `.zip` | Opens in this viewer after Purna confirms that the contents are a supported AnnData store. An arbitrary ZIP is not an omics dataset. |
| Embedding-only AnnData `.zarr.zip` | Supports prepared coordinates and optional cell groups. Gene expression and heatmaps are unavailable without expression data. |
| Prepared `.ome.tif` or `.ome.tiff` | Opens supported OME-TIFF imagery directly. The file must contain valid, readable OME metadata and supported image encoding. |
| Prepared `.ome.zarr.zip` | Opens a supported Zarr v2 OME image at the archive root, with one multiscale image and declared axes and channel metadata. |
| Prepared `.vitessce.json` configuration | Opens a supported viewer configuration referencing prepared resources, including linked imagery. The configuration does not contain or generate the underlying scientific data. Its interaction state remains temporary. |

Extensions are case-insensitive. Keep the correct compound filename, such as `sample.ome.tiff` or `sample.ome.zarr.zip`. Renaming an unrelated file does not convert its contents.

An image-only file provides image viewing, not cell identities, gene expression, or saved cell selections. Uploading an image and an AnnData file separately does not automatically align or link them. Spatial coordinates in an H5AD file alone do not automatically create a linked tissue-image view.

### Prepare an AnnData viewing copy

Use an already-processed dataset. Check the following before uploading:

* Each cell has a unique, consistent identifier. Embeddings, groups, and expression rows must refer to the same cells in the same order.
* Embedding coordinates are numeric and already computed. Standard UMAP and t-SNE inputs are two-dimensional. For supported PCA data, the viewer displays the first two components.
* Cell-group columns are stored as categorical metadata when you want group controls. A text column is not automatically treated as a cell-type grouping.
* Expression is supplied at the scale you want to inspect. Supported matrices include dense, CSC, and CSR data. For large sparse datasets, a CSC viewing copy can make gene exploration more responsive.
* A heatmap has a prepared boolean feature filter, such as a highly variable gene subset. A full expression matrix does not automatically enable the heatmap.

The viewer displays the expression values you supply. It does not determine whether they are raw counts, normalized values, or logarithmically transformed values. Keep that information with your dataset and use it when interpreting colors or asking for analysis.

### Package Zarr archives correctly

For AnnData, the ZIP must contain one store at the archive root or inside one top-level folder ending in `.zarr`.

For OME imagery, place the image store directly at the ZIP root. A wrapper folder is not supported for the direct OME-Zarr image path.

Use ZIP **Store** mode, also called `ZIP_STORED` or no ZIP-level compression. Compressing Zarr data internally is different from compressing the surrounding ZIP entries. Do not use a normal ZIP compression setting and assume it will be compatible.

Private multi-file `.zarr` directories, archives containing multiple stores, and arbitrary collections of files are not direct substitutes for these prepared archives. Other Zarr versions or encodings are not guaranteed to work.

## How Purna prepares your file

1. **Upload completes.** Add the file through **Files** or chat. Wait until the upload finishes.
2. **Purna checks supported data.** For processed H5AD and AnnData-Zarr archives, Purna checks the contents and prepares the information needed to open the available views. For H5AD, upload the dataset itself; you do not need to prepare or upload a companion file.
3. **The viewer becomes available.** While preparation is pending, you may see **Preparing viewer…**. Open the file when it is ready, or leave its tab open to continue automatically when preparation finishes.

New supported uploads prepare automatically. An older supported file may need preparation when you first open it. Closing its tab does not cancel preparation. Reopening a ready file reuses its prepared preview.

Supported OME images have their own automatic viewing preparation. For image-specific requirements and personal region tools, see the [Slides Viewer guide](https://docs.purna.ai/scientific-components/slides-viewer.md). Ordinary CSV, text, and other unrelated files keep their normal previews; they are not automatically converted into omics data.

Your original remains one visible file in **Files**. Preparation does not overwrite its values, identifiers, coordinates, or original annotations. It does not normalize expression, calculate embeddings, infer cell types, convert arbitrary microscopy formats, repack an incompatible archive, or align images with cells.

If a preview cannot be prepared, you can still download the original where you retain access. You may also ask an agent to inspect the file or prepare a compatible viewing copy as a separate, explicit task. Review any transformation and its assumptions before using the result.

## Working with your data

### Open and arrange the viewer

1. Open a supported file from **Files** or a chat attachment.
2. Wait for preparation and loading to finish.
3. Enable **Show Controls** to reveal available gene, cell-group, or image-layer controls.
4. Choose **Embeddings**, **Heatmap**, or **Spatial** when that view is available.

On desktop, drag the workspace divider to resize the pane. Use the expand icon for more room, then collapse it to return to your workspace. You can keep several file tabs open, switch between them, and download the original from the viewer toolbar.

### Explore embeddings and expression

* Pan and zoom to inspect a cluster or individual cells.
* Choose another embedding when the dataset contains more than one supported option.
* Search the gene list and select a gene to change expression coloring.
* Expand **Cell Sets** to explore available groups and their highlighting.
* Open **Heatmap** to inspect the prepared gene subset when available.

Changing a gene or color setting does not recompute the embedding. Points represent the coordinates supplied in your file. A cluster shape or color pattern alone does not establish a cell identity or biological finding.

![Expression heatmap for a prepared PBMC dataset in Purna, with gene labels, an expression color scale, and cell-group controls](https://cms.purna.ai/_emdash/api/media/file/01M6GZCKX3Z93W0SD2M1BPQ0TR.01M6GZCMWRH504J8QMNMM146SN.webp)

Switch to Heatmap to inspect expression across the prepared gene subset.

### Select cells or a region

Use the plot's lasso tool to draw around cells, or select an existing group in **Cell Sets**. Wait for cell identities to load, then check the selected-cell count. Use **Clear selection** to start again.

Where a configured spatial view provides cell-selection tools, you can select cells in a spatial region and compare highlighting across its linked views. This requires prepared cell identities and matching spatial coordinates; an image alone cannot provide that information.

A saved cell selection records the cells you selected. It is not a saved tissue-boundary drawing, freehand image annotation, or segmentation edit. The current viewer does not provide a general image-painting or region-boundary editor.

### Save selections, labels, and notes

For a prepared dataset saved in **Files** with cell-selection controls:

1. Select the cells you want to keep.
2. Open **Selections**. Some versions label this panel **Selections & labels**.
3. Choose **Save selection** and give the selection a meaningful name, such as `Outliers to review`.
4. Open that selection's details to edit its cell label or note. In the compact panel, use the pencil icon; **Done** closes the editor.
5. Wait until the viewer reports **Saved** before closing the tab or reloading.

Select a saved group's name or cell-count control to restore those cells. **Clear selection** clears the active highlight without deleting your saved groups. **Reset view** resets viewing controls while preserving named annotations. Delete a saved group from its details when you no longer need it.

Labels and notes are your personal interpretation of those cells. They do not rewrite the original dataset's cell-type columns or establish that a label is scientifically correct. Multiple saved groups may overlap.

### What is saved

For supported prepared files opened from **Files**, personal viewer settings can include the selected embedding or gene, camera and color settings, layout, and controls visibility. Where cell-selection controls are available, named selections, cell labels, and notes also persist after closing and reopening the file or reloading the page, once the save succeeds.

These updates belong to you and the particular version of the source file. They are not collaborative edits to the original dataset. Replacing the source starts a new view; Purna does not silently assign old labels to a replacement file. Downloading the original does not include your personal overlays.

Local configurations, custom configuration-file sessions, and demonstrations remain temporary. Do not assume their interactions will return after closing or reloading.

### Work with an agent

Agents can work with your files to help with analysis, statistics, and scripts. They can read the cell identities, labels, and notes in a selection you explicitly share. They can also help write plotting scripts, but you must inspect the resulting graphics yourself.

To share a selection, open the dataset in a saved chat in the same project and choose **Attach to chat** or **Attach selection to chat**, depending on your version. This adds the selection and source file to the composer. Add your question and send it yourself; attaching does not automatically send a message or start an analysis.

The shared file contains the selected cells and overlapping labels and notes. Treat this as sharing those details with the project. Your other personal selections are not included automatically. Select the cells you intend to discuss and attach a new snapshot after changing them.

For example, you can ask:

* "Read the attached selection and source dataset. Report how many selected cells belong to each supplied cell group."
* "Write a reproducible script comparing expression in these selected cells with the remaining cells. State the normalization, sample grouping, and statistical assumptions before interpreting the result."
* "Check whether these saved cell identifiers still match the source file before continuing."

**Important: agents cannot view the graphics or slides displayed in this viewer.** They do not see your live plot, tissue image, camera position, or every selection you make. An agent answer is not a visual inspection of the slide.

The system is designed to keep a human in the loop. You inspect the graphics, choose the cells or region, and review the agent's analysis, statistics, and scripts. Verify the source version, selected cells, data quality, assumptions, and biological interpretation. Do not rely completely on the agent or treat its suggestions as validated findings. Agents do not control the viewer or automatically write annotations back to it.

## Limits and unsupported inputs

| Limit | What it means |
| - | - |
| Up to 128 saved selections per view | Remove groups you no longer need before adding more. |
| Up to 100,000 cell identifiers per selection | Choose a smaller subset for saving or sharing larger selections. |
| Up to 2 MiB for a saved view or selection-sharing request | Long identifiers, notes, and overlapping groups can reach this limit before the cell-count limit. |
| Up to 32 embedding arrays in automatic inspection | Prepare a viewing copy with fewer embeddings if the file exceeds this limit. |
| Automatic group detection checks up to 64 cell-metadata columns | Put the intended categorical groups in the inspected metadata; not every column in a very wide dataset is offered. |
| Automatically detected cell-group columns support up to 1,000 categories each | High-cardinality identifiers are not suitable cell-group controls. |
| Direct OME-Zarr ZIP supports up to 64 channels and 32 image levels | Prepare a compatible viewing copy if the image exceeds these bounds. |

Preview limits are separate from upload limits. A successful upload does not guarantee comfortable viewing of a large dataset. Large cell counts, dense expression, image channels, or complex metadata can take longer to open and consume more browser memory. Use a smaller prepared viewing copy if the browser becomes unresponsive. A missing or oversized heatmap feature subset can leave the heatmap unavailable while other views still work.

The current viewer does not directly open or automatically prepare:

* Standalone CSV, TSV, or spreadsheet data as an omics view. CSV keeps its table preview; existing embedding coordinates must be packaged into a compatible AnnData viewing file.
* Raw counts with neither a supported embedding nor a usable prepared heatmap. Preparation does not calculate the missing analysis.
* General HDF5 `.h5` files, raw sequencing reads, standalone MTX or raw 10x bundles, Seurat `.rds` objects, or `.loom` files as native omics inputs.
* Arbitrary ZIP or TAR archives, multiple-store ZIPs, ZIP entries using unsupported compression, incomplete archives, or renamed files whose contents do not match their extension.
* Private multi-file Zarr folders as direct upload-and-open datasets.
* Ordinary TIFF or general DICOM slides through this viewer. Supported SVS and NDPI files open in the [Slides Viewer](https://docs.purna.ai/scientific-components/slides-viewer.md). A standard `.tif` is not an OME-TIFF simply because it has been renamed.
* H5AD files that rely on external data files or unsupported encodings, or inputs that exceed preparation limits.
* Custom viewer plugins, arbitrary configurations, or the full set of controls available in other specialized scientific applications.

Upload acceptance and native viewing are different capabilities. When a file has no compatible preview, keep the original for download or use an appropriate external tool. Preparing a smaller or converted viewing copy is a separate task, not an automatic biological correction.

## Troubleshooting

| What you see | What to try |
| - | - |
| **Preparing viewer…** stays visible | Confirm the upload completed. Preparation may take longer for a large file. Reopen the file or use **Retry** if offered. If it remains stuck, contact support with the file name and visible error; do not repeatedly upload identical copies. |
| The H5AD viewer asks for preparation or a viewing index is unavailable | Open or retry the processed H5AD itself. You should not need to upload a second reference file. If preparation fails again, use a compatible prepared AnnData-Zarr viewing copy or contact support. |
| "Could not find end of central directory" or another ZIP error | Confirm it is a complete ZIP that opens locally, not an H5AD or another file renamed to `.zip`. Re-export one supported store with ZIP Store mode and upload it again. If a valid archive still fails, contact support with the exact error. |
| Unsupported compression, archive layout, or image metadata | Check the packaging requirements above. Use one store, the appropriate root layout, compatible image metadata, and no additional ZIP-entry compression. Renaming cannot repair the file. |
| No embedding, or an empty plot | Confirm prepared coordinates exist and match the cell identities. The viewer does not calculate an embedding from a counts table. |
| No gene search or expression colors | Confirm the dataset contains readable features and expression values. An embedding-only file or image does not contain them. |
| **Heatmap** is missing | Include a supported prepared feature filter and a manageable gene subset. An expression matrix alone is insufficient. |
| Expected cell groups are missing | Check that the columns are categorical, refer to the same cells, and fit the metadata/category limits above. |
| **Spatial** is missing or cells do not align with the tissue | Check that the imagery, coordinates, and cell identities were prepared and configured together. Separate uploads do not establish alignment. Do not trust a mismatched overlay. |
| Expression colors look unexpected | Check the source's expression scale and selected gene. Purna does not infer normalization or validate biological meaning. |
| Save or attach actions are unavailable | Select a supported, smaller cell group and wait for identities to load. Saved cell annotations require a prepared dataset saved in **Files** with those controls. Chat attachment also requires a saved chat in the same project. |
| **Not saved** or a save error | Keep the tab open, check your connection, and use **Save** or **Retry save** if offered. Resolve the error and wait for **Saved** before leaving. Reduce saved data if the size limit is reached. |
| "This view changed in another tab" | Another window saved a newer view. Keep any unsaved notes you need, then choose **Reload saved view**. Reloading replaces local edits; concurrent changes are not automatically merged. |
| "The dataset changed" | Close and reopen the viewer for the current source. Check your cell selection again; annotations from the previous source version are not automatically transferred. |
| Access denied or unavailable data | Confirm you still have access to the file and project. Reopen after access is restored. |
| Blank canvas, graphics error, or slow interaction | Check browser graphics/WebGL support and available memory. Try a smaller dataset or prepared image, fewer cells, or fewer channels. |

Return to [Scientific Components](https://docs.purna.ai/scientific-components/overview.md), or see [Files](https://docs.purna.ai/guides/files.md) for uploading and organizing your data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.