spatiomic.spatial¶

Make all spatial analysis classes available in the spatial submodule.

Warning

Methods in the spatial module are not yet GPU accelerated.

Classes¶

`autocorrelation`	Class to perform spatial autocorrelation analysis on a 2D image of clusters or an XYC image.
`bivariate_correlation`	Class to perform bivariate spatial correlation analysis on a 2D image of clusters and an XYC image.
`local_autocorrelation`	Class to perform local spatial autocorrelation analysis on a 2D image of clusters or an XYC image.
`local_heteroskedasticity`	Class to calculate local heteroskedasticity (LOSH) on a 2D image of clusters or an XYC image.

Functions¶

`neighborhood_offset`([neighborhood_type, order, ...])	Create a neighborhood offset array for a given neighborhood type and steps.
`spatial_weights`(data_shape, neighborhood_offset)	Create a spatial weights matrix from a given data shape and neighborhood offset.
`vicinity_composition`(data[, neighborhood_offset, ...])	Get the counts of neighboring clusters for each cluster in an image.
`vicinity_graph`(data[, ignore_identities, normalize, ...])	Construct a vicinity graph from a dataframe.

Package Contents¶

class spatiomic.spatial.autocorrelation¶

Class to perform spatial autocorrelation analysis on a 2D image of clusters or an XYC image.

predict(data, spatial_weights=None, method='moran', permutation_count=0, *args, **kwargs)¶

Perform spatial autocorrelation analysis on a 2D image of clusters or an XYC image.

Analyse the spatial autocorrelation of each cluster or each channel in the image using Moran’s I or Geary’s C.

Parameters:

data (NDArray) – The 2D image to perform autocorrelation analysis on.
spatial_weights (Optional[W], optional) – The spatial weights to use. If None, queen contiguity weights are generated based on the data shape using lat2W. Defaults to None.
method (Literal["moran", "geary"], optional) – The method to use. Defaults to “moran”.
permutation_count (int, optional) – The number of permutations to use for p-value calculation, 0 if no simulation is to be performed. Defaults to 0.
args (Any)
kwargs (dict)

Returns:

A DataFrame containing the Moran’s I analysis results for each cluster.

Return type:

pd.DataFrame

class spatiomic.spatial.bivariate_correlation¶

Class to perform bivariate spatial correlation analysis on a 2D image of clusters and an XYC image.

Usage:

data = my_clustered_image # 2d, integers representing clusters
channel_image = my_xyc_image # or one-hot encoded cluster image

channel_names = ["CD3", "CD4", "CD8", "CD20", "CD68"] # optional, defaults to channel indices

df_morans_i = so.spatial.bivariate_correlation.predict(
    data,
    channel_image,
    channel_names
    method="moran",
    permutation_count=0,
)

predict(data, channel_image, channel_names=None, spatial_weights=None, method='moran', permutation_count=0, *args, **kwargs)¶

Perform spatial correlation analysis on a 2D image of clusters and an XYC image.

This analysis allows you to determine which clusters spatially correlate with which channels in the neighboring pixels of the image.

Parameters:

data (NDArray) – The clustered image.
channel_image (NDArray) – The XYC image to correlate with the clusters.
channel_names (Optional[List[str]], optional) – The names of the channels in the XYC image. Defaults to None.
spatial_weights (Optional[W], optional) – The spatial weights to use. If None, queen contiguity weights are generated based on the data shape using lat2W. Defaults to None.
method (Literal["moran", "lee"], optional) – The method to use for spatial correlation analysis.
permutation_count (int, optional) – The number of permutations to use for p-value calculation, 0 if no simulation is to be performed. Defaults to 0.
args (Any)
kwargs (dict)

Returns:

A DataFrame containing the Moran’s I analysis results for each cluster.

Return type:

pd.DataFrame

class spatiomic.spatial.local_autocorrelation¶

Class to perform local spatial autocorrelation analysis on a 2D image of clusters or an XYC image.

classmethod predict(data, spatial_weights=None, method='moran', permutation_count=0, *args, **kwargs)¶

Perform local spatial autocorrelation analysis on a 2D image of clusters.

Parameters:

data (NDArray) – The data to calculate the local autocorrelation on.
spatial_weights (Optional[W], optional) – The spatial weights to use. If None, queen contiguity weights are generated based on the data shape using lat2W. Defaults to None.
method (Literal["moran", "getisord"], optional) – The method to use for local spatial autocorrelation analysis. Defaults to “moran”.
permutation_count (int, optional) – The number of permutations to use for the pseudo-p-value calculation. Only used if method is “moran”. Defaults to 0.
args (Any)
kwargs (dict)

Returns:

The results of the local spatial autocorrelation analysis.

Return type:

pd.DataFrame

class spatiomic.spatial.local_heteroskedasticity¶

Class to calculate local heteroskedasticity (LOSH) on a 2D image of clusters or an XYC image.

classmethod predict(data, channel_names=None, spatial_weights=None, inference='chi-square', **kwargs)¶

Perform local heteroskedasticity (LOSH) analysis on a 2D image of clusters or an XYC image.

Parameters:

data (NDArray) – The input data. If the data is a 2D array, it is assumed to be a clustered image where each value represents a cluster label (integer). If the data is a 3D array (XYC), it is assumed to be a multi-channel image.
channel_names (Optional[List[str]], optional) – Names for each channel. Defaults to None.
spatial_weights (Optional[W], optional) – The spatial weights to use. If None, queen contiguity weights are generated based on the data shape using lat2SW. Defaults to None.
inference (Literal["chi-square", "permutation"], optional) – Method for p-value inference in LOSH. Defaults to “chi-square”.
**kwargs – Additional keyword arguments to be passed to the esda.losh.LOSH class.

Returns:

DataFrame containing LOSH values and p-values for each channel/cluster.: Columns are ‘losh’ and ‘p_value’. Index is based on channel_names if provided, otherwise a default RangeIndex.

Return type:

pd.DataFrame

Raises:

ValueError – If input data dimensions are not 2D or 3D.
ValueError – If input data is a clustered image but not of integer type.
ValueError – If input data is a clustered image and contains negative values.
ValueError – If channel_names are provided for a clustered image (2D input).
ValueError – If channel_names are provided for a 3D image (XYC) but do not match the number of channels.

spatiomic.spatial.neighborhood_offset(neighborhood_type='queen', order=1, exclude_inner_order=0)¶

Create a neighborhood offset array for a given neighborhood type and steps.

For queen neighborhoods, the order parameter defines the maximum Chebyshev distance from the focal cell to the neighbor. For rook neighborhoods, the order parameter defines the maximum Manhattan distance from the focal cell to the neighbor. For circle neighborhoods, the order parameter defines the radius from the focal cell to the neighbor.

E.g., for a queen neighborhood with order=1 and exclude_inner_order=0, the neighborhood offset array would be: array([[-1, -1],

[-1, 0], [-1, 1], [ 0, -1], [ 0, 1], [ 1, -1], [ 1, 0], [ 1, 1]])

Parameters:

neighborhood_type (Literal["queen", "rook", "circle"], optional) – The type of neighborhood to create. Defaults to “queen”.
order (int, optional) – The order of the neighborhood. Defaults to 1.
exclude_inner_order (int, optional) – The inner order to exclude from the neighborhood. Defaults to 0.

Returns:

The neighborhood offset array.

Return type:

NDArray

spatiomic.spatial.spatial_weights(data_shape, neighborhood_offset)¶

Create a spatial weights matrix from a given data shape and neighborhood offset.

from spatiomic.spatial import neighborhood_offset, spatial_weights

data_shape = (3, 3)
neighborhood_offset = neighborhood_offset(
    neighborhood_type="queen",
    steps=5,
    exclude_inner_steps=2,
)
spatial_weights_matrix = spatial_weights(
    data_shape,
    neighborhood_offset,
)

Parameters:

data_shape (tuple[int, int]) – The shape of the data.
neighborhood_offset (NDArray) – The neighborhood offset array.

Returns:

The spatial weights matrix.

Return type:

NDArray

spatiomic.spatial.vicinity_composition(data, neighborhood_offset=pixel_level_queen_neighborhood_offset, ignore_identities=True, ignore_repeated=False, permutations=None, use_gpu=False, seed=0, n_jobs=-1)¶

Get the counts of neighboring clusters for each cluster in an image.

Parameters:

data (np.ndarray) – The image of clusters.
neighborhood_offset (np.ndarray, optional) – The neighborhood offset array. Can be created using the neighborhood_offset function. Defaults to pixel_level_queen_neighborhood_offset.
ignore_identities (bool, optional) – Whether to ignore pixels from the same cluster in the vicinity. Defaults to True.
ignore_repeated (bool, optional) – Whether to just count pixels that are in the vicinity of multiple pixels from the same cluster once. Defaults to False.
permutations (int, optional) – The number of permutations to use for p-value calculation, 0 if no simulation is to be performed. Defaults to None.
use_gpu (bool, optional) – Whether to use GPU for calculations. Defaults to False.
seed (int, optional) – The random seed to use for the permutations. Defaults to 0.
n_jobs (int, optional) – Number of parallel jobs to use for permutation calculations. Defaults to -1.

Returns:

A DataFrame containing the counts of neighbors from each: cluster for each cluster. If permutations is not None, a tuple of two DataFrames containing the counts of neighbors from each cluster for each cluster and the p-values for each cluster.

Return type:

Union[pd.DataFrame, [pd.DataFrame, pd.DataFrame]]

spatiomic.spatial.vicinity_graph(data, ignore_identities=True, normalize=True, weighted=True, directed=True)¶

Construct a vicinity graph from a dataframe.

Parameters:

data (Union[NDArray, pd.DataFrame]) – The dataframe or its values where each row is a cluster and all columns are the counts of clusters in the vicinity.
ignore_identities (bool, optional) – Whether to ignore pixels from the same cluster in the vicinity. Defaults to True.
normalize (bool, optional) – Whether to normalize the counts in the vicinity. Defaults to True.
weighted (bool, optional) – Whether to weighted the edges by the counts in the vicinity. Defaults to True.
directed (bool, optional) – Whether to construct a directed graph. Defaults to True.

Returns:

The spatial vicinity graph.

Return type:

Graph