esda.Moran_Local¶

class esda.Moran_Local(y, w, transformation='r', permutations=999, geoda_quads=False, n_jobs=1, keep_simulations=True, seed=None, island_weight=0, alternative=None)[source]¶

Local Moran Statistics.

Parameters:¶

y : array¶: (n,1), attribute array
w : W | Graph¶: spatial weights instance as W or Graph aligned with y
transformation : {'R', 'B', 'D', 'U', 'V'}¶: weights transformation, default is row-standardized “r”. Other options include “B”: binary, “D”: doubly-standardized, “O”: restore original transformation (applicable only if w is passed as W), “V”: variance-stabilizing.
permutations : int¶: number of random permutations for calculation of pseudo p_values
geoda_quads : boolean¶: (default=False) If True use GeoDa scheme: HH=1, LL=2, LH=3, HL=4 If False use PySAL Scheme: HH=1, LH=2, LL=3, HL=4
n_jobs : int¶: Number of cores to be used in the conditional randomisation. If -1, all available cores are used.
keep_simulations : Boolean¶: (default=True) If True, the entire matrix of replications under the null is stored in memory and accessible; otherwise, replications are not saved
seed : None/int¶: Seed to ensure reproducibility of conditional randomizations. Must be set here, and not outside of the function, since numba does not correctly interpret external seeds nor numpy.random.RandomState instances.
island_weight=0¶: value to use as a weight for the “fake” neighbor for every island. If numpy.nan, will propagate to the final local statistic depending on the stat_func. If 0, then the lag is always zero for islands.

y[source]¶

original variable

Type:¶: array

w[source]¶

original w object

Type:¶: W | Graph

z[source]¶

zero-mean, unit standard deviation normalized y

Type:¶: array

permutations[source]¶

number of random permutations for calculation of pseudo p_values

Type:¶: int

Is[source]¶

local Moran’s I values

Type:¶: array

q[source]¶

(if permutations>0) values indicate quandrant location 1 HH, 2 LH, 3 LL, 4 HL

Type:¶: array

sim[source]¶

(if permutations>0) I values for permuted samples

Type:¶: array (permutations by n)

p_sim[source]¶

(if permutations>0) p-values based on permutations (one-sided) null: spatial randomness alternative: the observed Ii is further away or extreme from the median of simulated values. It is either extremely high or extremely low in the distribution of simulated Is.

Type:¶: array

EI_sim[source]¶

(if permutations>0) average values of local Is from permutations

Type:¶: array

VI_sim[source]¶

(if permutations>0) variance of Is from permutations

Type:¶: array

EI[source]¶

analytical expectation of Is under total permutation, from [Anselin, 1995]. Is the same at each site, and equal to the expectation of I itself when transformation=’r’. We recommend using EI_sim, not EI, for analysis. This EI is only provided for reproducibility.

Type:¶: array

VI[source]¶

analytical variance of Is under total permutation, from [Anselin, 1995]. Varies according only to cardinality. We recommend using VI_sim, not VI, for analysis. This VI is only provided for reproducibility.

Type:¶: array

EIc[source]¶

analytical expectation of Is under conditional permutation, from [Sokal et al., 1998]. Varies strongly by site, since it conditions on z_i. We recommend using EI_sim, not EIc, for analysis. This EIc is only provided for reproducibility.

Type:¶: array

VIc[source]¶

analytical variance of Is under conditional permutation, from [Sokal et al., 1998]. Varies strongly by site, since it conditions on z_i. We recommend using VI_sim, not VIc, for analysis. This VIc is only provided for reproducibility.

Type:¶: array

seI_sim[source]¶

(if permutations>0) standard deviations of Is under permutations.

Type:¶: array

z_sim[source]¶

(if permutations>0) standardized Is based on permutations

Type:¶: arrray

p_z_sim[source]¶

(if permutations>0) p-values based on standard normal approximation from permutations (one-sided) for two-sided tests, these values should be multiplied by 2

Type:¶: array

n_jobs[source]¶

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

Type:¶: int

keep_simulations[source]¶

(default=True) If True, the entire matrix of replications under the null is stored in memory and accessible; otherwise, replications are not saved

Type:¶: Boolean

seed[source]¶

Seed to ensure reproducibility of conditional randomizations. Must be set here, and not outside of the function, since numba does not correctly interpret external seeds nor numpy.random.RandomState instances.

Type:¶: None/int

alternative[source]¶

The alternative hypothesis for conditional randomization. See crand.crand() for complete description.

Type:¶: None | str = None

Notes

For technical details see [Anselin, 1995].

Examples

>>> import libpysal, numpy
>>> numpy.random.seed(10)
>>> w = libpysal.io.open(libpysal.examples.get_path("desmith.gal")).read()
>>> f = libpysal.io.open(libpysal.examples.get_path("desmith.txt"))
>>> y = np.array(f.by_col['z'])
>>> from esda import Moran_Local
>>> lm = Moran_Local(
...     y,
...     w,
...     transformation="r",
...     permutations=99,
...     seed=12345,
...     alternative="two-sided",
... )
>>> lm.q
array([4, 4, 4, 2, 3, 3, 1, 4, 3, 3])
>>> lm.p_z_sim[0]
np.float64(0.24226691753791402)
>>> lm = Moran_Local(
...     y,
...     w,
...     transformation="r",
...     permutations=99,
...     geoda_quads=True,
...     seed=12345,
...     alternative="two-sided",
... )
>>> lm.q
array([4, 4, 4, 3, 2, 2, 1, 4, 2, 2])
>>> lm.p_z_sim[0]
np.float64(0.24226691753791402)

Methods

`by_col`(df, cols[, w, inplace, pvalue, outvals])	Function to compute a Moran_Local statistic on a dataframe.
`explore`(gdf[, crit_value])	Create interactive map of LISA indicators
`get_cluster_labels`([crit_value])	Return LISA cluster labels for each observation.
`plot`(gdf[, crit_value])	Create static map of LISA indicators
`plot_combination`(gdf, attribute[, ...])	Produce three-plot visualisation of Moran Scatteprlot, LISA cluster and Choropleth maps, with Local Moran region and quadrant masking
`plot_scatter`([crit_value, ax, scatter_kwds, ...])	Plot a Moran scatterplot with optional coloring for significant points.

classmethod by_col(df, cols, w=None, inplace=False, pvalue='sim', outvals=None, **stat_kws)[source]¶

Function to compute a Moran_Local statistic on a dataframe.

Parameters:¶

df : pandas.DataFrame¶: a pandas dataframe with a geometry column
cols : string or list of string¶: name or list of names of columns to use to compute the statistic
w : W | Graph¶: spatial weights instance as W or Graph aligned with the dataframe. If not provided, this is searched for in the dataframe’s metadata
inplace : bool¶: a boolean denoting whether to operate on the dataframe inplace or to return a series contaning the results of the computation. If operating inplace, the derived columns will be named ‘column_moran_local’
pvalue : string¶: a string denoting which pvalue should be returned. Refer to the the Moran_Local statistic’s documentation for available p-values
outvals : list of strings¶: list of arbitrary attributes to return as columns from the Moran_Local statistic
**stat_kws : dict¶: options to pass to the underlying statistic. For this, see the documentation for the Moran_Local statistic.

Returns:¶

If inplace, None, and operation is conducted on dataframe
in memory. Otherwise, returns a copy of the dataframe with
the relevant columns attached.

explore(gdf, crit_value=0.05, **kwargs)[source]¶

Create interactive map of LISA indicators

Parameters:¶

gdf : geopandas.GeoDataFrame¶: geodataframe used to conduct the local Moran analysis
crit_value : float, optional¶: critical value to determine statistical significance, by default 0.05
kwargs : dict, optional¶: additional keyword arguments passed to the geopandas explore method

Returns:¶

interactive map with LISA clusters

Return type:¶

Folium.Map

get_cluster_labels(crit_value=0.05)[source]¶

Return LISA cluster labels for each observation.

Parameters:¶

crit_value : float, optional¶: crititical significance value for statistical inference, by default 0.05

Returns:¶

an array of cluster labels aligned with the input data used to conduct the local Moran analysis

Return type:¶

numpy.array

plot(gdf, crit_value=0.05, **kwargs)[source]¶

Create static map of LISA indicators

Parameters:¶

gdf : geopandas.GeoDataFrame¶: geodataframe used to conduct the local Moran analysis
crit_value : float, optional¶: critical value to determine statistical significance, by default 0.05
kwargs : dict, optional¶: additional keyword arguments passed to the geopandas explore method

Returns:¶

matplotlib axis

Return type:¶

plot_combination(gdf, attribute, crit_value=0.05, region_column=None, mask=None, mask_color='#636363', quadrant=None, legend=True, scheme='Quantiles', cmap='YlGnBu', figsize=(15, 4), scatter_kwds=None, fitline_kwds=None, legend_kwds=None, losh_scaling_factor=False, losh_inference=None, a=2)[source]¶

Produce three-plot visualisation of Moran Scatteprlot, LISA cluster and Choropleth maps, with Local Moran region and quadrant masking

Parameters:¶

gdf : geopandas.GeoDataFrame¶: geodataframe used to conduct the local Moran analysis
attribute : str¶: Column name of attribute which should be depicted in Choropleth map.
crit_value : float, optional¶: critical value to determine statistical significance, by default 0.05
region_column : string, optional¶: Column name containing mask region of interest, by default None
mask : str, float, int, optional¶: Identifier or name of the region to highlight, by default None Use the same dtype to specifiy as in original dataset.
mask_color : str, optional¶: Color of mask, by default ‘#636363’.
quadrant : int, optional¶: Quadrant 1-4 in scatterplot masking values in LISA cluster and Choropleth maps, by default None
figsize : tuple, optional¶: W, h of figure, by default (15,4)
legend : boolean, optional¶: If True, legend for maps will be depicted, by default True
scheme : str, optional¶: Name of mapclassify classifier to be used, by default ‘Quantiles’
cmap : str, optional¶: Name of matplotlib colormap used for plotting the Choropleth. By default ‘YlGnBu’.
scatter_kwds : keyword arguments, optional¶: Keywords used for creating and designing the scatter points, by default None.
fitline_kwds : keyword arguments, optional¶: Keywords used for creating and designing the moran fitline in the scatterplot, by default None.
legend_kwds : dict¶: Keyword arguments passed to geopandas.GeodataFrame.plot legend_kwds allowing repositioning of the legend in LISA cluster plot and choropleth.
losh_scaling_factor : bool | int | float, by default False¶: Scale the scatterplot observations by LOSH. When set to a number, it is treated as the multiplicative factor applied to exp(LOSH.Hi) when converting LOSH values into marker areas.
losh_inference : str, optional¶: Inference method for LOSH. See LOSH for supported options. Applies only if losh_scaling_factor is not False.
a : int or float, default=2¶: Residual exponent passed to esda.losh.LOSH.fit(). The default corresponds to a variance-based LOSH measure. Applies only if losh_scaling_factor is not False.

Returns:¶

axs

Return type:¶

array of Matplotlib axes

plot_scatter(crit_value=0.05, ax=None, scatter_kwds=None, fitline_kwds=None, losh_scaling_factor=False, losh_inference=None, a=2)[source]¶

Plot a Moran scatterplot with optional coloring for significant points.

Parameters:¶

crit_value : float, optional¶: Critical value to determine statistical significance, by default 0.05.
ax : matplotlib.axes.Axes, optional¶: Pre-existing axes for the plot, by default None.
scatter_kwds : dict, optional¶: Additional keyword arguments for scatter plot, by default None.
fitline_kwds : dict, optional¶: Additional keyword arguments for fit line, by default None.
losh_scaling_factor : bool | int | float, by default False¶: Scale the observations by LOSH. When set to a number, it is treated as the multiplicative factor applied to exp(LOSH.Hi) when converting LOSH values into marker areas.
losh_inference : str, optional¶: Inference method for LOSH. See LOSH for supported options. Applies only if losh_scaling_factor is not False.
a : int or float, default=2¶: Residual exponent passed to esda.losh.LOSH.fit(). The default corresponds to a variance-based LOSH measure. Applies only if losh_scaling_factor is not False.

Returns:¶

Axes object with the Moran scatterplot.

Return type:¶

matplotlib.axes.Axes