segstats 0.1.0__py3-none-any.whl

segstats/__init__.py

@@ -0,0 +1,124 @@
+"""segstats: residential segregation and diversity indices for urban analysis.
+
+Implements the five dimensions of Massey & Denton (1988) - evenness, exposure,
+concentration, centralization and clustering - plus multigroup indices (Reardon &
+Firebaugh 2002), spatial evenness measures (Morrill 1991; Wong 1993; Reardon &
+O'Sullivan 2004), local diversity measures and Monte Carlo inference.
+
+Quick start::
+
+    import segstats as ss
+
+    data = ss.read_csv("tracts.csv", id_column="tract", groups=["black", "white"])
+    ss.dissimilarity(*data.two_group("black"))
+    ss.profile(data, group="black")
+    ss.permutation_test(data, "D", group="black", seed=1).p_value
+"""
+
+from ._version import __version__
+from .aspatial import (
+    atkinson,
+    correlation_ratio,
+    dissimilarity,
+    entropy,
+    exposure_matrix,
+    gini,
+    interaction,
+    isolation,
+    multigroup_dissimilarity,
+    multigroup_entropy,
+)
+from .data import ZoneData, from_dataframe, read_csv, read_geojson
+from .geometry import ZoneGeometry
+from .indices import INDICES, IndexOptions, IndexSpec, Statistic, compute, profile, statistic
+from .inference import (
+    BootstrapResult,
+    PermutationResult,
+    bootstrap_ci,
+    permutation_test,
+    random_allocation,
+)
+from .local import (
+    local_dissimilarity_contribution,
+    local_entropy,
+    local_spatial_entropy,
+    location_quotient,
+)
+from .spatial import (
+    absolute_centralization,
+    absolute_clustering,
+    absolute_concentration,
+    delta,
+    local_environment,
+    morrill_dissimilarity,
+    proximity_matrix,
+    relative_centralization,
+    relative_clustering,
+    relative_concentration,
+    spatial_dissimilarity,
+    spatial_entropy,
+    spatial_proximity,
+    wong_dissimilarity_s,
+    wong_dissimilarity_w,
+)
+from .weights import distance_matrix, kernel_weights, row_standardize, with_self
+
+__all__ = [
+    "__version__",
+    # evenness / exposure
+    "dissimilarity",
+    "gini",
+    "entropy",
+    "atkinson",
+    "isolation",
+    "interaction",
+    "correlation_ratio",
+    "multigroup_dissimilarity",
+    "multigroup_entropy",
+    "exposure_matrix",
+    # concentration / centralization / clustering
+    "delta",
+    "absolute_concentration",
+    "relative_concentration",
+    "absolute_centralization",
+    "relative_centralization",
+    "proximity_matrix",
+    "absolute_clustering",
+    "relative_clustering",
+    "spatial_proximity",
+    # spatial evenness
+    "morrill_dissimilarity",
+    "wong_dissimilarity_w",
+    "wong_dissimilarity_s",
+    "local_environment",
+    "spatial_dissimilarity",
+    "spatial_entropy",
+    # local
+    "location_quotient",
+    "local_entropy",
+    "local_spatial_entropy",
+    "local_dissimilarity_contribution",
+    # data, geometry, weights
+    "ZoneData",
+    "ZoneGeometry",
+    "read_csv",
+    "read_geojson",
+    "from_dataframe",
+    "distance_matrix",
+    "kernel_weights",
+    "with_self",
+    "row_standardize",
+    # registry and inference
+    "INDICES",
+    "IndexSpec",
+    "IndexOptions",
+    "Statistic",
+    "statistic",
+    "compute",
+    "profile",
+    "permutation_test",
+    "bootstrap_ci",
+    "random_allocation",
+    "PermutationResult",
+    "BootstrapResult",
+]

segstats/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m segstats``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

segstats/_arrays.py

@@ -0,0 +1,84 @@
+"""Input validation helpers shared by every index module (internal)."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Tuple
+
+import numpy as np
+
+__all__ = ["as_counts", "as_vector", "as_square", "two_group", "safe_div"]
+
+
+def as_vector(values: Any, name: str, n: Optional[int] = None, nonneg: bool = True) -> np.ndarray:
+    """Return ``values`` as a finite 1-D float array, optionally checking its length."""
+    arr = np.asarray(values, dtype=float)
+    if arr.ndim != 1:
+        raise ValueError(f"{name} must be one-dimensional, got shape {arr.shape}")
+    if n is not None and arr.shape[0] != n:
+        raise ValueError(f"{name} has length {arr.shape[0]}, expected {n}")
+    if not np.all(np.isfinite(arr)):
+        raise ValueError(f"{name} contains NaN or infinite values")
+    if nonneg and np.any(arr < 0):
+        raise ValueError(f"{name} contains negative values")
+    return arr
+
+
+def as_counts(counts: Any, min_groups: int = 1) -> np.ndarray:
+    """Return a zones x groups count matrix as a validated 2-D float array."""
+    arr = np.asarray(counts, dtype=float)
+    if arr.ndim == 1:
+        arr = arr[:, None]
+    if arr.ndim != 2:
+        raise ValueError(f"counts must be a 2-D zones x groups table, got shape {arr.shape}")
+    if arr.shape[0] < 1:
+        raise ValueError("counts has no zones")
+    if arr.shape[1] < min_groups:
+        raise ValueError(f"counts needs at least {min_groups} group columns")
+    if not np.all(np.isfinite(arr)):
+        raise ValueError("counts contains NaN or infinite values")
+    if np.any(arr < 0):
+        raise ValueError("counts contains negative values")
+    if arr.sum() <= 0:
+        raise ValueError("counts sum to zero")
+    return arr
+
+
+def as_square(matrix: Any, name: str, n: int) -> np.ndarray:
+    """Return an n x n finite, non-negative float matrix."""
+    arr = np.asarray(matrix, dtype=float)
+    if arr.shape != (n, n):
+        raise ValueError(f"{name} must have shape ({n}, {n}), got {arr.shape}")
+    if not np.all(np.isfinite(arr)):
+        raise ValueError(f"{name} contains NaN or infinite values")
+    if np.any(arr < 0):
+        raise ValueError(f"{name} contains negative values")
+    return arr
+
+
+def two_group(x: Any, t: Any) -> Tuple[np.ndarray, np.ndarray]:
+    """Validate a minority-count vector ``x`` against zone totals ``t``.
+
+    Requires ``0 <= x_i <= t_i`` and ``0 < X < T`` so that both the group and the
+    rest of the population are present somewhere (otherwise every two-group index is
+    undefined).
+    """
+    xa = as_vector(x, "x")
+    ta = as_vector(t, "t", n=xa.shape[0])
+    if np.any(xa > ta * (1 + 1e-12) + 1e-12):
+        raise ValueError("group count exceeds the zone total in at least one zone")
+    big_x = xa.sum()
+    big_t = ta.sum()
+    if big_x <= 0:
+        raise ValueError("the group of interest has zero population")
+    if big_x >= big_t:
+        raise ValueError("the group of interest is the whole population; index undefined")
+    return xa, ta
+
+
+def safe_div(num: np.ndarray, den: np.ndarray) -> np.ndarray:
+    """Element-wise ``num / den`` with 0 where ``den == 0``."""
+    num = np.asarray(num, dtype=float)
+    den = np.asarray(den, dtype=float)
+    out = np.zeros(np.broadcast(num, den).shape, dtype=float)
+    np.divide(num, den, out=out, where=den != 0)
+    return out

segstats/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

segstats/aspatial.py

@@ -0,0 +1,203 @@
+"""Aspatial evenness and exposure indices (Massey & Denton 1988, dimensions 1-2).
+
+Notation follows Massey & Denton (1988): for zone ``i``, ``x_i`` is the count of the
+group of interest ("minority"), ``t_i`` the zone total, ``y_i = t_i - x_i`` the rest
+of the population, ``p_i = x_i / t_i``; capitals are city-wide totals and
+``P = X / T``. Zones with ``t_i = 0`` have no weight in any index.
+
+Multigroup forms follow Reardon & Firebaugh (2002): with ``M`` groups, ``pi_m`` is
+the city-wide share of group ``m`` and ``pi_im`` its share in zone ``i``.
+
+References
+----------
+- Massey, D. S. & Denton, N. A. (1988). The dimensions of residential segregation.
+  *Social Forces* 67(2), 281-315. https://doi.org/10.2307/2579183
+- Duncan, O. D. & Duncan, B. (1955). A methodological analysis of segregation
+  indexes. *American Sociological Review* 20(2), 210-217.
+- Atkinson, A. B. (1970). On the measurement of inequality. *Journal of Economic
+  Theory* 2(3), 244-263.
+- Theil, H. & Finizza, A. J. (1971). A note on the measurement of racial integration
+  of schools by means of informational concepts. *Journal of Mathematical Sociology*
+  1(2), 187-193.
+- Reardon, S. F. & Firebaugh, G. (2002). Measures of multigroup segregation.
+  *Sociological Methodology* 32, 33-67. https://doi.org/10.1111/1467-9531.00110
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ._arrays import as_counts, safe_div, two_group
+
+__all__ = [
+    "dissimilarity",
+    "gini",
+    "entropy",
+    "atkinson",
+    "isolation",
+    "interaction",
+    "correlation_ratio",
+    "multigroup_dissimilarity",
+    "multigroup_entropy",
+    "exposure_matrix",
+    "shannon_entropy",
+]
+
+
+def shannon_entropy(shares: Any, axis: int = -1) -> np.ndarray:
+    """Shannon entropy ``-sum(s ln s)`` (natural log) with the convention ``0 ln 0 = 0``."""
+    s = np.asarray(shares, dtype=float)
+    logs = np.zeros_like(s)
+    np.log(s, out=logs, where=s > 0)
+    return np.asarray(-(s * logs).sum(axis=axis))
+
+
+# --------------------------------------------------------------------------- evenness
+
+
+def dissimilarity(x: Any, t: Any) -> float:
+    """Index of dissimilarity ``D`` (Duncan & Duncan 1955; Massey & Denton 1988 eq. 1).
+
+    ``D = 1/2 * sum_i |x_i / X - y_i / Y|``, the share of either group that would have
+    to move to reach an even distribution. 0 = even, 1 = complete segregation.
+    """
+    xa, ta = two_group(x, t)
+    ya = ta - xa
+    return float(0.5 * np.abs(xa / xa.sum() - ya / ya.sum()).sum())
+
+
+def gini(x: Any, t: Any) -> float:
+    """Gini coefficient of segregation (Massey & Denton 1988 eq. 2).
+
+    ``G = sum_i sum_j t_i t_j |p_i - p_j| / (2 T^2 P (1 - P))``; computed in
+    ``O(n log n)`` from the sorted zone proportions rather than the full pair matrix.
+    """
+    xa, ta = two_group(x, t)
+    big_t = ta.sum()
+    big_p = xa.sum() / big_t
+    p = safe_div(xa, ta)
+    order = np.argsort(p, kind="stable")
+    ps, ts = p[order], ta[order]
+    cum_t = np.concatenate(([0.0], np.cumsum(ts)[:-1]))
+    cum_tp = np.concatenate(([0.0], np.cumsum(ts * ps)[:-1]))
+    pair_sum = 2.0 * float((ts * (ps * cum_t - cum_tp)).sum())  # ordered pairs
+    return pair_sum / (2.0 * big_t**2 * big_p * (1.0 - big_p))
+
+
+def entropy(x: Any, t: Any) -> float:
+    """Two-group entropy (information theory) index ``H`` (Massey & Denton 1988 eq. 3).
+
+    ``H = sum_i t_i (E - E_i) / (E T)`` with ``E = P ln(1/P) + (1-P) ln(1/(1-P))``.
+    Equal to :func:`multigroup_entropy` applied to ``[x, t - x]``.
+    """
+    xa, ta = two_group(x, t)
+    return multigroup_entropy(np.column_stack([xa, ta - xa]))
+
+
+def atkinson(x: Any, t: Any, b: float = 0.5) -> float:
+    """Atkinson index ``A_b`` (Atkinson 1970; Massey & Denton 1988 eq. 4).
+
+    ``A = 1 - P/(1-P) * |sum_i (1-p_i)^(1-b) p_i^b t_i / (P T)|^(1/(1-b))``.
+    The shape parameter ``0 < b < 1`` weights zones where the group is
+    under-represented (``b < 0.5``) or over-represented (``b > 0.5``).
+    """
+    if not 0.0 < b < 1.0:
+        raise ValueError("Atkinson shape parameter b must lie strictly between 0 and 1")
+    xa, ta = two_group(x, t)
+    big_t = ta.sum()
+    big_p = xa.sum() / big_t
+    p = safe_div(xa, ta)
+    inner = ((1.0 - p) ** (1.0 - b) * p**b * ta).sum() / (big_p * big_t)
+    return float(1.0 - big_p / (1.0 - big_p) * abs(inner) ** (1.0 / (1.0 - b)))
+
+
+# --------------------------------------------------------------------------- exposure
+
+
+def isolation(x: Any, t: Any) -> float:
+    """Isolation index ``xPx`` (Massey & Denton 1988 eq. 7).
+
+    ``xPx = sum_i (x_i / X)(x_i / t_i)``: the group share in the zone of the average
+    group member. Its lower bound is ``P`` (not 0), so compare with
+    :func:`correlation_ratio` when groups differ in size.
+    """
+    xa, ta = two_group(x, t)
+    return float((xa / xa.sum() * safe_div(xa, ta)).sum())
+
+
+def interaction(x: Any, t: Any) -> float:
+    """Interaction (exposure) index ``xPy`` (Massey & Denton 1988 eq. 6).
+
+    ``xPy = sum_i (x_i / X)(y_i / t_i)``. In the two-group case ``xPy + xPx = 1``.
+    """
+    xa, ta = two_group(x, t)
+    return float((xa / xa.sum() * safe_div(ta - xa, ta)).sum())
+
+
+def correlation_ratio(x: Any, t: Any) -> float:
+    """Correlation ratio, eta squared ``V = (xPx - P) / (1 - P)`` (Massey & Denton 1988 eq. 8).
+
+    Isolation corrected for group size; 0 = no excess isolation, 1 = complete
+    segregation (Bell 1954; White 1986).
+    """
+    xa, ta = two_group(x, t)
+    big_p = xa.sum() / ta.sum()
+    return (isolation(xa, ta) - big_p) / (1.0 - big_p)
+
+
+# --------------------------------------------------------------------------- multigroup
+
+
+def _shares(counts: Any) -> "tuple[np.ndarray, np.ndarray, np.ndarray, float]":
+    c = as_counts(counts, min_groups=2)
+    t = c.sum(axis=1)
+    big_t = float(t.sum())
+    pi = c.sum(axis=0) / big_t
+    pi_i = safe_div(c, t[:, None])
+    return t, pi, pi_i, big_t
+
+
+def multigroup_dissimilarity(counts: Any) -> float:
+    """Multigroup dissimilarity ``D`` (Reardon & Firebaugh 2002, eq. for D; Morgan 1975).
+
+    ``D = sum_m sum_i t_i |pi_im - pi_m| / (2 T I)`` with the interaction (Simpson)
+    index ``I = sum_m pi_m (1 - pi_m)``. Reduces to :func:`dissimilarity` for two
+    groups.
+    """
+    t, pi, pi_i, big_t = _shares(counts)
+    simpson = float((pi * (1.0 - pi)).sum())
+    if simpson <= 0:
+        raise ValueError("only one group is present; multigroup D undefined")
+    return float((t[:, None] * np.abs(pi_i - pi)).sum() / (2.0 * big_t * simpson))
+
+
+def multigroup_entropy(counts: Any) -> float:
+    """Multigroup information theory index (Theil's ``H``; Reardon & Firebaugh 2002).
+
+    ``H = sum_i t_i (E - E_i) / (T E)`` with ``E = -sum_m pi_m ln pi_m`` and
+    ``E_i = -sum_m pi_im ln pi_im``. 0 = every zone mirrors the city composition,
+    1 = every zone holds a single group.
+    """
+    t, pi, pi_i, big_t = _shares(counts)
+    big_e = float(shannon_entropy(pi))
+    if big_e <= 0:
+        raise ValueError("only one group is present; entropy index undefined")
+    e_i = shannon_entropy(pi_i, axis=1)
+    return float((t * (big_e - e_i)).sum() / (big_t * big_e))
+
+
+def exposure_matrix(counts: Any) -> np.ndarray:
+    """Matrix of exposure indices ``mPn = sum_i (x_im / X_m)(x_in / t_i)``.
+
+    Entry ``[m, n]`` is the average share of group ``n`` in the zone of a member of
+    group ``m`` (Massey & Denton 1988 eq. 6 generalised; Bell 1954). The diagonal holds
+    the isolation indices and each row sums to 1.
+    """
+    c = as_counts(counts)
+    t = c.sum(axis=1)
+    totals = c.sum(axis=0)
+    weights = safe_div(c, totals[None, :])  # x_im / X_m
+    shares = safe_div(c, t[:, None])  # x_in / t_i
+    return np.asarray(weights.T @ shares)

segstats/cli.py

@@ -0,0 +1,220 @@
+"""Command-line interface: ``segstats indices|local|list``."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import math
+import sys
+from typing import Any, Dict, List, Optional, Sequence
+
+from . import __version__
+from .data import ZoneData, read_csv, read_geojson
+from .indices import INDICES, IndexOptions, profile
+from .inference import bootstrap_ci, permutation_test
+from .local import local_entropy, local_spatial_entropy, location_quotient
+from .weights import kernel_weights, with_self
+
+
+def _split(value: Optional[str]) -> Optional[List[str]]:
+    if not value:
+        return None
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def _load(args: argparse.Namespace) -> ZoneData:
+    groups = _split(args.groups)
+    src = str(args.counts)
+    is_geo = src.lower().endswith((".geojson", ".json"))
+    if is_geo:
+        return read_geojson(
+            src, args.id, groups, args.total, project=args.project
+        )  # counts from properties
+    data = read_csv(src, args.id, groups, args.total, delimiter=args.delimiter)
+    if args.geojson:
+        return read_geojson(args.geojson, args.geo_id or args.id, project=args.project, counts=data)
+    return data
+
+
+def _options(args: argparse.Namespace) -> IndexOptions:
+    center = None
+    if args.center:
+        parts = [float(v) for v in args.center.split(",")]
+        if len(parts) != 2:
+            raise SystemExit("--center expects X,Y")
+        center = parts
+    return IndexOptions(
+        b=args.atkinson_b,
+        center=center,
+        decay_scale=args.decay_scale,
+        clustering=args.clustering,
+        bandwidth=args.bandwidth,
+        kernel=args.kernel,
+        contiguity=args.contiguity,
+    )
+
+
+def _fmt(v: Any) -> str:
+    if isinstance(v, float):
+        return "nan" if math.isnan(v) else f"{v:.6g}"
+    return str(v)
+
+
+def _emit(rows: List[Dict[str, Any]], fmt: str, out: Any) -> None:
+    if fmt == "json":
+        json.dump(rows, out, indent=2, allow_nan=True)
+        out.write("\n")
+        return
+    keys: List[str] = []
+    for r in rows:
+        for k in r:
+            if k not in keys:
+                keys.append(k)
+    if fmt == "csv":
+        w = csv.DictWriter(out, fieldnames=keys, lineterminator="\n")
+        w.writeheader()
+        w.writerows(rows)
+        return
+    table = [keys] + [[_fmt(r.get(k, "")) for k in keys] for r in rows]
+    widths = [max(len(row[i]) for row in table) for i in range(len(keys))]
+    for line_no, row in enumerate(table):
+        out.write("  ".join(c.ljust(w) for c, w in zip(row, widths)).rstrip() + "\n")
+        if line_no == 0:
+            out.write("  ".join("-" * w for w in widths) + "\n")
+
+
+def _cmd_indices(args: argparse.Namespace) -> int:
+    data = _load(args)
+    opts = _options(args)
+    group = args.group
+    names = _split(args.index)
+    values = profile(data, group, names, opts)
+    rows: List[Dict[str, Any]] = []
+    for name, value in values.items():
+        spec = INDICES[name]
+        row: Dict[str, Any] = {"index": name, "label": spec.label, "dimension": spec.dimension}
+        row["value"] = value
+        if args.permutations:
+            pt = permutation_test(
+                data, name, group, args.permutations, args.null, seed=args.seed, options=opts
+            )
+            row.update(null_mean=pt.null_mean, p_value=pt.p_value)
+        if args.bootstrap:
+            bs = bootstrap_ci(
+                data, name, group, args.bootstrap, args.level, seed=args.seed, options=opts
+            )
+            row.update(ci_low=bs.ci_low, ci_high=bs.ci_high)
+        rows.append(row)
+    _emit(rows, args.format, sys.stdout)
+    return 0
+
+
+def _cmd_local(args: argparse.Namespace) -> int:
+    data = _load(args)
+    lq = location_quotient(data.counts)
+    ent = local_entropy(data.counts)
+    spatial = None
+    if data.geometry is not None:
+        if args.bandwidth:
+            w = kernel_weights(data.geometry.distances(), args.bandwidth, args.kernel)
+        else:
+            w = with_self(data.geometry.contiguity(args.contiguity))
+        spatial = local_spatial_entropy(data.counts, w)
+    rows: List[Dict[str, Any]] = []
+    for i, zid in enumerate(data.ids or []):
+        row: Dict[str, Any] = {"id": zid, "total": float(data.totals[i])}
+        for j, g in enumerate(data.groups):
+            row[f"lq_{g}"] = float(lq[i, j])
+        row["entropy"] = float(ent[i])
+        if spatial is not None:
+            row["spatial_entropy"] = float(spatial[i])
+        rows.append(row)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8", newline="") as fh:
+            _emit(rows, args.format if args.format != "table" else "csv", fh)
+    else:
+        _emit(rows, args.format, sys.stdout)
+    return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    rows = [
+        {
+            "index": s.name,
+            "label": s.label,
+            "dimension": s.dimension,
+            "groups": "multi" if s.multigroup else "two",
+            "needs": ",".join(s.needs) or "-",
+            "reference": s.reference,
+        }
+        for s in INDICES.values()
+    ]
+    _emit(rows, args.format, sys.stdout)
+    return 0
+
+
+def _add_input(p: argparse.ArgumentParser) -> None:
+    p.add_argument("counts", help="CSV count table or GeoJSON with counts in properties")
+    p.add_argument("--id", help="zone id column / property")
+    p.add_argument("--groups", help="comma-separated group columns (default: all numeric)")
+    p.add_argument("--total", help="total column; adds an 'other' group for the remainder")
+    p.add_argument("--delimiter", default=",", help="CSV delimiter (default ',')")
+    p.add_argument("--geojson", help="zone polygons to join to a CSV table by id")
+    p.add_argument("--geo-id", help="id property in --geojson (default: --id)")
+    p.add_argument(
+        "--project",
+        choices=["auto", "lonlat", "none"],
+        default="auto",
+        help="project lon/lat coordinates to metres (default: auto-detect)",
+    )
+    p.add_argument("--bandwidth", type=float, help="kernel bandwidth for spatial H/D")
+    p.add_argument("--kernel", default="gaussian", help="gaussian|exponential|biweight|box")
+    p.add_argument("--contiguity", choices=["queen", "rook"], default="queen")
+    p.add_argument("--format", choices=["table", "json", "csv"], default="table")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Argument parser for the ``segstats`` command."""
+    parser = argparse.ArgumentParser(
+        prog="segstats",
+        description="Residential segregation and diversity indices for urban zones.",
+    )
+    parser.add_argument("--version", action="version", version=f"segstats {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("indices", help="compute global segregation indices")
+    _add_input(p)
+    p.add_argument("--group", help="group of interest for two-group indices")
+    p.add_argument("--index", help="comma-separated index names (default: all available)")
+    p.add_argument("--center", help="centre X,Y for centralization (input coordinates)")
+    p.add_argument("--decay-scale", type=float, default=1000.0, help="distance unit of exp(-d)")
+    p.add_argument("--clustering", choices=["proximity", "contiguity"], default="proximity")
+    p.add_argument("--atkinson-b", type=float, default=0.5)
+    p.add_argument("--permutations", type=int, default=0, help="random-allocation test runs")
+    p.add_argument("--null", choices=["labels", "zones"], default="labels")
+    p.add_argument("--bootstrap", type=int, default=0, help="bootstrap resamples for CIs")
+    p.add_argument("--level", type=float, default=0.95, help="confidence level")
+    p.add_argument("--seed", type=int, help="random seed")
+    p.set_defaults(func=_cmd_indices)
+
+    p = sub.add_parser("local", help="per-zone location quotients and entropy")
+    _add_input(p)
+    p.add_argument("-o", "--output", help="write to this file instead of stdout")
+    p.set_defaults(func=_cmd_local)
+
+    p = sub.add_parser("list", help="list available indices")
+    p.add_argument("--format", choices=["table", "json", "csv"], default="table")
+    p.set_defaults(func=_cmd_list)
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entry point; returns the process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except (ValueError, KeyError, OSError) as exc:
+        print(f"segstats: error: {exc}", file=sys.stderr)
+        return 2