esda.Moran_Local_Rate¶

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

Adjusted Local Moran Statistics for Rate Variables [Assuncao and Reis, 1999].

Parameters:¶

e : array¶: (n,1), an event variable across n spatial units
b : array¶: (n,1), a population-at-risk variable across n spatial units
w : W | Graph¶: spatial weights instance as W or Graph aligned with y
adjusted : boolean¶: whether or not local Moran statistics need to be adjusted for rate variable
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
njobs : int: number of workers to use to compute the local statistic.
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 : float¶: 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.
alternative : None | str = None¶: The alternative hypothesis for conditional randomization. See crand.crand() for complete description.

y[source]¶

rate variables computed from parameters e and b if adjusted is True, y is standardized rates otherwise, y is raw rates

Type:¶: array

z[source]¶

zero-mean, unit standard deviation normalized y

Type:¶: array

w[source]¶

original w object

Type:¶: W | Graph

permutations[source]¶

number of random permutations for calculation of pseudo p_values

Type:¶: int

Is[source]¶

value of Local Moran’s Ii

Type:¶: float

q[source]¶

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

Type:¶: array

sim[source]¶

(if permutations>0) vector of I values for permuted samples

Type:¶: array

p_sim[source]¶

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

Type:¶: array

EI_sim[source]¶

(if permutations>0) average value of I from permutations

Type:¶: float

VI_sim[source]¶

(if permutations>0) variance of I from permutations

Type:¶: float

seI_sim[source]¶

(if permutations>0) standard deviation of I under permutations.

Type:¶: float

z_sim[source]¶

(if permutations>0) standardized I based on permutations

Type:¶: float

p_z_sim[source]¶

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

Type:¶: float

Examples

>>> import libpysal
>>> import numpy as np
>>> np.random.seed(10)
>>> w = libpysal.io.open(libpysal.examples.get_path("sids2.gal")).read()
>>> f = libpysal.io.open(libpysal.examples.get_path("sids2.dbf"))
>>> e = np.array(f.by_col('SID79'))
>>> b = np.array(f.by_col('BIR79'))
>>> from esda.moran import Moran_Local_Rate
>>> lm = Moran_Local_Rate(
...     e,
...     b,
...     w,
...     transformation="r",
...     permutations=99,
...     seed=12345,
...     alternative="two-sided",
... )
>>> lm.q[:10]
array([2, 4, 3, 1, 2, 1, 1, 4, 2, 4])
>>> lm.p_z_sim[0]
np.float64(0.48921877308350953)
>>> lm = Moran_Local_Rate(
...     e,
...     b,
...     w,
...     transformation="r",
...     permutations=99,
...     seed=12345,
...     alternative="two-sided",
...     geoda_quads=True,
... )
>>> lm.q[:10]
array([3, 4, 2, 1, 3, 1, 1, 4, 3, 4])
>>> lm.p_z_sim[0]
np.float64(0.48921877308350953)

Methods

`by_col`(df, events, populations[, w, ...])	Function to compute a Moran_Local_Rate 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, events, populations, w=None, inplace=False, pvalue='sim', outvals=None, swapname='', **stat_kws)[source]¶

Function to compute a Moran_Local_Rate statistic on a dataframe

Parameters:¶

df : pandas.DataFrame¶: a pandas dataframe with a geometry column
events : string or list of strings¶: one or more names where events are stored
populations : string or list of strings¶: one or more names where the populations corresponding to the events are stored. If one population column is provided, it is used for all event columns. If more than one population column is provided but there is not a population for every event column, an exception will be raised.
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_rate’
pvalue : string¶: a string denoting which pvalue should be returned. Refer to the the Moran_Local_Rate statistic’s documentation for available p-values
outvals : list of strings¶: list of arbitrary attributes to return as columns from the Moran_Local_Rate statistic
**stat_kws : dict¶: options to pass to the underlying statistic. For this, see the documentation for the Moran_Local_Rate 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