Analyze Nanostring data¶

This notebook uses Lung5_Rep2 as an example to walk through a complete NanoString workflow in OmicVerse: loading the data, inspecting the spatial layout across FOVs, checking segmentation quality, and then learning graph embeddings with CAST for downstream clustering.

The analysis is organized into four parts:

1. Set up the environment and confirm the input file structure.
2. Read the NanoString dataset and inspect spatial coordinates and expression patterns.
3. Zoom in on a single FOV to examine image overlays and segmentation boundaries.
4. Prepare CAST inputs, generate embeddings, and compare clustering results in spatial space.

The goal is not only to run the pipeline, but also to understand why each step appears where it does and what the key parameters control.

1. Environment setup¶

This section does three things: import omicverse, set the plotting font, and enable auto-reload.

• ov.style(font_path='Arial'): keeps the plotting style consistent and avoids font mismatches in exported figures.
• %autoreload 2: useful during local development or package debugging, because edited source code is picked up when the cell is rerun.
• Path: used later to build data paths in a readable way.

This line initializes the mixed CPU/GPU runtime used by OmicVerse.

For most users, the practical purpose is simple: later steps that involve deep learning or graph embedding can access hardware resources more reliably. If no GPU is available in the current environment, CAST should be configured to run on CPU instead.

2. Check the NanoString data directory¶

Before reading the data, print the directory tree and confirm that the expression matrix, metadata, and FOV coordinate files are all present where expected.

This is a small step, but it prevents a common source of errors: incorrect paths are often easier to fix at the file level than after a loader function fails.

We download the count data and HE image from https://nanostring.com/products/cosmx-spatial-molecular-imager/ffpe-dataset/

3. Read the NanoString dataset¶

This cell builds an AnnData object with ov.io.read_nanostring(). Once loaded, the expression matrix, cell metadata, FOV annotations, and spatial coordinates are organized into adata.

Main parameters¶

• path: directory containing the sample files.
• counts_file: expression matrix file, usually arranged as cells × genes.
• meta_file: metadata file with cell-level annotations.
• fov_file: file describing the spatial positions of different fields of view.

In practice, read_nanostring() is the entry point that converts raw NanoString outputs into a structure that can be used directly for plotting and downstream analysis.

4. Inspect the spatial layout at the whole-sample level¶

Here ov.pl.embedding() is used for a first overview across all FOVs.

Main parameters¶

• basis='spatial_fov': use the stitched spatial coordinate system across FOVs. This is the right view when you want to inspect how multiple FOVs are positioned relative to one another.
• color=['Max.PanCK', 'fov']: plot one panel by marker intensity and one by FOV identity.
• vmax='p99.2': cap the color scale at the 99.2th percentile to reduce the influence of extreme values.
• cmap='Reds': use a continuous red colormap for expression intensity.
• wspace=0.35: adjust spacing between panels.

At this stage, the aim is not fine detail. It is simply to confirm that coordinates, FOV stitching, and signal ranges look reasonable before moving to local inspection.

Printing adata is a quick sanity check that the dataset loaded correctly. The most useful things to confirm here are:

• the number of observations and variables, that is, cells and features;
• which metadata columns are available in obs;
• whether obsm, layers, and uns contain the spatial objects needed for downstream analysis.

5. Select a single FOV for local inspection¶

From this point on, the notebook focuses on fov == '12'. The reason is practical: a whole-sample view is useful for orientation, but a single FOV is much easier to read when checking coordinates, segmentation boundaries, and local expression structure.

To inspect a different field of view, replace '12' with the target FOV identifier.

First, inspect the spatial distribution of Max.PanCK within a single FOV.

The important distinction here is between basis='spatial' and the earlier spatial_fov:

• spatial_fov: better for stitched, whole-sample views across multiple FOVs.
• spatial: better for the original local coordinate system within one FOV.

If the orientation, aspect ratio, or point placement of an individual FOV looks unusual, this is usually the first place to diagnose it.

6. Visualize a single FOV with the background image¶

ov.pl.spatial() overlays the signal on the spatial background image. Compared with a plain scatter plot, this gives a more tissue-like view of the data.

Main parameters¶

• color=[None, 'Max.PanCK']: the first panel shows only the background image, and the second overlays the selected marker. This side-by-side setup makes the correspondence easier to read.
• size=100: controls the size of plotted markers.
• library_id='12': explicitly selects the current FOV image.
• img_key='hires': use the high-resolution image stored for this library.
• alpha_img=1: set image opacity. A value of 1 keeps the image fully visible.
• crop_coord=None: do not crop; display the full FOV.

When working on figure preparation, this step is useful for checking whether the signal pattern matches the image context before adding segmentation contours.

7. Inspect segmentation contours together with expression¶

Next, switch to ov.pl.spatialseg(). This function is more suitable for datasets with segmentation information because it overlays cell boundaries on the image rather than only plotting points.

Main parameters¶

• color='Max.PanCK': color cells by the selected feature.
• edges_color='white', edges_width=0: control segmentation boundary color and line width.
• seg_contourpx=15: thickness of the segmentation contour in pixels.
• library_id='12': choose the FOV to display.
• img_key='hires': use the high-resolution background image.
• crop_coord=None: show the full field rather than a cropped region.

This is a good checkpoint for deciding whether the segmentation overlay is visually informative and whether boundary thickness is appropriate for the current figure scale.

The next plot is similar to the previous one, except that seg_contourpx is no longer set explicitly. Looking at the two versions side by side makes it easier to judge how much the contour thickness affects readability.

A practical rule of thumb:

• if you want to emphasize segmentation structure, increase seg_contourpx;
• if you want to emphasize continuous expression patterns, use thinner boundaries or weaken them visually.

8. Check coordinate ranges before local cropping¶

Before making a zoomed-in view, inspect the x and y coordinate ranges of the current FOV. This makes it easier to define crop_coord based on real values rather than trial and error.

It is a small step, but very helpful when preparing publication figures or when trying to isolate a specific local region.

This cell prints the y-coordinate range separately so that, together with the previous output, a local crop window can be chosen more deliberately.

9. Zoom in on a selected region¶

This cell uses crop_coord=(0, 2000, 400, 2400) to display a local region. In practice, you can think of this as defining a rectangular window within the current FOV so that cell boundaries and expression patterns are easier to inspect at higher resolution.

What crop_coord does¶

Different plotting functions may implement coordinate order slightly differently internally, but the main idea is the same: supply a rectangular range and only display content inside it.

For image-based plots, cropping is especially useful when:

• a region of interest occupies only a small portion of the full FOV;
• segmentation quality needs to be assessed locally;
• figure panels require a tighter composition than the full image.

Print adata again as a light sanity check before moving into the modeling part. The goal is simply to confirm that the visualization steps above did not introduce unexpected changes to the object state.

10. Prepare spatial coordinates for CAST¶

CAST expects explicit coordinate inputs, so here the whole-sample coordinates from spatial_fov are written into adata.obs['x'] and adata.obs['y'].

The original note already hints that this assignment may need to be rerun occasionally and checked for NA values. In practice, that usually means one of two things:

• the object state was not fully refreshed in a previous step;
• the index alignment was not what you expected.

The purpose of this cell is to make the coordinates easy to access later when building the per-FOV dictionaries required by CAST.

11. Build a normalized expression layer¶

Here ov.pp.normalize_total() scales each cell to a total count of 1e4 and stores the result in adata.layers['norm_1e4'].

Main parameters¶

• target_sum=1e4: the target total count after normalization for each cell.
• inplace=False: return the normalized matrix instead of overwriting the original data in place.

Keeping a separate normalized layer is useful because it preserves the raw matrix while creating a standardized input for downstream embedding methods.

12. Organize CAST inputs by FOV¶

CAST expects two dictionaries:

• coords_raw: two-dimensional coordinates for each FOV;
• exp_dict: normalized expression matrices for each FOV.

The key idea is to split one large AnnData object into multiple FOV-level subsets and then pass them to CAST for cross-sample graph representation learning. samples = np.unique(adata.obs['fov']) is used here to iterate over all available FOVs in a consistent order.

13. Run CAST_MARK to generate graph embeddings¶

This is the main modeling step of the notebook: learn graph embeddings from the spatial coordinates and expression matrix of each FOV.

Main parameters¶

• coords_raw: dictionary of spatial coordinates for each FOV.
• exp_dict: dictionary of expression matrices for each FOV.
• output_path: directory where intermediate results or saved outputs are written.
• graph_strategy='delaunay': use Delaunay triangulation to define the spatial graph.
• device='cuda:0': run on the first GPU. Change this if you need CPU or another device.
• args = Args(...): package a group of training hyperparameters used by CAST.

The exact optimization details belong to CAST itself, but from the notebook perspective, this is the step that converts raw spatial expression into a learned embedding space.

14. Use K-means for a first look at the embedding structure¶

After CAST produces embeddings, kmeans_plot_multiple() is used as a quick unsupervised summary. The purpose here is not to produce a final biological interpretation, but to check whether the embedding already separates meaningful spatial domains.

Main parameters¶

• embed_dict: embedding output generated by CAST.
• samples: the FOVs included in the analysis.
• task_name_t='Lung5_Rep2': label used in the visualization.
• output_path_t: directory for saving outputs.
• k=20: number of K-means clusters.
• plot_strategy='sep': plot samples separately rather than merging everything into one panel.

This is best treated as an exploratory checkpoint: if the embedding is informative, even a simple clustering method should begin to reveal structure.

15. Write CAST K-means labels back to adata.obs¶

This loop maps clusters_kmeans back to the original cell table in FOV order and stores the final labels in adata.obs['cast_clusters'].

The reason front_idx and back_idx are tracked manually is that clusters_kmeans is effectively a concatenation of per-FOV results. To restore the labels correctly, each segment has to be aligned back to the matching subset of cells.

16. Store CAST embeddings in adata.obsm¶

In addition to the cluster labels, the 512-dimensional CAST embeddings themselves should be saved for downstream graph construction and Leiden clustering.

The code first creates an empty matrix and then fills it FOV by FOV. Once stored in obsm['X_cast'], the representation can be used just like standard embeddings such as X_pca or X_umap.

Convert cast_clusters to string so that plotting functions treat it as a discrete category rather than a continuous numeric variable. This small step is often necessary for categorical coloring to behave as expected.

17. Visualize CAST clusters in whole-sample space¶

Here basis='spatial_fov' is used again to project the CAST clustering labels back onto the stitched spatial layout of the whole sample. This makes it easy to judge whether clusters are spatially continuous and whether they show interpretable organization across FOVs.

palette=ov.pl.palette_112[:] provides enough distinct colors for cases with many categories.

Earlier, X_cast was temporarily stored as a DataFrame to make index-based assignment convenient. Before computing the neighborhood graph, it is converted back to a numpy array so downstream functions can use it directly.

18. Build a neighborhood graph from the CAST embedding¶

At this stage, PCA is no longer used. Instead, X_cast itself is treated as the representation space for nearest-neighbor graph construction.

Main parameters¶

• n_neighbors=15: connect each cell to 15 nearest neighbors.
• n_pcs=512: here this matches the embedding dimensionality because X_cast has 512 dimensions.
• use_rep='X_cast': explicitly tell the function to use the CAST embedding rather than a default representation.

This step turns the learned embedding into a graph structure that can support community detection and other downstream analyses.

19. Run Leiden clustering¶

Leiden clustering is then applied to the neighborhood graph built from the CAST embedding.

• resolution=0.1: controls clustering granularity. Larger values usually produce more clusters, while smaller values give coarser partitions.

Compared with the earlier K-means result, Leiden depends more directly on the neighbor graph structure, so the two sets of clusters are not expected to be identical.

These Leiden labels are plotted back in spatial_fov coordinates so they can be compared directly with the earlier CAST K-means assignments.

20. Compare clustering results within a single FOV¶

Finally, return to fov == '12' and overlay both leiden and cast_clusters on the segmented image.

This is a practical way to answer two common questions:

1. Do cluster boundaries follow tissue structure?
2. Are the local partitions from K-means and Leiden broadly consistent?

If the two results differ strongly in some regions, it is often worth revisiting the embedding quality, graph construction settings, or segmentation context.

This panel shows the spatial distribution of Leiden clusters on the segmentation overlay. Because the boundary lines are kept relatively thin, it is easier to inspect transitions between neighboring cell groups.

This panel shows the CAST K-means clustering result. Viewed next to the Leiden panel, it helps clarify:

• whether the CAST embedding captures the main spatial structure;
• where local differences between graph-based clustering and direct clustering arise.

Summary¶

At this point, the full workflow is complete:

• read NanoString raw files into an AnnData object;
• inspect spatial expression and segmentation at both whole-sample and single-FOV scales;
• prepare CAST inputs and learn graph embeddings;
• perform K-means and Leiden clustering in the embedding space, then map the results back to spatial coordinates.

Natural next steps would include:

• annotating CAST-derived clusters with marker genes;
• comparing clustering consistency across FOVs or biological replicates;
• combining CAST embeddings with more formal downstream analyses such as neighborhood enrichment, differential expression, or region-level annotation.