Result visualization and postprocessing

This tutorial introduces the postprocessing and visualization utilities provided by SMODER.

After running a SMODER pipeline, the main output file is usually:

spatial_decon_result.h5ad

This AnnData file may contain:

inferred cell-type proportions,
learned SMODER embeddings,
spatial coordinates,
RNA and second-modality encoder representations,
reconstructed low-dimensional features.

SMODER also provides utilities for generating spatial result figures and reconstructing denoised gene-level or feature-level signals.

Loading a SMODER result

import scanpy as sc

adata = sc.read_h5ad("spatial_decon_result.h5ad")

print(adata)
print(adata.obsm.keys())

Commonly used fields include:

adata.obsm["spatial"]
adata.obsm["cell_type_proportions"]
adata.obsm["embedding"]

For trained models that saved encoder representations, the result file may also contain keys such as:

adata.obsm["rna_encoder"]
adata.obsm["peak_encoder"]
adata.obsm["adt_encoder"]

Plotting cell-type proportion heatmaps

SMODER provides functions for plotting inferred cell-type proportions.

import scanpy as sc
from smoder.visualization import plot_cell_type_proportion_panel

adata = sc.read_h5ad("spatial_decon_result.h5ad")

plot_cell_type_proportion_panel(
    adata,
    out_path="cell_type_proportion_panel.png",
    obsm_key="cell_type_proportions",
    obs_start_col=9,
    top_n=12,
    ncols=4,
    title="Spatial heatmaps of selected cell-type proportions",
)

The argument obs_start_col is used when cell-type names are stored in adata.obs after metadata columns. For example:

Mousebrain H3K27ac: cell-type names start from obs[9:].
HBC: cell-type names start from obs[8:].
Simulated human melanoma: cell-type names start from obs[4:].

Plotting all cell types

from smoder.visualization import plot_all_cell_type_proportions

plot_all_cell_type_proportions(
    adata,
    out_path="all_cell_type_proportions.png",
    obsm_key="cell_type_proportions",
    obs_start_col=9,
    ncols=6,
    title="Spatial heatmaps of cell-type proportions",
)

Plotting embedding-based spatial clusters

The learned SMODER embedding can be clustered and visualized spatially.

from smoder.visualization import plot_embedding_spatial_clustering

clustered = plot_embedding_spatial_clustering(
    adata,
    out_path="embedding_spatial_clustering.png",
    embedding_key="embedding",
    method="leiden",
    resolution=0.6,
    n_neighbors=15,
)

The cluster labels are stored in:

clustered.obs["smoder_cluster"]

Reconstructing denoised RNA expression

The function omics_reconstruct can reconstruct selected RNA genes from trained SMODER embeddings.

from smoder.postprocessing import omics_reconstruct

rna_recon = omics_reconstruct(
    omics_type="RNA",
    expr_path="RNA.h5ad",
    spatial_path="spatial_decon_result.h5ad",
    target_genes=["Penk", "Ppp1r1b", "Sez6l", "Gng2"],
    encoder_key="rna_encoder",
    hidden_dim=256,
    n_layers=3,
    epochs=500,
    lr=1e-4,
    patience=100,
    save_path="RNA_recon.h5ad",
)

The returned AnnData object stores reconstructed values in .X:

print(rna_recon.shape)
print(rna_recon.var_names)

Reconstructing second-modality signals

For peak or gene-level epigenomic signals, use omics_type="EPIGENOMICS" or omics_type="ATAC" with peak_encoder:

epi_recon = omics_reconstruct(
    omics_type="EPIGENOMICS",
    expr_path="gene_level_epigenomic_signal.h5ad",
    spatial_path="spatial_decon_result.h5ad",
    target_genes=["Penk", "Ppp1r1b", "Sez6l", "Gng2"],
    encoder_key="peak_encoder",
    hidden_dim=256,
    n_layers=3,
    epochs=500,
    lr=1e-4,
    patience=100,
    save_path="epigenomics_recon.h5ad",
)

For ADT or protein marker signals, use omics_type="ADT" with adt_encoder:

adt_recon = omics_reconstruct(
    omics_type="ADT",
    expr_path="HBC_ADT.h5ad",
    spatial_path="spatial_decon_result.h5ad",
    target_genes=["KRT5.1", "CD68.1", "CD8A.1", "HLA-DRA"],
    encoder_key="adt_encoder",
    hidden_dim=256,
    n_layers=3,
    epochs=500,
    lr=1e-4,
    patience=100,
    do_preprocess=False,
    save_path="ADT_recon.h5ad",
)

Plotting reconstructed heatmaps

After reconstruction, spatial heatmaps can be generated from the reconstructed AnnData object.

import scanpy as sc
from smoder.visualization import plot_reconstruction_heatmaps

rna_recon = sc.read_h5ad("RNA_recon.h5ad")

plot_reconstruction_heatmaps(
    rna_recon,
    out_dir="figures",
    prefix="rna",
    title_prefix="Denoised RNA expression",
)

Notes

The reconstruction utilities are intended for downstream analysis and visualization. They require the SMODER result file to contain the appropriate encoder representations, such as rna_encoder, peak_encoder, or adt_encoder.

Representative result figures are shown in the Results page.