How to display the expression levels of a specific gene in a spatial clustering plot?

[sun-fei2026]

Could you please show the expression level of a certain gene in the spatial clustering plot?

[wanruiwen-genomics-cn]

Dear @sun-fei2026,

Thank you for your interest in Stereopy!

Short answer: You can display the expression level of a specific gene on a spatial plot using data.plt.spatial_scatter_by_gene(gene_name='YourGeneName').

---

Assessment

• Type: usage/question
• Severity: low
• Affected module: stereo/plots/plot_collection.py

What Is Happening

Stereopy provides several built-in methods for visualizing gene expression levels overlaid on spatial coordinates. The main entry point is the PlotCollection class, accessible via data.plt. The function spatial_scatter_by_gene extracts the expression vector for the specified gene from data.exp_matrix, maps it to spatial coordinates from data.position, and renders a scatter plot colored by expression intensity with a continuous colorbar.

Recommended Workflow

Step 1: Basic spatial gene expression plot

import stereo as st

# Read your data
data = st.io.read_gef('your_file.gef', bin_size=50)
# or
data = st.io.read_h5ad('your_file.h5ad')

# Plot expression of a single gene on spatial coordinates
data.plt.spatial_scatter_by_gene(gene_name='YourGeneName')

# Plot multiple genes at once (each in its own panel)
data.plt.spatial_scatter_by_gene(gene_name=['Gene1', 'Gene2', 'Gene3'])

This will produce a spatial scatter plot where each spot/bin is colored by the expression level of the specified gene.

Step 2: Customize the appearance

data.plt.spatial_scatter_by_gene(
    gene_name='YourGeneName',
    dot_size=10,
    palette='CET_L4',        # colormap (default)
    color_bar_reverse=True,   # reverse color scale
    vmin=0,                   # min expression cutoff
    vmax=5,                   # max expression cutoff
    width=10,
    height=10
)

Step 3: Save the plot to a file

data.plt.spatial_scatter_by_gene(
    gene_name='YourGeneName',
    out_path='./gene_expression_spatial.png',
    out_dpi=300
)

Alternative Approaches

If you are working with CellBin data (cell segmentation polygons):

data.plt.cells_plotting(color_by='gene', color_key='YourGeneName')

If you want to see raw vs. Gaussian-smoothed expression side by side:

data.plt.gaussian_smooth_scatter_by_gene(gene_name='YourGeneName')

If you are working with multi-sample data (MSData):

ms_data.plt.ms_spatial_scatter(color_by='gene', color_key='YourGeneName', ncols=3)

Notes

• Make sure the gene name you provide exactly matches the names in data.gene_names. You can check available genes with print(data.gene_names).
• The spatial coordinates are taken from data.position. If your data has not been loaded with spatial coordinates, the plot will not render correctly.
• The default colormap is CET_L4, which works well for continuous expression data. You can change it via the palette parameter.

Please let us know if you have further questions!

Best regards,
Stereopy Maintainer