Skip to content

local_autocorr

Run local spatial autocorrelation for a GeoDataFrame.

Note

This is a wrapper function for the esda.Moran_Local from esda package, returning only the relevant data: p-values, local Moran's I, and quadrant places.

Parameters:

Name Type Description Default
gdf GeoDataFrame

The GeoDataFrame containing the spatial data.

 required
w W

The spatial weights object.

 required
feat str

The feature column to analyze.

 required
permutations int

number of random permutations for calculation of pseudo p_values.

 999
num_processes int

Number of cores to be used in the conditional randomisation. If -1, all available cores are used.

 1

Returns:

Type Description
Tuple[ndarray, ndarray, ndarray]

Tuple[np.ndarray, np.ndarray, np.ndarray]: A tuple containing: - p_sim: Array of pseudo p-values for each feature. - Is: Array of local Moran's I values. - q: Array of quadrant places for each feature.

Examples:

>>> from histolytics.data import hgsc_cancer_nuclei
>>> from histolytics.spatial_clust.autocorr import local_autocorr
>>> from histolytics.spatial_graph.graph import fit_graph
>>> from histolytics.utils.gdf import set_uid
>>> from histolytics.spatial_geom.shape_metrics import shape_metric
>>> # Load the HGSC cancer nuclei dataset
>>> nuc = hgsc_cancer_nuclei()
>>> neo = nuc[nuc["class_name"] == "neoplastic"]
>>> neo = set_uid(neo)
>>> neo = shape_metric(neo, ["area"])
>>> # Fit a spatial graph to the neoplastic nuclei
>>> w, _ = fit_graph(neo, "distband", threshold=100)
>>> # Calculate local Moran's I for the area feature
>>> pval, moran_i, quadrants = local_autocorr(neo, w, feat="area")
>>> print(moran_i)
    [ 0.32793505  0.07546211 -0.00902539 -0.05775879  0.13344124  0.57178879 ...
Source code in src/histolytics/spatial_clust/autocorr.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def local_autocorr(
    gdf: gpd.GeoDataFrame,
    w: libpysal.weights.W,
    feat: str,
    permutations: int = 999,
    num_processes: int = 1,
) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
    """Run local spatial autocorrelation for a GeoDataFrame.

    Note:
        This is a wrapper function for the `esda.Moran_Local` from `esda` package,
        returning only the relevant data: p-values, local Moran's I, and quadrant places.

    Parameters:
        gdf (gpd.GeoDataFrame):
            The GeoDataFrame containing the spatial data.
        w (libpysal.weights.W):
            The spatial weights object.
        feat (str):
            The feature column to analyze.
        permutations (int):
            number of random permutations for calculation of pseudo p_values.
        num_processes (int):
            Number of cores to be used in the conditional randomisation.
            If -1, all available cores are used.

    Returns:
        Tuple[np.ndarray, np.ndarray, np.ndarray]:
            A tuple containing:
            - p_sim: Array of pseudo p-values for each feature.
            - Is: Array of local Moran's I values.
            - q: Array of quadrant places for each feature.

    Examples:
        >>> from histolytics.data import hgsc_cancer_nuclei
        >>> from histolytics.spatial_clust.autocorr import local_autocorr
        >>> from histolytics.spatial_graph.graph import fit_graph
        >>> from histolytics.utils.gdf import set_uid
        >>> from histolytics.spatial_geom.shape_metrics import shape_metric
        >>> # Load the HGSC cancer nuclei dataset
        >>> nuc = hgsc_cancer_nuclei()
        >>> neo = nuc[nuc["class_name"] == "neoplastic"]
        >>> neo = set_uid(neo)
        >>> neo = shape_metric(neo, ["area"])
        >>> # Fit a spatial graph to the neoplastic nuclei
        >>> w, _ = fit_graph(neo, "distband", threshold=100)
        >>> # Calculate local Moran's I for the area feature
        >>> pval, moran_i, quadrants = local_autocorr(neo, w, feat="area")
        >>> print(moran_i)
            [ 0.32793505  0.07546211 -0.00902539 -0.05775879  0.13344124  0.57178879 ...
    """
    moran = esda.Moran_Local(
        gdf[feat],
        w,
        island_weight=np.nan,
        permutations=permutations,
        n_jobs=num_processes,
    )

    return moran.p_sim, moran.Is, moran.q