spatiomic.spatial ================= .. py:module:: spatiomic.spatial .. autoapi-nested-parse:: Make all spatial analysis classes available in the spatial submodule. .. warning:: Methods in the spatial module are not yet GPU accelerated. Classes ------- .. autoapisummary:: spatiomic.spatial.autocorrelation spatiomic.spatial.bivariate_correlation spatiomic.spatial.local_autocorrelation spatiomic.spatial.local_heteroskedasticity Functions --------- .. autoapisummary:: spatiomic.spatial.neighborhood_offset spatiomic.spatial.spatial_weights spatiomic.spatial.vicinity_composition spatiomic.spatial.vicinity_graph Package Contents ---------------- .. py:class:: autocorrelation Class to perform spatial autocorrelation analysis on a 2D image of clusters or an XYC image. .. py:method:: 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. :param data: The 2D image to perform autocorrelation analysis on. :type data: NDArray :param spatial_weights: The spatial weights to use. If None, queen contiguity weights are generated based on the data shape using `lat2W`. Defaults to None. :type spatial_weights: Optional[W], optional :param method: The method to use. Defaults to "moran". :type method: Literal["moran", "geary"], optional :param permutation_count: The number of permutations to use for p-value calculation, 0 if no simulation is to be performed. Defaults to 0. :type permutation_count: int, optional :returns: A DataFrame containing the Moran's I analysis results for each cluster. :rtype: pd.DataFrame .. py:class:: bivariate_correlation Class to perform bivariate spatial correlation analysis on a 2D image of clusters and an XYC image. Usage: .. code-block:: python 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, ) .. py:method:: 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. :param data: The clustered image. :type data: NDArray :param channel_image: The XYC image to correlate with the clusters. :type channel_image: NDArray :param channel_names: The names of the channels in the XYC image. Defaults to None. :type channel_names: Optional[List[str]], optional :param spatial_weights: The spatial weights to use. If None, queen contiguity weights are generated based on the data shape using `lat2W`. Defaults to None. :type spatial_weights: Optional[W], optional :param method: The method to use for spatial correlation analysis. :type method: Literal["moran", "lee"], optional :param permutation_count: The number of permutations to use for p-value calculation, 0 if no simulation is to be performed. Defaults to 0. :type permutation_count: int, optional :returns: A DataFrame containing the Moran's I analysis results for each cluster. :rtype: pd.DataFrame .. py:class:: local_autocorrelation Class to perform local spatial autocorrelation analysis on a 2D image of clusters or an XYC image. .. py:method:: predict(data, spatial_weights = None, method = 'moran', permutation_count = 0, *args, **kwargs) :classmethod: Perform local spatial autocorrelation analysis on a 2D image of clusters. :param data: The data to calculate the local autocorrelation on. :type data: NDArray :param spatial_weights: The spatial weights to use. If None, queen contiguity weights are generated based on the data shape using `lat2W`. Defaults to None. :type spatial_weights: Optional[W], optional :param method: The method to use for local spatial autocorrelation analysis. Defaults to "moran". :type method: Literal["moran", "getisord"], optional :param permutation_count: The number of permutations to use for the pseudo-p-value calculation. Only used if method is "moran". Defaults to 0. :type permutation_count: int, optional :returns: The results of the local spatial autocorrelation analysis. :rtype: pd.DataFrame .. py:class:: local_heteroskedasticity Class to calculate local heteroskedasticity (LOSH) on a 2D image of clusters or an XYC image. .. py:method:: predict(data, channel_names = None, spatial_weights = None, inference = 'chi-square', **kwargs) :classmethod: Perform local heteroskedasticity (LOSH) analysis on a 2D image of clusters or an XYC image. :param data: 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. :type data: NDArray :param channel_names: Names for each channel. Defaults to None. :type channel_names: Optional[List[str]], optional :param spatial_weights: The spatial weights to use. If None, queen contiguity weights are generated based on the data shape using `lat2SW`. Defaults to None. :type spatial_weights: Optional[W], optional :param inference: Method for p-value inference in LOSH. Defaults to "chi-square". :type inference: Literal["chi-square", "permutation"], optional :param \*\*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. :rtype: pd.DataFrame :raises ValueError: If input data dimensions are not 2D or 3D. :raises ValueError: If input data is a clustered image but not of integer type. :raises ValueError: If input data is a clustered image and contains negative values. :raises ValueError: If `channel_names` are provided for a clustered image (2D input). :raises ValueError: If `channel_names` are provided for a 3D image (XYC) but do not match the number of channels. .. py:function:: 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]]) :param neighborhood_type: The type of neighborhood to create. Defaults to "queen". :type neighborhood_type: Literal["queen", "rook", "circle"], optional :param order: The order of the neighborhood. Defaults to 1. :type order: int, optional :param exclude_inner_order: The inner order to exclude from the neighborhood. Defaults to 0. :type exclude_inner_order: int, optional :returns: The neighborhood offset array. :rtype: NDArray .. py:function:: spatial_weights(data_shape, neighborhood_offset) Create a spatial weights matrix from a given data shape and neighborhood offset. .. code-block:: python 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, ) :param data_shape: The shape of the data. :type data_shape: tuple[int, int] :param neighborhood_offset: The neighborhood offset array. :type neighborhood_offset: NDArray :returns: The spatial weights matrix. :rtype: NDArray .. py:function:: 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. :param data: The image of clusters. :type data: np.ndarray :param neighborhood_offset: The neighborhood offset array. Can be created using the `neighborhood_offset` function. Defaults to `pixel_level_queen_neighborhood_offset`. :type neighborhood_offset: np.ndarray, optional :param ignore_identities: Whether to ignore pixels from the same cluster in the vicinity. Defaults to True. :type ignore_identities: bool, optional :param ignore_repeated: Whether to just count pixels that are in the vicinity of multiple pixels from the same cluster once. Defaults to False. :type ignore_repeated: bool, optional :param permutations: The number of permutations to use for p-value calculation, 0 if no simulation is to be performed. Defaults to None. :type permutations: int, optional :param use_gpu: Whether to use GPU for calculations. Defaults to False. :type use_gpu: bool, optional :param seed: The random seed to use for the permutations. Defaults to 0. :type seed: int, optional :param n_jobs: Number of parallel jobs to use for permutation calculations. Defaults to -1. :type n_jobs: int, optional :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. :rtype: Union[pd.DataFrame, [pd.DataFrame, pd.DataFrame]] .. py:function:: vicinity_graph(data, ignore_identities = True, normalize = True, weighted = True, directed = True) Construct a vicinity graph from a dataframe. :param data: The dataframe or its values where each row is a cluster and all columns are the counts of clusters in the vicinity. :type data: Union[NDArray, pd.DataFrame] :param ignore_identities: Whether to ignore pixels from the same cluster in the vicinity. Defaults to True. :type ignore_identities: bool, optional :param normalize: Whether to normalize the counts in the vicinity. Defaults to True. :type normalize: bool, optional :param weighted: Whether to weighted the edges by the counts in the vicinity. Defaults to True. :type weighted: bool, optional :param directed: Whether to construct a directed graph. Defaults to True. :type directed: bool, optional :returns: The spatial vicinity graph. :rtype: Graph