equipop 1.1.0__py3-none-any.whl

equipop/__init__.py

@@ -0,0 +1,31 @@
+"""
+EquiPop Pangea - k-nearest neighbour contextual analysis on gridded data.
+
+Phase 1, Step 1: projection, grid snapping, and the basic radial k-NN engine
+(no friction, no decay yet - those come in Phase 2).
+"""
+
+from .transform import project_to_metric, snap_to_grid
+from .analysis import run_knn
+from .decay import Decay
+from .analysis import run_knn_stats
+from .cells import build_cells, CellData
+from .friction import run_knn_friction, load_friction_table
+from .projection import suggest_projection, assign_zones
+from .io import read_table, save_output
+from .fetch import fetch
+from .hex import build_hex_cells
+from .meta import RunLog, load_meta
+from .io import list_layers
+from .fastcounts import run_knn_counts
+from .segregation import seg_profile
+from .area import aggregate_output
+try:
+    from .viz import map_output
+except ImportError:                       # matplotlib is an optional extra
+    def map_output(*a, **k):
+        raise ImportError("map_output needs matplotlib: "
+                          "pip install equipop[viz]")
+
+__version__ = "1.1.0"
+__all__ = ["project_to_metric", "snap_to_grid", "run_knn", "Decay", "run_knn_stats", "build_cells", "CellData", "run_knn_friction", "load_friction_table", "suggest_projection", "assign_zones", "read_table", "save_output", "fetch", "build_hex_cells", "RunLog", "load_meta", "list_layers", "run_knn_counts", "seg_profile", "aggregate_output", "map_output"]

equipop/analysis.py

@@ -0,0 +1,369 @@
+"""
+analysis.py - the radial k-NN engine (Phase 1 + decay).
+
+Core idea (from the EquiPop papers): on a uniform grid, the relative
+distances from ANY origin cell to its surrounding cells are always the
+same. So we compute ONE list of cell-offsets sorted by distance, and
+reuse it for every origin. Cells at identical distance form a "ring".
+
+Decay: when a Decay object is passed, every neighbour's contribution
+is ALSO accumulated multiplied by weight(distance). The k-thresholds
+are still defined by the RAW (unweighted) counts - the decayed values
+are simply recorded at the same moment, exactly as in the original
+EquiPop ("decayed variables use the same k-values as the non-decaying
+variables"). Decayed counts are therefore always <= raw counts.
+
+Output naming - two schemes, chosen with naming="short" | "legacy":
+
+  short (default)   legacy (original EquiPop)
+  ---------------   -------------------------------
+  N_50              IntervalSumCountAll_50
+  T_50              IntervalSumCountGroup_50
+  R_50              IntervalRatio_50
+  Dist_50           IntervalDistance_50
+  ND_50             IntervalSumCountAllDecay_50
+  TD_50             IntervalSumCountGroupDecay_50
+  RD_50             IntervalRatioDecay_50
+
+(N = count of all, T = treatment, R = ratio, D = decayed.)
+"""
+
+import math
+import numpy as np
+import pandas as pd
+from itertools import groupby
+
+from .decay import Decay
+
+
+# ---------------------------------------------------------------- naming
+NAMES = {
+    "short": {
+        "N": "N_{k}", "T": "T_{k}", "R": "R_{k}", "Dist": "Dist_{k}",
+        "ND": "ND_{k}", "TD": "TD_{k}", "RD": "RD_{k}",
+    },
+    "legacy": {
+        "N": "IntervalSumCountAll_{k}",
+        "T": "IntervalSumCountGroup_{k}",
+        "R": "IntervalRatio_{k}",
+        "Dist": "IntervalDistance_{k}",
+        "ND": "IntervalSumCountAllDecay_{k}",
+        "TD": "IntervalSumCountGroupDecay_{k}",
+        "RD": "IntervalRatioDecay_{k}",
+    },
+}
+
+
+def build_distance_rings(max_radius_units: int):
+    """
+    Pre-compute all cell offsets (dx, dy) within max_radius_units,
+    grouped into 'rings' of identical distance, sorted by distance.
+    The origin (0, 0) is excluded - it is counted first, separately.
+
+    Returns a list of (distance_in_units, [(dx, dy), ...]).
+    """
+    offsets = []
+    for dx in range(-max_radius_units, max_radius_units + 1):
+        for dy in range(-max_radius_units, max_radius_units + 1):
+            if dx == 0 and dy == 0:
+                continue
+            d = math.hypot(dx, dy)
+            if d <= max_radius_units:
+                offsets.append((d, dx, dy))
+    offsets.sort(key=lambda t: t[0])
+    return [(dist, [(dx, dy) for _, dx, dy in grp])
+            for dist, grp in groupby(offsets, key=lambda t: t[0])]
+
+
+def run_knn(
+    cells: pd.DataFrame,
+    k_values: list[int],
+    count_all_col: str = "FullPop",
+    count_group_col: str = "Treatment",
+    unit_size: float = 100.0,
+    max_radius_units: int = 500,
+    id_col: str | None = "id",
+    tie_mode: str = "ring",
+    decay: Decay | None = None,
+    naming: str = "short",
+    seed: int | None = None,
+) -> pd.DataFrame:
+    """
+    Radial k-NN analysis for every populated cell.
+
+    Parameters
+    ----------
+    cells : DataFrame with one row per grid cell ('E_grid', 'N_grid',
+            a total-count column, a treatment-count column).
+    k_values : the k thresholds, e.g. [50, 100, 200, 400, 800].
+    unit_size : grid size in metres.
+    max_radius_units : search limit in grid units; unreached ks get
+            partial results (mirrors original EquiPop behaviour).
+    tie_mode : "ring" (default) adds all equidistant cells before
+            checking thresholds; "sequential" checks after every
+            single cell (original EquiPop, order-dependent).
+    decay : a Decay object, e.g. Decay(half_life_m=8000), or None.
+    naming : "short" (N_50, T_50, R_50, ...) or
+             "legacy" (IntervalSumCountAll_50, ...).
+    seed : only used with tie_mode="sequential": shuffles the (otherwise
+           arbitrary) within-ring visiting order reproducibly. Record it
+           in the run's metadata log. None keeps the construction order.
+
+    Returns
+    -------
+    One row per origin cell. Fixed columns: Id, EastWest, NorthSouth,
+    CountAllLocal, CountGroupLocal, SumCountAll, SumCountGroup, Ratio,
+    MaxDistance. Per-k columns as per the chosen naming scheme.
+    """
+    k_values = sorted(k_values)
+    nm = NAMES[naming]
+
+    def col(kind: str, k: int) -> str:
+        return nm[kind].format(k=k)
+
+    # ---- fast lookup: (E, N) -> (count_all, count_group) ----
+    lookup: dict[tuple[int, int], tuple[float, float]] = {}
+    for row in cells.itertuples(index=False):
+        key = (int(getattr(row, "E_grid")), int(getattr(row, "N_grid")))
+        lookup[key] = (float(getattr(row, count_all_col)),
+                       float(getattr(row, count_group_col)))
+
+    print(f"[analysis] {len(lookup)} populated cells, k = {k_values}, "
+          f"unit = {unit_size} m")
+    if decay:
+        print(f"[analysis] decay active: {decay.describe()}")
+    rings = build_distance_rings(max_radius_units)
+    if tie_mode == "sequential" and seed is not None:
+        rng = np.random.default_rng(seed)
+        rings = [(d, list(rng.permutation(np.array(offs, dtype=object))))
+                 for d, offs in rings]
+        print(f"[analysis] sequential tie order shuffled with seed {seed}")
+    print(f"[analysis] {len(rings)} distance rings ready")
+
+    results = []
+    step = int(unit_size)
+
+    for row in cells.itertuples(index=False):
+        e0 = int(getattr(row, "E_grid"))
+        n0 = int(getattr(row, "N_grid"))
+        local_all, local_grp = lookup[(e0, n0)]
+
+        rec: dict = {
+            "Id": getattr(row, id_col) if id_col else None,
+            "EastWest": e0,
+            "NorthSouth": n0,
+            "CountAllLocal": local_all,
+            "CountGroupLocal": local_grp,
+        }
+
+        # running totals - raw and (optionally) decay-weighted
+        sum_all, sum_grp, dist_m = local_all, local_grp, 0.0
+        d_all, d_grp = local_all, local_grp   # weight(0) = 1
+        pending = list(k_values)
+
+        def record(k: int):
+            """Write all per-k output columns at the current state."""
+            rec[col("N", k)] = sum_all
+            rec[col("T", k)] = sum_grp
+            rec[col("R", k)] = sum_grp / sum_all if sum_all else np.nan
+            rec[col("Dist", k)] = dist_m
+            if decay:
+                rec[col("ND", k)] = d_all
+                rec[col("TD", k)] = d_grp
+                rec[col("RD", k)] = d_grp / d_all if d_all else np.nan
+
+        # thresholds already satisfied inside the origin cell
+        while pending and sum_all >= pending[0]:
+            record(pending.pop(0))
+
+        # --- expand ring by ring ---
+        for dist_units, offsets in rings:
+            if not pending:
+                break
+            ring_dist_m = dist_units * unit_size
+            w = decay.weight(ring_dist_m) if decay else 1.0
+
+            if tie_mode == "sequential":
+                for dx, dy in offsets:
+                    cell = lookup.get((e0 + dx * step, n0 + dy * step))
+                    if not cell:
+                        continue
+                    sum_all += cell[0]
+                    sum_grp += cell[1]
+                    d_all += cell[0] * w
+                    d_grp += cell[1] * w
+                    dist_m = ring_dist_m
+                    while pending and sum_all >= pending[0]:
+                        record(pending.pop(0))
+            else:  # "ring" - atomic per equidistant ring
+                ring_all = ring_grp = 0.0
+                for dx, dy in offsets:
+                    cell = lookup.get((e0 + dx * step, n0 + dy * step))
+                    if cell:
+                        ring_all += cell[0]
+                        ring_grp += cell[1]
+                if ring_all == 0:
+                    continue
+                sum_all += ring_all
+                sum_grp += ring_grp
+                d_all += ring_all * w
+                d_grp += ring_grp * w
+                dist_m = ring_dist_m
+                while pending and sum_all >= pending[0]:
+                    record(pending.pop(0))
+
+        # unreached thresholds: partial results (spec, section 12)
+        for k in pending:
+            record(k)
+
+        rec["SumCountAll"] = sum_all
+        rec["SumCountGroup"] = sum_grp
+        rec["Ratio"] = sum_grp / sum_all if sum_all else np.nan
+        rec["MaxDistance"] = dist_m
+        results.append(rec)
+
+    out = pd.DataFrame(results)
+    fixed = ["Id", "EastWest", "NorthSouth", "CountAllLocal",
+             "CountGroupLocal", "SumCountAll", "SumCountGroup",
+             "Ratio", "MaxDistance"]
+    kinds = ["N", "T", "R", "Dist"] + (["ND", "TD", "RD"] if decay else [])
+    per_k = [col(kind, k) for k in k_values for kind in kinds]
+    return out[fixed + per_k]
+
+
+# ======================================================================
+#  run_knn_stats - k-NN with per-variable statistics (tiers 1-3)
+# ======================================================================
+from .cells import CellData
+from .stats import BINARY_STATS, VALUE_STATS, PREFIX
+
+
+def run_knn_stats(
+    cd: CellData,
+    k_values: list[int],
+    stats: dict[str, list[str]],
+    max_radius_units: int | None = None,
+) -> pd.DataFrame:
+    """
+    Radial k-NN analysis with user-selected statistics per variable.
+
+    The user switches statistics on per FUNCTION (applied to all k),
+    exactly as requested:
+
+        stats = {
+            "HighEdu": ["ratio", "sd", "se", "entropy", "gini"],  # binary
+            "ForvInk": ["mean", "median", "sd", "se", "gini"],    # value
+        }
+
+    Whether a variable is binary (tier 1, exact from counts) or
+    continuous (tiers 2/3, from stored individual values) is decided
+    by how it was declared in build_cells().
+
+    Engine note: this function uses a distance-sort core rather than
+    the ring-expansion core of run_knn(). For the radial (no-friction)
+    model the two are MATHEMATICALLY IDENTICAL - cells at equal
+    distance are still processed as one atomic ring - but the sort
+    core is much faster when populated cells are sparse. The
+    ring-expansion core remains the basis for the future friction
+    model, where visiting order genuinely depends on the path.
+
+    Output columns
+    --------------
+    EastWest, NorthSouth, N_local, plus per k:
+      N_{k}, Dist_{k},
+      per binary var+stat:  e.g. R_HighEdu_{k}, Gini_HighEdu_{k}
+      per value  var+stat:  e.g. Mean_ForvInk_{k}, Med_ForvInk_{k}
+      per value  var:       Nv_{var}_{k} (count of valid values)
+    Unreached k-levels receive partial results, as in run_knn().
+    """
+    k_values = sorted(k_values)
+
+    bin_vars = [v for v in stats if v in cd.binary_sums]
+    val_vars = [v for v in stats if v in cd.value_arrays]
+    unknown = [v for v in stats if v not in bin_vars + val_vars]
+    if unknown:
+        raise ValueError(f"Variables {unknown} were not declared in "
+                         f"build_cells(binary_vars=..., value_vars=...).")
+    for v in bin_vars:
+        for s in stats[v]:
+            if s not in BINARY_STATS:
+                raise ValueError(f"Unknown binary statistic '{s}' for {v}. "
+                                 f"Available: {list(BINARY_STATS)}")
+    for v in val_vars:
+        for s in stats[v]:
+            if s not in VALUE_STATS:
+                raise ValueError(f"Unknown value statistic '{s}' for {v}. "
+                                 f"Available: {list(VALUE_STATS)}")
+
+    m = len(cd)
+    print(f"[stats] {m} cells, k = {k_values}")
+    print(f"[stats] binary vars: {bin_vars} | value vars: {val_vars}")
+
+    results = []
+    Ef, Nf = cd.E.astype(float), cd.N.astype(float)
+
+    for oi in range(m):
+        e0, n0 = cd.E[oi], cd.N[oi]
+
+        # distances from this origin to ALL populated cells (vectorised)
+        dist = np.hypot(Ef - e0, Nf - n0)
+        order = np.argsort(dist, kind="stable")
+
+        rec: dict = {"EastWest": round(float(e0), 2),
+                     "NorthSouth": round(float(n0), 2),
+                     "N_local": float(cd.n[oi])}
+        if cd.labels is not None:
+            rec["CellId"] = cd.labels[oi]
+        for v in bin_vars:
+            rec[f"{v}_local"] = float(cd.binary_sums[v][oi])
+
+        # running state
+        sum_n = 0.0
+        bin_t = {v: 0.0 for v in bin_vars}
+        val_chunks = {v: [] for v in val_vars}
+        dist_m = 0.0
+        pending = list(k_values)
+
+        def record(k: int):
+            rec[f"N_{k}"] = sum_n
+            rec[f"Dist_{k}"] = dist_m
+            for v in bin_vars:
+                for s in stats[v]:
+                    rec[f"{PREFIX[s]}_{v}_{k}"] = BINARY_STATS[s](sum_n, bin_t[v])
+            for v in val_vars:
+                x = (np.concatenate(val_chunks[v])
+                     if val_chunks[v] else np.empty(0))
+                rec[f"Nv_{v}_{k}"] = len(x)
+                for s in stats[v]:
+                    rec[f"{PREFIX[s]}_{v}_{k}"] = VALUE_STATS[s](x)
+
+        # walk cells in distance order, atomically per equal-distance ring
+        j = 0
+        while j < m and pending:
+            d = dist[order[j]]
+            if max_radius_units is not None and d > max_radius_units * cd.unit_size:
+                break
+            # gather the full ring of cells at this exact distance
+            ring = []
+            while j < m and dist[order[j]] - d < 1e-6:
+                ring.append(order[j])
+                j += 1
+            for ci in ring:
+                sum_n += float(cd.n[ci])
+                for v in bin_vars:
+                    bin_t[v] += cd.binary_sums[v][ci]
+                for v in val_vars:
+                    a = cd.value_arrays[v][ci]
+                    if len(a):
+                        val_chunks[v].append(a)
+            dist_m = float(d)
+            while pending and sum_n >= pending[0]:
+                record(pending.pop(0))
+
+        for k in pending:          # unreached: partial results
+            record(k)
+        rec["SumN"] = sum_n
+        rec["MaxDistance"] = dist_m
+        results.append(rec)
+
+    return pd.DataFrame(results)

equipop/area.py

@@ -0,0 +1,121 @@
+"""
+area.py - area-based output (backlog item 9): bring overlapping
+bespoke-neighbourhood results back to fixed geographies that policy
+audiences grasp.
+
+DELIBERATE DESIGN, stated for reviewers: values are collected
+overlappingly with k and then SUMMARISED per area - this is
+"individualised context, reported per area", not a recomputation of
+areal statistics. The precedent is the block-level illustration of
+EquiPop output in Östh, Clark & Malmberg (2015, fig. 1).
+
+Three alternatives, one function:
+  Alt 1  by = a COLUMN NAME already on the output (belonging ID,
+         e.g. a municipality code carried through CellId/merge).
+  Alt 2  by = a POLYGON FILE path (shp/gpkg): origin cells are
+         point-in-polygon assigned (geopandas sjoin); `id_field`
+         names the polygon attribute to aggregate by. `points_epsg`
+         must be given if it differs from the polygons' CRS.
+  Alt 3  by = a NUMBER: a coarser grid size (e.g. 1000 for 1 km
+         super-cells over 100 m results), anchored at the minimum
+         X/Y of the data.
+"""
+
+import numpy as np
+import pandas as pd
+
+
+def aggregate_output(
+    df: pd.DataFrame,
+    by,
+    columns: list[str] | None = None,
+    how: str = "wmean",
+    weight_col: str = "N_local",
+    id_field: str | None = None,
+    points_epsg: int | None = None,
+    x_col: str = "EastWest",
+    y_col: str = "NorthSouth",
+) -> pd.DataFrame:
+    """
+    Aggregate k-NN output to areas. See module docstring for the three
+    `by` alternatives.
+
+    columns : which output columns to aggregate (default: all R_*,
+              Mean_*, Med_*, Gini_*, SD_* columns found).
+    how     : 'wmean' population-weighted mean (weights = weight_col,
+              typically the origin population), 'mean', or 'median'.
+    Returns one row per area with the aggregated columns, the number
+    of origin cells, and the summed weight.
+    """
+    df = df.copy()
+    if columns is None:
+        columns = [c for c in df.columns if c.split("_")[0] in
+                   ("R", "Mean", "Med", "Gini", "SD", "Ratio")]
+        if not columns:
+            raise ValueError("No aggregatable columns found - pass "
+                             "columns=[...] explicitly.")
+
+    # ---- resolve `by` into a per-row area label ----
+    if isinstance(by, (int, float)):                       # Alt 3
+        u = float(by)
+        x0, y0 = df[x_col].min(), df[y_col].min()
+        df["_area"] = (
+            "SG" + (np.floor((df[x_col] - x0) / u)).astype(int).astype(str)
+            + "_" + (np.floor((df[y_col] - y0) / u)).astype(int).astype(str))
+        label = f"supergrid_{int(u)}m"
+    elif isinstance(by, str) and by in df.columns:         # Alt 1
+        df["_area"] = df[by]
+        label = by
+    elif isinstance(by, str):                              # Alt 2: file
+        try:
+            import geopandas as gpd
+        except ImportError:
+            raise ImportError("Polygon aggregation needs geopandas.")
+        polys = gpd.read_file(by)
+        if id_field is None:
+            raise ValueError("Give id_field=<polygon attribute>.")
+        pts = gpd.GeoDataFrame(
+            df[[x_col, y_col]],
+            geometry=gpd.points_from_xy(df[x_col], df[y_col]),
+            crs=f"EPSG:{points_epsg}" if points_epsg else polys.crs)
+        if points_epsg and pts.crs != polys.crs:
+            pts = pts.to_crs(polys.crs)
+            print(f"[area] points reprojected EPSG:{points_epsg} -> "
+                  f"{polys.crs.to_epsg()} for the join")
+        joined = gpd.sjoin(pts, polys[[id_field, "geometry"]],
+                           how="left", predicate="within")
+        df["_area"] = joined[id_field].to_numpy()
+        unmatched = df["_area"].isna().sum()
+        if unmatched:
+            print(f"[area] WARNING: {unmatched} origin cells fall outside "
+                  f"all polygons (dropped from area output).")
+            df = df[df["_area"].notna()]
+        label = id_field
+    else:
+        raise ValueError("`by` must be a column name, a polygon file "
+                         "path, or a super-grid size in metres.")
+
+    # ---- aggregate ----
+    w = df[weight_col].to_numpy(float)
+    out_rows = []
+    for area, g in df.groupby("_area"):
+        gw = g[weight_col].to_numpy(float)
+        row = {label: area, "n_origin_cells": len(g),
+               weight_col + "_sum": gw.sum()}
+        for c in columns:
+            v = g[c].to_numpy(float)
+            ok = np.isfinite(v)
+            if not ok.any():
+                row[c] = np.nan
+            elif how == "wmean":
+                row[c] = np.average(v[ok], weights=gw[ok]) \
+                    if gw[ok].sum() > 0 else np.nan
+            elif how == "mean":
+                row[c] = v[ok].mean()
+            elif how == "median":
+                row[c] = np.median(v[ok])
+        out_rows.append(row)
+    out = pd.DataFrame(out_rows)
+    print(f"[area] {len(df)} origin cells -> {len(out)} areas "
+          f"('{label}', how={how})")
+    return out

equipop/cells.py

@@ -0,0 +1,139 @@
+"""
+cells.py - build cell-level data from INDIVIDUAL-level rows.
+
+This is the entry point for "tier 3" data: one row per individual,
+where several individuals may share the same coordinate. The builder
+aggregates them into grid cells while keeping, per cell:
+
+  - n            : the individual count (this is what k counts!)
+  - binary sums  : one running sum per binary variable (0/1)
+  - value arrays : the raw individual values per continuous variable
+                   (needed for exact median / Gini at k-level)
+
+Missing handling (spec section 12):
+  - rows with missing coordinates are DROPPED with a printed warning
+  - missing values in a continuous variable: the individual still
+    counts towards k, but contributes no value to that variable's
+    statistics (a separate valid-n is reported as Nv_<var>_<k>)
+"""
+
+import numpy as np
+import pandas as pd
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CellData:
+    """Aggregated per-cell data ready for run_knn_stats()."""
+    E: np.ndarray                 # cell midpoint eastings  (m cells)
+    N: np.ndarray                 # cell midpoint northings
+    n: np.ndarray                 # individuals per cell
+    binary_sums: dict = field(default_factory=dict)   # var -> array (m,)
+    value_arrays: dict = field(default_factory=dict)  # var -> list of arrays
+    unit_size: float = 100.0
+    labels: list | None = None    # optional per-cell ID/label (e.g. place, year)
+
+    def __len__(self):
+        return len(self.n)
+
+
+def build_cells(
+    df: pd.DataFrame,
+    e_col: str,
+    n_col: str,
+    binary_vars: list[str] | None = None,
+    value_vars: list[str] | None = None,
+    unit_size: float = 100.0,
+    snap: bool = True,
+    label_col: str | None = None,
+) -> CellData:
+    """
+    Aggregate an individual-level DataFrame into CellData.
+
+    Parameters
+    ----------
+    df : one row per individual.
+    e_col, n_col : METRIC coordinate columns (already projected).
+    binary_vars : 0/1 columns (each becomes a treatment with exact
+                  count-based statistics).
+    value_vars : continuous columns (individual values are stored
+                 per cell for exact median/Gini/etc.).
+    unit_size : grid size in metres.
+    snap : snap coordinates to grid midpoints. Idempotent - if the
+           data is already midpoint-snapped (like 100m register data
+           ending in ...50), snapping changes nothing.
+    label_col : optional ID column carried through to the output
+           (e.g. a place code or a year). If a cell contains SEVERAL
+           distinct labels they are joined with '|' and a warning is
+           printed - a good ID should be constant within a cell.
+    """
+    binary_vars = binary_vars or []
+    value_vars = value_vars or []
+    df = df.copy()
+
+    # --- coerce to numeric; blanks become NaN ---
+    for c in [e_col, n_col] + binary_vars + value_vars:
+        df[c] = pd.to_numeric(df[c], errors="coerce")
+
+    # --- missing coordinates: drop with warning (spec 12) ---
+    bad = df[e_col].isna() | df[n_col].isna()
+    if bad.any():
+        print(f"[cells] WARNING: {bad.sum()} of {len(df)} rows have "
+              f"missing coordinates and are dropped.")
+        df = df[~bad]
+
+    # --- snap to grid midpoints ---
+    if snap:
+        half = unit_size / 2.0
+        df["_E"] = (np.floor(df[e_col] / unit_size) * unit_size + half).astype(int)
+        df["_N"] = (np.floor(df[n_col] / unit_size) * unit_size + half).astype(int)
+    else:
+        df["_E"] = df[e_col].astype(int)
+        df["_N"] = df[n_col].astype(int)
+
+    # --- report missing values in analysis variables ---
+    for v in value_vars:
+        miss = df[v].isna().sum()
+        if miss:
+            print(f"[cells] note: '{v}' has {miss} missing values - these "
+                  f"individuals count towards k but not towards {v} statistics.")
+
+    # --- aggregate ---
+    groups = df.groupby(["_E", "_N"], sort=True)
+    E, N, n = [], [], []
+    bsums = {v: [] for v in binary_vars}
+    varrs = {v: [] for v in value_vars}
+    labels = [] if label_col else None
+    mixed = 0
+
+    for (e, nn), g in groups:
+        E.append(e)
+        N.append(nn)
+        n.append(len(g))
+        for v in binary_vars:
+            bsums[v].append(g[v].sum())
+        for v in value_vars:
+            varrs[v].append(g[v].dropna().to_numpy(dtype=float))
+        if label_col:
+            uniq = g[label_col].astype(str).unique()
+            if len(uniq) > 1:
+                mixed += 1
+            labels.append("|".join(sorted(uniq)))
+
+    if label_col and mixed:
+        print(f"[cells] WARNING: {mixed} cells contain several distinct "
+              f"'{label_col}' values (joined with '|'). A good cell ID "
+              f"should be constant within a cell.")
+
+    cd = CellData(
+        E=np.array(E, dtype=np.int64),
+        N=np.array(N, dtype=np.int64),
+        n=np.array(n, dtype=np.int64),
+        binary_sums={v: np.array(a, dtype=float) for v, a in bsums.items()},
+        value_arrays=varrs,
+        unit_size=unit_size,
+        labels=labels,
+    )
+    print(f"[cells] {len(df)} individuals -> {len(cd)} cells "
+          f"(unit {unit_size} m, global N = {cd.n.sum()})")
+    return cd