esda.Moran¶

class esda.Moran(y, w, transformation='r', permutations=999, two_tailed=True)[source]¶

Moran’s I Global Autocorrelation Statistic

Parameters:¶

y : array¶: variable measured across n spatial units
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
two_tailed : boolean¶: If True (default) analytical p-values for Moran are two tailed, otherwise if False, they are one-tailed.

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 permutations

Type:¶: int

I[source]¶

value of Moran’s I

Type:¶: float

EI[source]¶

expected value under normality assumption

Type:¶: float

VI_norm[source]¶

variance of I under normality assumption

Type:¶: float

seI_norm[source]¶

standard deviation of I under normality assumption

Type:¶: float

z_norm[source]¶

z-value of I under normality assumption

Type:¶: float

p_norm[source]¶

p-value of I under normality assumption

Type:¶: float

VI_rand[source]¶

variance of I under randomization assumption

Type:¶: float

seI_rand[source]¶

standard deviation of I under randomization assumption

Type:¶: float

z_rand[source]¶

z-value of I under randomization assumption

Type:¶: float

p_rand[source]¶

p-value of I under randomization assumption

Type:¶: float

two_tailed[source]¶

If True p_norm and p_rand are two-tailed, otherwise they are one-tailed.

Type:¶: boolean

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-tailed) null: spatial randomness alternative: the observed I is extreme if it is either extremely greater or extremely lower than the values obtained based on permutations

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

Type:¶: float

Notes

Technical details and derivations can be found in [Cliff and Ord, 1981].

Examples

>>> import libpysal, numpy
>>> w = libpysal.io.open(libpysal.examples.get_path("stl.gal")).read()
>>> f = libpysal.io.open(libpysal.examples.get_path("stl_hom.txt"))
>>> y = numpy.array(f.by_col['HR8893'])
>>> from esda import Moran
>>> mi = Moran(y,  w)
>>> round(mi.I, 3)
np.float64(0.244)
>>> mi.EI
-0.012987012987012988
>>> round(mi.p_norm, 6)
np.float64(0.000271)

SIDS example replicating OpenGeoda

>>> w = libpysal.io.open(libpysal.examples.get_path("sids2.gal")).read()
>>> f = libpysal.io.open(libpysal.examples.get_path("sids2.dbf"))
>>> SIDR = numpy.array(f.by_col("SIDR74"))
>>> mi = Moran(SIDR,  w)
>>> round(mi.I, 3)
np.float64(0.248)
>>> mi.p_norm
np.float64(0.00011583307814905095)

One-tailed

>>> mi_1 = Moran(SIDR,  w, two_tailed=False)
>>> round(mi_1.I, 3)
np.float64(0.248)
>>> round(mi_1.p_norm, 4)
np.float64(0.0001)

Methods

`by_col`(df, cols[, w, inplace, pvalue, outvals])	Function to compute a Moran statistic on a dataframe
`plot_scatter`([ax, scatter_kwds, ...])	Plot a Moran scatterplot with optional coloring for significant points.
`plot_simulation`([ax, legend, fitline_kwds])	Global Moran's I simulated reference distribution.

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

Function to compute a Moran 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’
pvalue : string¶: a string denoting which pvalue should be returned. Refer to the the Moran statistic’s documentation for available p-values
outvals : list of strings¶: list of arbitrary attributes to return as columns from the Moran statistic
**stat_kws : dict¶: options to pass to the underlying statistic. For this, see the documentation for the Moran 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.

plot_scatter(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:¶

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

plot_simulation(ax=None, legend=False, fitline_kwds=None, **kwargs)[source]¶

Global Moran’s I simulated reference distribution.

Parameters:¶

ax : matplotlib.axes.Axes, optional¶: Pre-existing axes for the plot, by default None.
legend : bool, optional¶: Plot a legend, by default False
fitline_kwds : dict, optional¶: Additional keyword arguments for vertical Moran fit line, by default None.
**kwargs : keyword arguments, optional¶: Additional keyword arguments for KDE plot passed to seaborn.kdeplot, by default None.

Returns:¶

Axes object with the Moran scatterplot.

Return type:¶

matplotlib.axes.Axes

Notes

This requires optional dependencies matplotlib and seaborn.

Examples

>>> import libpysal, numpy
>>> w = libpysal.io.open(libpysal.examples.get_path("stl.gal")).read()
>>> f = libpysal.io.open(libpysal.examples.get_path("stl_hom.txt"))
>>> y = numpy.array(f.by_col['HR8893'])
>>> from esda import Moran
>>> mi = Moran(y,  w)

Default plot:

>>> mi.plot_simulation()

Customized styling that turns the distribution into a pink line and line indicating I to a black line:

>>> mi.plot_simulation(fitline_kwds={"color": "k"}, color="pink", shade=False)