API Reference

Core model

smoder.models.deconvolution.selectInfoGenes(Basis, sc_adata, commonGene, ct_select, ct_varname, log_FC=1.25, top_n_filter=False, top_n=200)

选择信息基因的函数（新增top_n筛选选项）

参数:

Basis: 基础表达矩阵，行是基因，列是细胞类型 sc_adata: scanpy的AnnData对象 commonGene: 共同基因列表 ct_select: 需要筛选的细胞类型列表 ct_varname: 细胞类型在sc_adata.obs中的列名 log_FC: 原有的log倍变化阈值，默认1.25 top_n_filter: 是否启用top_n筛选模式，默认False（使用原有log_FC筛选） top_n: 每种细胞类型筛选的差异基因数量，默认2000

返回:

gene2: 最终筛选出的信息基因列表

class smoder.models.deconvolution.SpaMultiDecon_two_modals(ref_adata_dict={'modal1': None}, smo_adata_dict={'modal1': None, 'modal2': None}, nn_para_dict={}, modal2_type='adt')

Bases: object

property weight_loss

property hidden_dim

property learning_rate

property device

property epochs

property seed

property weight_spatial

property weight_consistency

property pca_n_components_rna

property modal2_target_dim

第二模态（ADT/Peak）最终目标维度（仅一个输入参数，统一管控）

property lsi_random_state

set_nn_para(**kwargs)

preprocess(ref_celltype_col, sample_id_col, ct_select, log_FC=1.25, top_n_filter=False, top_n=200, do_select_info_genes=True)

仅完成数据预处理（清洗、归一化、位点对齐），不执行特征工程（降维） 流程：RNA数据预处理 + 模态2（ADT/Peak）数据预处理（TF-IDF/CLR） + 位点对齐

run_feature_engineering_and_mapping(obsm_name_rna=None, obsm_name_modal2=None)

create_spatialgraph(obsm_spatial, K_neighbors=8)

get_laplacian(normalize=True)

create_featuregraph(obsm_name='X_pca', K_neighbors=8, name='namemod')

train(embd_dim=50, method=1, name1='name1', name2='name2', obsm_name_rna='X_pca', obsm_name_adt='X_pca', plot=True, model_save=False, model_save_dir='trained_models')

核心特点：输入维度为 modal2_target_dim（第二模态单维度），兼容合并后的流程

Pipelines

smoder.pipelines.mousebrain_h3k27ac.set_base_config(run_name='mousebrain_H3K27ac_run4')

smoder.pipelines.mousebrain_h3k27ac.set_analysis_params()

smoder.pipelines.mousebrain_h3k27ac.load_and_show_data(base_config, params)

smoder.pipelines.mousebrain_h3k27ac.init_model_and_preprocess(ref_dict, smo_dict, params)

smoder.pipelines.mousebrain_h3k27ac.feature_engineering_and_graph_build(model, params)

smoder.pipelines.mousebrain_h3k27ac.train_model(model, params, dim_rna, dim_modal2, base_config)

smoder.pipelines.mousebrain_h3k27ac.clean_anndata_for_save(adata)

清理AnnData中所有层级的特殊字符，避免h5ad保存报错

smoder.pipelines.mousebrain_h3k27ac.save_results(adata_result, model, params, base_config, dim_rna, dim_modal2)

smoder.pipelines.mousebrain_h3k27ac.main()

Preprocessing

RNA preprocessing

smoder.preprocessing.rna.filter_out_low_quality_data(adata, data_type='spatial')

Filter low-quality data for spatial or single-cell AnnData objects.

smoder.preprocessing.rna.process_single_cell(adata, ref_celltype_col='CellType')

单细胞数据初始处理（基础清洗，不含最终过滤步骤） 参数: 数据文件adata 返回: 初始处理后的AnnData对象

smoder.preprocessing.rna.process_single_cell_path(sc_path)

单细胞数据初始处理（基础清洗，不含最终过滤步骤） 参数: 数据文件路径 返回: 初始处理后的AnnData对象

smoder.preprocessing.rna.sanitize_filename(name)

替换文件名中的特殊字符，避免路径错误

smoder.preprocessing.rna.normalize_expression_matrix(matrix, target_sum)

对表达矩阵进行归一化处理

smoder.preprocessing.rna.normalize_single_cell(adata)

对筛选高变基因后的单细胞数据进行归一化

smoder.preprocessing.rna.process_spatial_data(adata, common_genes, hvgs)

处理空间转录组数据：筛选基因+归一化+log转换

smoder.preprocessing.rna.process_spatial_data_path(st_path, common_genes, hvgs)

处理空间转录组数据：筛选基因+归一化+log转换

smoder.preprocessing.rna.get_spatial_hvgs_only(st_path, common_genes, hvgs)

仅筛选高变基因，不进行其他处理

smoder.preprocessing.rna.select_hvgs(adata_ref, celltype_col, num_per_group=200)

smoder.preprocessing.rna.calculate_celltype_averages(adata_sc_norm, celltype_col, sample_id_col, target_sum, normalize)

计算细胞类型平均表达并可选归一化

smoder.preprocessing.rna.calculate_celltype_averages2(adata_sc_norm, celltype_col, target_sum, normalize)

计算细胞类型平均表达并可选归一化

Second-modality preprocessing

smoder.preprocessing.modality2.clr_normalization(matrix)

执行中心对数比（CLR）标准化：clr(x) = ln(x_i / 几何均值(x))

smoder.preprocessing.modality2.process_spatial_adt_data(adata, min_genes=20, min_cells=100)

读取数据→过滤低质量位点和蛋白→CLR标准化→保留空间坐标

smoder.preprocessing.modality2.process_spatial_adt_data_path(st_adt_path)

通过文件路径读取数据→过滤低质量位点和蛋白→CLR标准化→保留空间坐标

smoder.preprocessing.modality2.process_peak_data(adata, n_top_features=20000)

Process peak data with TF-IDF normalization and top-feature selection.

smoder.preprocessing.modality2.process_peak_data_path(peak_h5ad_path, n_top_features=20000)

Load peak data from file, then apply TF-IDF normalization and top-feature selection.

Postprocessing

Reconstruction

Postprocessing utilities for SMODER reconstruction.

This module provides omics_reconstruct for reconstructing selected RNA genes or second-modality gene and feature signals from trained SMODER embeddings.

The input spatial_path should point to a SMODER result AnnData file that contains spatial coordinates and encoder representations such as rna_encoder, peak_encoder, or adt_encoder.

smoder.postprocessing.reconstruction.set_random_seed(seed: int = 42) → None

Set NumPy and PyTorch random seeds.

smoder.postprocessing.reconstruction.normalize_coords(coords: numpy.ndarray) → numpy.ndarray

Min-max normalize spatial coordinates to [0, 1].

smoder.postprocessing.reconstruction.standardize_embedding(embedding_data: numpy.ndarray, train_size: int) → Tuple[torch.Tensor, sklearn.preprocessing.StandardScaler]

Z-score standardize embeddings using the training subset only.

smoder.postprocessing.reconstruction.lognorm_transform(expr_matrix: numpy.ndarray, target_sum: float = 10000.0) → numpy.ndarray

Apply total-count normalization followed by log1p transformation.

smoder.postprocessing.reconstruction.filter_valid_genes(adata: anndata.AnnData, target_genes: Sequence[str] | None) → list[str]

Return target genes/features that are present in adata.var_names.

smoder.postprocessing.reconstruction.load_align_data(expr_path: str, spatial_path: str) → Tuple[anndata.AnnData, anndata.AnnData]

Load expression and SMODER result AnnData files, then align common spots.

smoder.postprocessing.reconstruction.project_coords(coords: numpy.ndarray, n_angles: int = 100) → torch.Tensor

Project 2D spatial coordinates under multiple rotation angles.

class smoder.postprocessing.reconstruction.RNAFCModel(*args: Any, **kwargs: Any)

Bases: Module

Fully connected model for RNA gene reconstruction.

forward(x: torch.Tensor) → torch.Tensor

smoder.postprocessing.reconstruction.rna_run(adata_expr: anndata.AnnData, adata_spatial: anndata.AnnData, target_genes: Sequence[str] | None, hidden_dim: int, n_layers: int, epochs: int, lr: float, patience: int, encoder_key: str = 'rna_encoder', n_angles: int = 100, batch_size: int = 64, print_interval: int = 10, do_lognorm: bool = True, target_sum: float = 10000.0, device: str | None = None, seed: int = 42) → anndata.AnnData

Run RNA gene reconstruction.

smoder.postprocessing.reconstruction.second_modality_preprocess_single(expr: numpy.ndarray, coords: numpy.ndarray, k: int = 8, quantile: float = 0.8, support_thr: float = 0.3) → numpy.ndarray

Filter noisy signal using quantile thresholding and neighborhood support.

smoder.postprocessing.reconstruction.second_modality_preprocess_batch(adata_expr: anndata.AnnData, adata_spatial: anndata.AnnData, target_genes: Sequence[str], k: int = 8, quantile: float = 0.8, support_thr: float = 0.3) → anndata.AnnData

Apply neighborhood-aware preprocessing to selected second-modality features.

class smoder.postprocessing.reconstruction.DenseGCNConv(*args: Any, **kwargs: Any)

Bases: Module

Dense GCN layer used by second-modality reconstruction.

forward(x: torch.Tensor, adj: torch.Tensor) → torch.Tensor

class smoder.postprocessing.reconstruction.SecondModalityGCNModel(*args: Any, **kwargs: Any)

Bases: Module

GCN model for reconstructing second-modality gene/feature signals.

forward(x: torch.Tensor, adj: torch.Tensor) → torch.Tensor

smoder.postprocessing.reconstruction.build_spatial_adj(coords: numpy.ndarray, k: int = 12, device: str | None = None) → torch.Tensor

Build dense KNN adjacency matrix from spatial coordinates.

smoder.postprocessing.reconstruction.second_modality_run(adata_expr: anndata.AnnData, adata_spatial: anndata.AnnData, target_genes: Sequence[str] | None, hidden_dim: int, n_layers: int, epochs: int, lr: float, patience: int, encoder_key: str, omics_label: str = 'ATAC', spatial_k: int = 12, do_preprocess: bool = True, pre_k: int = 8, pre_quantile: float = 0.8, pre_support: float = 0.3, do_lognorm: bool = True, target_sum: float = 10000.0, device: str | None = None, seed: int = 42) → anndata.AnnData

Run second-modality reconstruction using a GCN model.

smoder.postprocessing.reconstruction.omics_reconstruct(omics_type: str, expr_path: str, spatial_path: str, target_genes: Sequence[str] | None, hidden_dim: int = 64, n_layers: int = 3, epochs: int = 500, lr: float = 0.0001, patience: int = 30, save_path: str | None = None, encoder_key: str | None = None, device: str | None = None, seed: int = 42, n_angles: int = 100, batch_size: int = 64, print_interval: int = 10, do_lognorm: bool = True, target_sum: float = 10000.0, spatial_k: int = 12, do_preprocess: bool | None = None, pre_k: int = 8, pre_quantile: float = 0.8, pre_support: float = 0.3) → anndata.AnnData

Reconstruct selected RNA or second-modality gene/feature signals.

Parameters:

• omics_type – One of "RNA", "ATAC", "PEAK", "EPIGENOMICS", "ADT", or "PROTEIN".

• expr_path – Path to an AnnData file containing the target expression/signal matrix.

• spatial_path – Path to a SMODER result AnnData file containing spatial coordinates and encoder representations.

• target_genes – Genes or features to reconstruct. If None, all features are used.

• encoder_key – Key in spatial_path.obsm used as model input. If None, a default is selected based on omics_type.

• save_path – Optional output path for saving the reconstructed AnnData object.

Returns:

Reconstructed AnnData object. .X stores denoised/reconstructed signals, .obsm["spatial"] stores spatial coordinates, and .layers["original_label"] stores the target labels used for fitting.

Return type:

AnnData

Visualization

Spatial visualization

Spatial visualization utilities for SMODER results.

smoder.visualization.spatial.get_spatial_xy(adata: anndata.AnnData, spatial_key: str = 'spatial', flip_y: bool = True) → tuple[numpy.ndarray, numpy.ndarray]

Return x and y coordinates from adata.obsm[spatial_key].

smoder.visualization.spatial.save_spatial_continuous(adata: anndata.AnnData, values: Sequence[float], out_path: str, title: str = '', spatial_key: str = 'spatial', flip_y: bool = True, point_size: float = 6, cmap: str = 'viridis', vmin: float | None = None, vmax: float | None = None, figsize: tuple[float, float] = (5, 5), dpi: int = 300) → None

Save a spatial heatmap for continuous values.

smoder.visualization.spatial.save_spatial_categorical(adata: anndata.AnnData, labels: Sequence[str], out_path: str, title: str = '', spatial_key: str = 'spatial', flip_y: bool = True, point_size: float = 6, cmap: str = 'tab20', figsize: tuple[float, float] = (6, 5), dpi: int = 300) → None

Save a spatial map for categorical labels.

smoder.visualization.spatial.get_cell_type_proportions(adata: anndata.AnnData, obsm_key: str = 'cell_type_proportions', obs_start_col: int | None = None, cell_type_names: Sequence[str] | None = None) → pandas.DataFrame

Extract cell-type proportion matrix from a SMODER result AnnData object.

Priority: 1. use adata.obsm[obsm_key] if available; 2. otherwise use adata.obs.iloc[:, obs_start_col:].

smoder.visualization.spatial.sanitize_filename(name: str) → str

Return a safe filename.

smoder.visualization.spatial.plot_cell_type_proportion_panel(adata: anndata.AnnData, out_path: str, obsm_key: str = 'cell_type_proportions', obs_start_col: int | None = None, cell_type_names: Sequence[str] | None = None, selected_cell_types: Sequence[str] | None = None, top_n: int | None = 12, ncols: int = 4, point_size: float = 4, cmap: str = 'viridis', vmin: float | None = None, vmax: float | None = None, title: str = 'Spatial heatmaps of cell-type proportions', spatial_key: str = 'spatial', flip_y: bool = True, dpi: int = 300) → pandas.DataFrame

Save a multi-panel figure of selected cell-type proportion heatmaps.

smoder.visualization.spatial.plot_all_cell_type_proportions(adata: anndata.AnnData, out_path: str, obsm_key: str = 'cell_type_proportions', obs_start_col: int | None = None, cell_type_names: Sequence[str] | None = None, ncols: int = 6, point_size: float = 2, cmap: str = 'viridis', vmin: float = 0, vmax: float = 1, title: str = 'Spatial heatmaps of cell-type proportions', spatial_key: str = 'spatial', flip_y: bool = True, dpi: int = 200) → pandas.DataFrame

Save one panel containing all cell-type proportion heatmaps.

smoder.visualization.spatial.plot_individual_cell_type_heatmaps(adata: anndata.AnnData, out_dir: str, obsm_key: str = 'cell_type_proportions', obs_start_col: int | None = None, cell_type_names: Sequence[str] | None = None, point_size: float = 6, cmap: str = 'viridis', spatial_key: str = 'spatial', flip_y: bool = True, dpi: int = 300) → pandas.DataFrame

Save one spatial heatmap for each cell type.

smoder.visualization.spatial.plot_embedding_spatial_clustering(adata: anndata.AnnData, out_path: str, embedding_key: str = 'embedding', cluster_key: str = 'smoder_cluster', method: str = 'leiden', resolution: float = 0.6, n_neighbors: int = 15, spatial_key: str = 'spatial', flip_y: bool = True, point_size: float = 6, dpi: int = 300) → anndata.AnnData

Cluster a learned embedding and save a spatial cluster map.

smoder.visualization.spatial.plot_reconstruction_heatmaps(recon_adata: anndata.AnnData, out_dir: str, prefix: str, title_prefix: str, spatial_key: str = 'spatial', flip_y: bool = True, point_size: float = 6, cmap: str = 'viridis', dpi: int = 300) → None

Save spatial heatmaps for all reconstructed genes/features in recon_adata.

Configuration

smoder.config.defaults.get_mousebrain_h3k27ac_base_config(run_name='mousebrain_H3K27ac_run4')

smoder.config.defaults.get_mousebrain_h3k27ac_params()