explore_lisa_cluster_map

explore_lisa_cluster_map(
    df,
    var,
    *,
    gdf,
    w=None,
    period=None,
    entity=None,
    time=None,
    permutations=999,
    seed=12345,
    alpha=0.05,
    tiles='carto-positron',
    title=None,
)

Map local Moran (LISA) clusters of var and the matching Moran scatterplot.

:class:esda.moran.Moran_Local assigns each entity a scatter quadrant (via its q: 1=HH, 2=LH, 3=LL, 4=HL) and a permutation pseudo p-value; entities with p_sim < alpha receive their quadrant’s cluster label (High-High hot spots, Low-Low cold spots, Low-High / High-Low spatial outliers) and everything else is "Not significant". The cluster map uses the ecosystem-fixed LISA colors (GeoDa / splot convention); fig_scatter is the same Moran scatter as :func:explore_moran_plot, colored by cluster. Global Moran’s I accompanies the local statistics (moran_i, p_sim_global).

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 analyze.	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.	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 the local and global pseudo p-values.	999
seed	int | None	Reproducibility seed. Moran_Local accepts it directly; the global :class:~esda.moran.Moran has no seed argument, so numpy.random.seed(seed) is set immediately before it (see :func:explore_moran_plot). None leaves the random state untouched.	12345
alpha	float	Significance level masking the cluster labels (p_sim < alpha).	0.05
tiles	str | None	MapLibre base-map style for the cluster map (default "carto-positron") or None for the vector backend (deterministic PNG export).	'carto-positron'
title	str | None	Cluster-map title. Defaults to "LISA clusters: <label> (<period>)"; the scatter always uses its own composed title.	None

Returns

Name	Type	Description
	LisaClusterMapResult	Frozen result with the per-entity frame (entity, standardized value, lag, local_i, quadrant, p_sim, cluster), the cluster map fig, the cluster-colored fig_scatter, the global test scalars, the per-class counts and w_spec.

Examples

LISA on a four-cell strip (tiny n, so nothing is significant at 5%):

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

from geometrics.dependence import explore_lisa_cluster_map
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_lisa_cluster_map(
    df, "gdppc", gdf=gdf, w=make_weights(gdf), entity="region",
    permutations=99, tiles=None,
)
print(res.df["cluster"].tolist())