inequality.polarization.S#

class inequality.polarization.S(df, g, column, k=2, bins=None, permutations=999, seed=None, keep_sim=False, n_jobs=1, verbose=True)[source]#

Spatial Polarization Index

This class computes a spatial polarization index that quantifies the degree to which categorical groupings of a variable align with the structure of a spatial graph. A higher value indicates stronger spatial clustering of similar values.

The index is calculated by comparing the observed number of connected components in the graph induced by group membership against a null distribution generated through Monte Carlo permutation. See [Rey26] for the underlying spatial polarization framework.

Attributes:

columnstr

The name of the variable analyzed for spatial polarization.

nint

Number of observations.

statistic_float

The observed spatial polarization index.

p_valuefloat

Monte Carlo p-value based on the permutation distribution. Present only if permutations > 0.

permutationsint

The number of permutations used in the significance test.

n_a_componentsint

Number of attribute-based groups (bins).

n_g_componentsint

Number of spatial components in the original graph.

n_i_componentsint

Number of connected components in the intersection subgraph.

labelspandas.DataFrame

A dataframe containing:

i_labels: labels for intersection components
a_labels: attribute bin labels
g_labels: original spatial component labels

simnumpy.ndarray, optional

Array of simulated index values from the permutation test. Present only if keep_sim is True.

Notes

The spatial polarization index measures the degree of spatial fragmentation by assessing how many connected subregions are formed by similar attribute values. This helps to identify whether like values are spatially clustered or dispersed.

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from libpysal.weights import lat2W
>>> from libpysal.graph import Graph
>>> from inequality.polarization import S

# Create a synthetic 40x40 spatial grid >>> y = np.arange(1600) >>> df = pd.DataFrame({‘y’: y}, index=y) >>> w = lat2W(40, 40) >>> g = Graph.from_W(w)

# Compute the spatial polarization index >>> s = S(df, g, ‘y’, permutations=99, seed=123, verbose=False) >>> print(s) S Spatial Polarization Summary ======================================================= Variable: y n: 1600 ——————————————————- S: 1.0000 p-value: 0.0100 permutations: 99 ——————————————————- Number of attribute components: 2 Number of spatial components: 1 Number of intersection components: 2 ======================================================= <BLANKLINE>

__init__(df, g, column, k=2, bins=None, permutations=999, seed=None, keep_sim=False, n_jobs=1, verbose=True)[source]#

Initialize the Spatial Polarization Index computation.

Parameters:

dfpandas.DataFrame

Dataframe containing spatial observations. Index must align with nodes in the graph g.

glibpysal.graph.Graph

A PySAL graph representing spatial adjacency.

columnstr

Name of the column in df to evaluate for spatial polarization.

kint, default 2

Number of quantile bins to divide the variable into, if bins is not specified.

binslist of float, optional

Explicit cutpoints to bin the variable, passed directly to pandas.cut. Overrides k if provided.

The first and last values in bins define the lower and upper bounds of the binning range. Any data values below the lowest bin edge or above the highest bin edge will be excluded (i.e., assigned NaN). This can lead to errors in the computation of the S index if observations are dropped because of out-of-range values. To ensure all data are included, make sure the first and last bin edges bound the full range of the data.

permutationsint, default 999

Number of random permutations to generate the null distribution.

seedint or None, optional

Seed for random number generator (reproducibility).

keep_simbool, default False

If True, store the full array of simulated statistics.

n_jobsint, default 1

Number of parallel jobs for permutations. Use -1 for all CPUs.

verbosebool, default True

If True, display a progress bar during permutation computation.

Methods

__init__(df, g, column[, k, bins, ...])

Initialize the Spatial Polarization Index computation.