spamosaic.build_graph

spamosaic.build_graph.Cal_Spatial_Net(adata, rad_cutoff=None, k_cutoff=None, max_neigh=50, model='Radius', verbose=True)

Construct spatial graph from spatial coordinates using radius or kNN method.

Parameters:

• adata (AnnData) – Input annotated data.

• rad_cutoff (float, optional) – Distance cutoff for radius-based graph.

• k_cutoff (int, optional) – Number of neighbors for kNN-based graph.

• max_neigh (int) – Maximum number of neighbors to consider.

• model (str) – Type of graph construction: ‘Radius’ or ‘KNN’.

• verbose (bool) – Whether to print debug info.

Return type:

None

Notes

On success, adds the adjacency matrix to adata.uns['adj'] (SciPy sparse matrix).

spamosaic.build_graph.build_intra_graph(ads, rad_cutoff, knns)

Construct intra-batch graphs for a list of AnnData objects.

Parameters:

• ads (List[AnnData]) – List of spatial AnnData objects.

• rad_cutoff (float) – Radius cutoff for spatial neighbor graph.

• knns (List[int]) – List of maximum neighbors per AnnData.

spamosaic.build_graph.build_mnn_graph(bridge_ads, test_ads, use_rep, batch_key, knn_base=10, auto_knn=False, auto_thr=0.8, rmv_outlier=False, contamination='auto', seed=1234)

Build a mutual nearest neighbor (MNN) graph within a single modality.

This function constructs a set of matched cell pairs across batches (MNNs), including both bridge-to-bridge and bridge-to-single relationships, based on specified embeddings. Optionally supports automatic KNN sizing and outlier removal.

Parameters:

• bridge_ads (list of AnnData) – List of AnnData objects from bridge batches (i.e., batches with multiple modalities).

• test_ads (list of AnnData) – List of AnnData objects from test batches (i.e., batches with a single modality).

• use_rep (str) – Key in .obsm indicating the representation to use for MNN search.

• batch_key (str) – Column in .obs used to identify the batch name (for logging purposes).

• knn_base (int, default=10) – Base number of neighbors for KNN search.

• auto_knn (bool, default=False) – Whether to automatically adjust KNN size based on batch sizes.

• auto_thr (float, default=0.8) – Size ratio threshold for determining asymmetric KNNs in auto_knn mode.

• rmv_outlier (bool, default=False) – Whether to apply spatial outlier removal using Isolation Forest.

• contamination (str or float, default='auto') – Proportion of outliers when using Isolation Forest.

• seed (int, default=1234) – Random seed used by the Isolation Forest or other stochastic operations.

Returns:

A set of MNN cell barcode pairs across batches.

Return type:

Set[Tuple[str, str]]

spamosaic.build_graph.determine_kSize(adi, adj, knn_base, auto_thr)

Dynamically determine the number of nearest neighbors for KNN search between two datasets of potentially imbalanced sizes.

This function adjusts the KNN size based on the relative number of observations between adi and adj. If the dataset sizes are sufficiently similar (i.e., ratio >= auto_thr), both sides use the same base KNN. Otherwise, the smaller dataset uses a scaled-down KNN count to balance the search.

Parameters:

• adi (AnnData) – First AnnData object.

• adj (AnnData) – Second AnnData object.

• knn_base (int) – Base number of nearest neighbors.

• auto_thr (float) – Size similarity threshold (e.g., 0.8). If the ratio of smaller to larger dataset exceeds this, no scaling is applied.

Returns:

Tuple of (knn_adi, knn_adj) representing KNN sizes for each dataset.

Return type:

Tuple[int, int]

spamosaic.build_graph.remove_outlier(mnn_set, ad1, ad2, contamination='auto')

Remove outlier cell pairs from an MNN set based on spatial distance patterns.

This function uses an Isolation Forest model to detect and remove spatial outlier cell pairs from a set of mutual nearest neighbors (MNNs). It constructs a feature matrix based on spatial coordinates from both datasets and their differences, then filters out pairs classified as outliers.

Parameters:

• mnn_set (set of tuple[str, str]) – Set of MNN cell pairs represented by (cell_id_1, cell_id_2).

• ad1 (AnnData) – First AnnData object containing ‘spatial’ in .obsm.

• ad2 (AnnData) – Second AnnData object containing ‘spatial’ in .obsm.

• contamination (str or float, default='auto') – The amount of contamination (i.e., expected proportion of outliers) used to define the threshold in the Isolation Forest. Follows scikit-learn’s format.

Returns:

Filtered MNN set with spatial outliers removed.

Return type:

set of tuple[str, str]

Functions

spamosaic.build_graph.Cal_Spatial_Net	Construct spatial graph from spatial coordinates using radius or kNN method.
spamosaic.build_graph.build_intra_graph	Construct intra-batch graphs for a list of AnnData objects.
spamosaic.build_graph.build_mnn_graph	Build a mutual nearest neighbor (MNN) graph within a single modality.
spamosaic.build_graph.determine_kSize	Dynamically determine the number of nearest neighbors for KNN search between two datasets of potentially imbalanced sizes.
spamosaic.build_graph.remove_outlier	Remove outlier cell pairs from an MNN set based on spatial distance patterns.