explore_moran_plot

explore_moran_plot(
    df,
    var,
    *,
    gdf,
    w=None,
    period=None,
    entity=None,
    time=None,
    permutations=999,
    seed=12345,
    title=None,
)

Draw the Moran scatterplot and test global spatial autocorrelation in var.

The panel is aligned to the geometry for one cross-section (the latest period by default), the variable is z-standardized, and its row-standardized spatial lag is plotted against it, colored by scatter quadrant (HH, LH, LL, HL). The OLS slope of the fitted line equals global Moran’s I under row-standardized weights, whose significance is assessed with permutations conditional permutations (:class:esda.moran.Moran).

Parameters

Name	Type	Description	Default
df	pd.DataFrame	Long panel (or cross-section) holding var per entity.	required
var	str	Numeric column of df to test.	required
gdf	gpd.GeoDataFrame	Entity geometry; must carry the same entity-id column as df.	required
w	W | None	libpysal weights aligned to the gdf entity ids. None builds the default weights (queen contiguity for polygons, 6-nearest-neighbor otherwise) with a :class:~geometrics.GeometricsWarning. esda row-standardizes the weights for the statistic (its transformation="r" convention), which is also what makes the scatter slope equal Moran’s I.	None
period	Any	Period to analyze. Defaults to the latest period when df has a time dimension (a note records this).	None
entity	str | None	Panel identifiers; default to the ids declared via :func:geometrics.set_panel.	None
time	str | None	Panel identifiers; default to the ids declared via :func:geometrics.set_panel.	None
permutations	int	Number of conditional permutations behind p_sim / z_sim.	999
seed	int | None	esda’s global :class:~esda.moran.Moran draws its permutations from NumPy’s global random state and exposes no seed argument, so when seed is not None geometrics calls numpy.random.seed(seed) immediately before the test to make p_sim reproducible. Pass None to leave the global state untouched.	12345
title	str | None	Figure title. Defaults to "Moran scatterplot: <label> (<period>)".	None

Returns

Name	Type	Description
	MoranPlotResult	Frozen result with df (entity, standardized value, spatial lag, quadrant), the quadrant-colored scatter fig, the global Moran scalars (moran_i, expected_i, p_sim, z_sim) and w_spec.

Examples

Moran’s I on a four-cell strip where value increases smoothly west to east:

import geopandas as gpd
import pandas as pd
from shapely.geometry import box

from geometrics.dependence import explore_moran_plot
from geometrics.weights import make_weights

gdf = gpd.GeoDataFrame(
    {"region": ["a", "b", "c", "d"]},
    geometry=[box(i, 0, i + 1, 1) for i in range(4)],
    crs="EPSG:4326",
)
df = pd.DataFrame({"region": ["a", "b", "c", "d"], "gdppc": [1.0, 2.0, 3.0, 4.0]})
res = explore_moran_plot(
    df, "gdppc", gdf=gdf, w=make_weights(gdf), entity="region", permutations=99
)
print(res.df["quadrant"].tolist(), round(res.moran_i, 3))