getis_ord#

getis_ord(domain, label_name, population=None, include_boundaries=None, exclude_boundaries=None, boundary_exclude_distance=0, distance_weight_function=None, network_kwargs={'max_edge_distance': inf, 'min_edge_distance': 0, 'network_type': 'Delaunay'}, alpha=0.05, add_local_value_as_label=True, local_getis_label_name=None)#

Calculate the local Getis-Ord G* statistic for spatial autocorrelation of a continuous label.

The Getis-Ord G* statistic is a measure of spatial autocorrelation that identifies hotspots and coldspots in the spatial distribution of a continuous label. The local Getis-Ord G* statistic is calculated for each object in the domain and the z-scores and p-values for each object are returned.

Postive z-scores indicate clustering of high values (hotspots) and negative z-scores indicate clustering of low values (coldspots).

The p-values are adjusted for multiple comparisons using the Bonferroni procedure. Local Getis-Ord G* values are added as labels to the domain if add_local_value_as_label is True.

Parameters:
domainobject

A muspan domain object.

label_namestr

The name of the label to be analysed. Must refer to a continuous label, not a categorical one.

populationlist or np.ndarray or query-like

The population of objects or a query to select objects.

include_boundarieslist, np.ndarray or query-like or None, optional

Boundaries to include or None to include all.

exclude_boundarieslist, np.ndarray or query-like or None, optional

Boundaries to exclude or None to exclude none.

boundary_exclude_distancefloat, optional

Distance to exclude around boundaries, default is 0.

distance_weight_functioncallable or None, optional

Function to weight distances, default f(x) = 1.

network_kwargsdict, optional

Dictionary of network generation parameters, default is {‘network_type’: ‘Delaunay’, ‘min_edge_distance’: 0, ‘max_edge_distance’: np.inf}.

alphafloat, optional

Significance level for null rejection, default is 0.05.

add_local_value_as_labelbool, optional

Whether to add the local Getis-Ord values as labels in the domain. Default is True.

local_getis_label_namestr, optional

Name for the local Getis-Ord label. If not specified, this will default to ‘Local Getis Ord - {label_name}’, where {label_name} is the label specified above.

Returns:
local_getis_ord_zscorenumpy.ndarray

Array of local Getis-Ord z-scores for each object.

local_getis_ord_pvalsnumpy.ndarray

Array of adjusted p-values for each object.

object_indicesnumpy.ndarray

Array of object indices used in the analysis.

Raises:
ValueError

If the label does not exist or is not continuous, or if the distance_weight_function is not callable.

Warning

UserWarning

If the number of objects is less than 30, indicating potential issues with statistical validity.

Notes

For more information, see this reference.

Examples

Minimal example of calculating local Getis-Ord G* statistic for a continuous label:

import muspan as ms

# load example domain
domain = ms.datasets.load_example_domain('Mouse-Colon-Carcinoma')

# compute global and local Moran's I for the 'CD4' label
local_getis_ord_zscore, local_getis_ord_pvals, object_ids = ms.spatial_statistics.getis_ord(domain,
                                                                                            label_name='CD4',
                                                                                            add_local_value_as_label=True,
                                                                                            local_getis_label_name='local Getis CD4')

# visualise the domain colored by the local Moran's I z-score for 'CD4'
ms.visualise.visualise(domain,color_by='local Getis CD4')
On this page