metachat.pl.plot_3d_feature

metachat.pl.plot_3d_feature(adata, feature, spatial_key='spatial_3d', cmap_continuous='Viridis', layer=None, use_raw=False, point_size=3, opacity=0.6, aspectratio=(1.1, 1.0, 1.3), show_axes=True, figsize=(9, 9), plot_savepath=None)[source]

Visualize a spatial feature (gene or obs annotation) in 3D using Plotly.

This function renders a 3D scatter plot for any feature stored in .obs, .var, .layers, or .raw, using the spatial coordinates stored in adata.obsm[spatial_key].

Parameters

adataanndata.AnnData

Annotated data matrix with 3D spatial coordinates stored in adata.obsm[spatial_key].

featurestr

Name of the feature to visualize. It can be: - A column name in adata.obs (categorical or continuous); - A gene name in adata.var_names or adata.raw.var_names.

spatial_keystr, default=’spatial_3d’

Key in adata.obsm containing the 3D spatial coordinates (shape: (n_obs, 3)).

cmap_continuousstr, default=’Viridis’

Colormap for continuous features.

layerstr, optional

If provided, use expression values from adata.layers[layer].

use_rawbool, default=False

Whether to use adata.raw instead of adata.X when available.

point_sizeint, default=3

Size of scatter plot markers.

opacityfloat or list, default=0.6

Global opacity (float) or per-category opacity (list, same length as categories).

aspectratiotuple of float, default=(1.1, 1.0, 1.3)

Aspect ratio (x, y, z) for 3D axes scaling.

show_axesbool, default=True

Whether to display 3D axis lines and labels.

figsizetuple of float, default=(9, 9)

Figure size in inches (controls pixel width/height of the Plotly figure).

plot_savepathstr, optional

Path to save the 3D figure (e.g. "results/3D_feature_geneA.pdf"). If None, the figure is displayed interactively.

Returns

figplotly.graph_objects.Figure

The generated Plotly 3D scatter figure.

Notes

  • If the feature is categorical, it is colored using discrete color sequences.

  • If the feature is continuous (e.g., gene expression), a continuous colormap is applied.

  • This function is ideal for visualizing 3D tissue reconstructions, such as those derived from MetaChat’s 3D MCC analysis.