kintsugi-st 0.1.0__py3-none-any.whl

kintsugi/__init__.py

@@ -0,0 +1,168 @@
+"""Kintsugi: adaptive spatial tessellation for sub-cellular transcriptomics."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .models import TessellationResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "GridData",
+    "TessellationReport",
+    "TessellationResult",
+    "build_regular_grid",
+    "load_10x_feature_matrix",
+    "load_visium_hd",
+    "load_visium_hd_from_dir",
+    "parse_visium_barcode_coordinates",
+    "read_tissue_positions",
+    "validate_grid_data",
+    "adaptive_tessellation",
+    "aggregate_counts",
+    "boundary_tensor",
+    "build_spatial_graph",
+    "directional_semivariance",
+    "poisson_baseline",
+    "poisson_log_variance",
+    "make_toy_dataset",
+    "tessellate",
+    "tessellation_report",
+    "to_anndata",
+]
+
+_LAZY_EXPORTS = {
+    "GridData": (".models", "GridData"),
+    "TessellationReport": (".report", "TessellationReport"),
+    "TessellationResult": (".models", "TessellationResult"),
+    "validate_grid_data": (".models", "validate_grid_data"),
+    "build_regular_grid": (".io", "build_regular_grid"),
+    "load_10x_feature_matrix": (".io", "load_10x_feature_matrix"),
+    "load_visium_hd": (".io", "load_visium_hd"),
+    "load_visium_hd_from_dir": (".io", "load_visium_hd_from_dir"),
+    "parse_visium_barcode_coordinates": (".io", "parse_visium_barcode_coordinates"),
+    "read_tissue_positions": (".io", "read_tissue_positions"),
+    "to_anndata": (".io", "to_anndata"),
+    "directional_semivariance": (".variogram", "directional_semivariance"),
+    "poisson_baseline": (".variogram", "poisson_baseline"),
+    "poisson_log_variance": ("._poisson_log_var", "poisson_log_variance"),
+    "boundary_tensor": (".tensor", "boundary_tensor"),
+    "adaptive_tessellation": (".partition", "adaptive_tessellation"),
+    "aggregate_counts": (".aggregate", "aggregate_counts"),
+    "build_spatial_graph": (".graph", "build_spatial_graph"),
+    "tessellation_report": (".report", "tessellation_report"),
+    "make_toy_dataset": ("._demo", "make_toy_dataset"),
+}
+
+
+def __getattr__(name: str):
+    if name not in _LAZY_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    module_name, attr_name = _LAZY_EXPORTS[name]
+    value = getattr(import_module(module_name, __name__), attr_name)
+    globals()[name] = value
+    return value
+
+
+def tessellate(
+    counts,
+    rows: int | None = None,
+    cols: int | None = None,
+    mask=None,
+    lag: int = 2,
+    kappa: float = 2.0,
+    min_seed_distance: int = 4,
+    smooth_sigma: float = 4.0,
+) -> "TessellationResult":
+    """Run the full Kintsugi pipeline: variogram -> tensor -> partition -> aggregate -> graph.
+
+    Parameters
+    ----------
+    counts : GridData or sparse matrix
+        Either a normalized ``GridData`` container or a sparse UMI count
+        matrix with shape ``(rows * cols, genes)`` in row-major grid order.
+    rows, cols : int
+        Grid dimensions. Required when ``counts`` is not a ``GridData`` instance.
+    mask : ndarray, shape (rows, cols), dtype bool, optional
+        True for in-tissue bins. Ignored when ``counts`` is a ``GridData`` instance.
+    lag : int
+        Variogram lag in bin units (2 bins = 4 um on a 2 um grid).
+    kappa : float
+        Stationarity tolerance (in SE units) for region growing.
+    min_seed_distance : int
+        Minimum seed separation in bins.
+    smooth_sigma : float
+        Gaussian sigma (bins) for trace smoothing before seed detection.
+
+    Returns
+    -------
+    result : TessellationResult with fields
+        ``"labels"``      : ndarray (rows, cols) int32, region labels (0-indexed, -1 outside mask)
+        ``"residuals"``   : ndarray (K, G) float64, Pearson residuals
+        ``"areas"``       : ndarray (K,) float64, bins per region
+        ``"depths"``      : ndarray (K,) float64, total UMI per region
+        ``"centroids"``   : ndarray (K, 2) float64, (row, col) centroids
+        ``"adjacency"``   : csr_matrix (K, K), spatial adjacency graph
+        ``"trace"``       : ndarray (rows, cols) float64, boundary-tensor trace
+    """
+    from .models import GridData, TessellationResult
+
+    if isinstance(counts, GridData):
+        if rows is not None or cols is not None or mask is not None:
+            raise ValueError(
+                "rows, cols, and mask must not be passed separately when counts is a GridData instance."
+            )
+        grid = counts
+        counts = grid.counts
+        rows = grid.rows
+        cols = grid.cols
+        mask = grid.mask
+    else:
+        if rows is None or cols is None:
+            raise TypeError(
+                "rows and cols are required when counts is not a GridData instance."
+            )
+        grid = GridData(counts, rows=rows, cols=cols, mask=mask)
+        counts = grid.counts
+        rows = grid.rows
+        cols = grid.cols
+        mask = grid.mask
+
+    import numpy as np
+
+    from .aggregate import aggregate_counts
+    from .graph import build_spatial_graph
+    from .partition import adaptive_tessellation
+    from .tensor import boundary_tensor
+    from .variogram import directional_semivariance
+
+    umi_flat = np.asarray(counts.sum(axis=1)).ravel()
+    umi = umi_flat.reshape(rows, cols)
+
+    excess = directional_semivariance(umi, lag=lag, mask=mask)
+    trace, _lambda1, _lambda2, evec1 = boundary_tensor(excess)
+    labels = adaptive_tessellation(
+        umi, trace, evec1,
+        kappa=kappa,
+        min_seed_distance=min_seed_distance,
+        smooth_sigma=smooth_sigma,
+        mask=mask,
+    )
+
+    residuals, areas, depths, centroids = aggregate_counts(counts, labels, mask=mask)
+    adjacency = build_spatial_graph(labels)
+
+    return TessellationResult(
+        labels=labels,
+        residuals=residuals,
+        areas=areas,
+        depths=depths,
+        centroids=centroids,
+        adjacency=adjacency,
+        trace=trace,
+    )

kintsugi/_demo.py

@@ -0,0 +1,169 @@
+"""Built-in demo: toy data generation and one-command pipeline.
+
+This module is shipped inside the wheel so that ``pip install`` users
+can run the demo without cloning the repository::
+
+    kintsugi-demo            # CLI entry point
+    python -m kintsugi.demo  # module invocation
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+
+import numpy as np
+import scipy.sparse as sp
+
+
+# ---------------------------------------------------------------------------
+# Toy dataset (self-contained, no external dependency)
+# ---------------------------------------------------------------------------
+
+def make_toy_dataset(
+    rows: int = 60,
+    cols: int = 60,
+    n_genes: int = 100,
+    seed: int = 2024,
+):
+    """Create a synthetic spatial transcriptomics grid.
+
+    Returns a ``kintsugi.GridData`` with four spatially distinct domains:
+
+    - **Top-left** (domain 0): high density, marker genes in first quarter.
+    - **Top-right** (domain 1): medium density, marker genes in second quarter.
+    - **Bottom-left** (domain 2): medium density, marker genes in third quarter.
+    - **Bottom-right** (domain 3): low density, marker genes in last quarter.
+
+    A circular tissue mask excludes corner bins.
+
+    Parameters
+    ----------
+    rows, cols : int
+        Grid dimensions (default 60×60 = 3,600 bins).
+    n_genes : int
+        Number of genes (default 100).
+    seed : int
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    grid : kintsugi.GridData
+        Normalized grid ready for ``grid.tessellate()``.
+    """
+    from . import GridData
+
+    rng = np.random.default_rng(seed)
+
+    rr, cc = np.mgrid[:rows, :cols]
+    centre_r, centre_c = rows / 2 - 0.5, cols / 2 - 0.5
+    dist = np.sqrt((rr - centre_r) ** 2 + (cc - centre_c) ** 2)
+    mask = dist <= 28.0
+
+    domain = np.full((rows, cols), -1, dtype=np.int32)
+    domain[(rr < rows // 2) & (cc < cols // 2)] = 0
+    domain[(rr < rows // 2) & (cc >= cols // 2)] = 1
+    domain[(rr >= rows // 2) & (cc < cols // 2)] = 2
+    domain[(rr >= rows // 2) & (cc >= cols // 2)] = 3
+
+    base_rates = {0: 12.0, 1: 7.0, 2: 7.0, 3: 4.0}
+
+    block = n_genes // 4
+    gene_profiles = np.ones((4, n_genes)) * 0.1
+    gene_profiles[0, 0:block] = 2.0
+    gene_profiles[1, block:2 * block] = 2.0
+    gene_profiles[2, 2 * block:3 * block] = 2.0
+    gene_profiles[3, 3 * block:n_genes] = 2.0
+    gene_profiles = gene_profiles / gene_profiles.sum(axis=1, keepdims=True)
+
+    N = rows * cols
+    data_rows = []
+    data_cols = []
+    data_vals = []
+
+    for r in range(rows):
+        for c in range(cols):
+            if not mask[r, c]:
+                continue
+            d = domain[r, c]
+            if d < 0:
+                continue
+            total_umi = rng.poisson(base_rates[d])
+            if total_umi == 0:
+                continue
+            gene_counts = rng.multinomial(total_umi, gene_profiles[d])
+            nz_idx = np.where(gene_counts > 0)[0]
+            flat_idx = r * cols + c
+            for g in nz_idx:
+                data_rows.append(flat_idx)
+                data_cols.append(g)
+                data_vals.append(float(gene_counts[g]))
+
+    counts = sp.coo_matrix(
+        (data_vals, (data_rows, data_cols)),
+        shape=(N, n_genes),
+    ).tocsr()
+
+    gene_names = np.array([f"Gene_{g:03d}" for g in range(n_genes)])
+
+    return GridData(
+        counts, rows=rows, cols=cols, mask=mask, gene_names=gene_names,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Demo entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """Run the full Kintsugi demo pipeline."""
+    from . import __version__, tessellation_report, to_anndata
+
+    print(f"Kintsugi v{__version__}")
+    print("=" * 55)
+
+    print("\n1. Generating toy dataset...")
+    t0 = time.perf_counter()
+    grid = make_toy_dataset()
+    t_data = time.perf_counter() - t0
+    print(f"   Grid: {grid.rows}\u00d7{grid.cols}, {grid.n_genes} genes, "
+          f"{int(grid.mask.sum()):,} tissue bins")
+    print(f"   Time: {t_data:.2f}s")
+
+    print("\n2. Running tessellation...")
+    t0 = time.perf_counter()
+    result = grid.tessellate()
+    t_tess = time.perf_counter() - t0
+    print(f"   Regions: {result.n_regions}")
+    print(f"   Time: {t_tess:.2f}s")
+
+    print("\n3. Diagnostic report:")
+    t0 = time.perf_counter()
+    report = tessellation_report(result, grid)
+    t_report = time.perf_counter() - t0
+    print(report)
+    print(f"   Report time: {t_report:.2f}s")
+
+    label_hash = hashlib.sha256(result.labels.tobytes()).hexdigest()[:16]
+    print("\n4. Determinism check:")
+    print(f"   Label hash (sha256[:16]): {label_hash}")
+
+    print("\n5. AnnData export:")
+    try:
+        adata = to_anndata(result, grid=grid, use_raw_counts=True)
+        print(f"   Shape: {adata.shape}")
+        print(f"   obs:   {list(adata.obs.columns)}")
+        print(f"   obsm:  {list(adata.obsm.keys())}")
+        print(f"   obsp:  {list(adata.obsp.keys())}")
+        print(f"   layers: {list(adata.layers.keys())}")
+    except ImportError:
+        print("   Skipped (anndata not installed).")
+        print("   Install with: pip install 'kintsugi-st[anndata]'")
+
+    total = t_data + t_tess + t_report
+    print(f"\nTotal runtime: {total:.2f}s")
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

kintsugi/_poisson_log_var.py

@@ -0,0 +1,104 @@
+"""Poisson-log variance: Var[log(N+1)] for N ~ Poisson(lambda).
+
+The trigamma function psi^(1)(lambda+1) equals Var[log(X)] for
+X ~ Gamma(lambda+1, 1), which is a continuous approximation.  The exact
+discrete quantity requires summing over the Poisson PMF.  The two
+converge as lambda -> inf (relative error < 0.8% for lambda >= 10),
+but diverge substantially at small lambda (2.69x overestimate at
+lambda = 1).
+
+This module provides a vectorized implementation using a precomputed
+lookup table with linear interpolation for lambda in [0, 500], and
+falls back to the trigamma for lambda > 500 (relative error < 1e-8).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.special import gammaln, polygamma
+
+
+# ---------------------------------------------------------------------------
+# Scalar computation (used to build the lookup table)
+# ---------------------------------------------------------------------------
+
+def _exact_scalar(lam: float) -> float:
+    """Exact Var[log(N+1)] for a single lambda value."""
+    if lam <= 0.0:
+        return 0.0
+
+    # Truncation bound: tail probability < 1e-15.
+    n_max = int(max(20, lam + 12.0 * np.sqrt(lam) + 10))
+    n = np.arange(0, n_max + 1, dtype=np.float64)
+
+    # Log-space Poisson PMF for numerical stability.
+    log_pmf = n * np.log(lam) - lam - gammaln(n + 1.0)
+    pmf = np.exp(log_pmf)
+
+    log_np1 = np.log(n + 1.0)
+
+    m1 = np.dot(pmf, log_np1)          # E[log(N+1)]
+    m2 = np.dot(pmf, log_np1 ** 2)     # E[log(N+1)^2]
+    return float(m2 - m1 * m1)
+
+
+_LUT_STEP = 0.1
+_LUT_MAX = 500.0
+_LUT_N = int(_LUT_MAX / _LUT_STEP) + 1
+_LUT_LAMBDAS: np.ndarray | None = None
+_LUT_VALUES: np.ndarray | None = None
+
+
+def _lookup_table() -> tuple[np.ndarray, np.ndarray]:
+    global _LUT_LAMBDAS, _LUT_VALUES
+    if _LUT_LAMBDAS is None or _LUT_VALUES is None:
+        lambdas = np.linspace(0.0, _LUT_MAX, _LUT_N)
+        values = np.array([_exact_scalar(lam) for lam in lambdas], dtype=np.float64)
+        _LUT_LAMBDAS = lambdas
+        _LUT_VALUES = values
+    return _LUT_LAMBDAS, _LUT_VALUES
+
+
+# ---------------------------------------------------------------------------
+# Public vectorized function
+# ---------------------------------------------------------------------------
+
+def poisson_log_variance(lam: np.ndarray | float) -> np.ndarray | float:
+    r"""Approximate Var[log(N+1)] for N ~ Poisson(lam), vectorized.
+
+    For lam <= 500: linear interpolation on a lazily built exact table
+    (absolute error < 1e-4 at worst, typically < 1e-5).
+    For lam > 500: trigamma(lam+1) (relative error < 1e-8).
+
+    Parameters
+    ----------
+    lam : array_like
+        Poisson rate parameter(s).  Must be non-negative.
+
+    Returns
+    -------
+    var : same shape as lam
+        Var[log(N+1)] for each element.
+    """
+    scalar = np.ndim(lam) == 0
+    lam_arr = np.asarray(lam, dtype=np.float64)
+    if np.any(~np.isfinite(lam_arr)) or np.any(lam_arr < 0):
+        raise ValueError("lam must contain only finite non-negative values.")
+
+    shape = lam_arr.shape
+    flat = lam_arr.ravel()
+
+    result = np.empty_like(flat)
+
+    lo = flat <= _LUT_MAX
+    hi = ~lo
+
+    if np.any(lo):
+        lut_lambdas, lut_values = _lookup_table()
+        result[lo] = np.interp(flat[lo], lut_lambdas, lut_values)
+    if np.any(hi):
+        result[hi] = polygamma(1, flat[hi] + 1.0)
+
+    if scalar:
+        return float(result[0])
+    return result.reshape(shape)

kintsugi/aggregate.py

@@ -0,0 +1,138 @@
+"""Null-aware count aggregation and Pearson residual normalization.
+
+Aggregates a sparse (N x G) count matrix over an irregular partition
+into a dense (K x G) residual matrix, where K << N.  All operations
+keep the input sparse until the final K x G product.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import scipy.sparse as sp
+
+
+def aggregate_counts(
+    counts: sp.csr_matrix,
+    labels: np.ndarray,
+    mask: np.ndarray | None = None,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """Aggregate bin-level counts into region-level Pearson residuals.
+
+    Parameters
+    ----------
+    counts : csr_matrix, shape (N, G)
+        Sparse UMI count matrix.  Row order must match the row-major
+        (C-order) flattening of the 2D lattice: bin (r, c) maps to
+        row ``r * C + c``.
+    labels : ndarray, shape (R, C), dtype int32
+        Region labels from ``adaptive_tessellation``.  Values in
+        ``[0, K)``.  Bins with label -1 are excluded.
+    mask : ndarray, shape (R, C), dtype bool, optional
+        If provided, only bins where mask is True are aggregated.
+        Bins outside the mask are ignored regardless of their label.
+
+    Returns
+    -------
+    residuals : ndarray, shape (K, G)
+        Pearson residuals ``(observed - expected) / sqrt(expected)``.
+    areas : ndarray, shape (K,)
+        Number of native bins per region.
+    depths : ndarray, shape (K,)
+        Total UMI per region.
+    centroids : ndarray, shape (K, 2)
+        Region centroids in (row, col) grid coordinates.
+    """
+    if labels.ndim != 2:
+        raise ValueError("labels must be a 2D array.")
+    if not sp.issparse(counts):
+        raise TypeError("counts must be a SciPy sparse matrix.")
+    if not sp.isspmatrix_csr(counts):
+        counts = counts.tocsr()
+    if counts.data.size and (
+        np.any(~np.isfinite(counts.data)) or np.any(counts.data < 0)
+    ):
+        raise ValueError("counts must contain only finite non-negative values.")
+
+    R, C = labels.shape
+    N = R * C
+
+    if counts.shape[0] != N:
+        raise ValueError(
+            f"Count matrix has {counts.shape[0]} rows but label grid has "
+            f"{N} bins ({R} x {C})."
+        )
+    if mask is not None:
+        mask = np.asarray(mask, dtype=bool)
+        if mask.shape != labels.shape:
+            raise ValueError(
+                f"mask has shape {mask.shape}, expected {labels.shape}."
+            )
+
+    flat_labels = labels.ravel()  # (N,)
+
+    # Build inclusion mask.
+    include = flat_labels >= 0
+    if mask is not None:
+        include = include & mask.ravel()
+
+    G = counts.shape[1]
+
+    # --- Sparse indicator matrix (K x N) ----------------------------------
+    valid_idx = np.where(include)[0]
+    if valid_idx.size == 0:
+        empty = np.zeros((0, G), dtype=np.float64)
+        return (
+            empty,
+            np.zeros(0, dtype=np.float64),
+            np.zeros(0, dtype=np.float64),
+            np.zeros((0, 2), dtype=np.float64),
+        )
+
+    valid_labels = flat_labels[valid_idx].astype(np.int64, copy=False)
+    K = int(valid_labels.max()) + 1
+
+    indicator = sp.csr_matrix(
+        (np.ones(valid_idx.size, dtype=np.uint8), (valid_labels, valid_idx)),
+        shape=(K, N),
+    )
+
+    # --- Aggregated counts Y' = indicator @ counts  (K x G) ---------------
+    # counts is (N, G) sparse; indicator is (K, N) sparse.
+    # Result is (K, G) — dense since K ~ 10^3-10^5, fits in memory.
+    agg_counts = (indicator @ counts).toarray().astype(np.float64, copy=False)  # (K, G)
+
+    # --- Region statistics ------------------------------------------------
+    areas = np.bincount(valid_labels, minlength=K).astype(np.float64, copy=False)
+    depths = agg_counts.sum(axis=1)                     # (K,)
+    N_total = depths.sum()
+
+    # Gene totals across all included bins.
+    gene_totals = np.asarray(agg_counts.sum(axis=0)).ravel()  # (G,)
+
+    # --- Centroids --------------------------------------------------------
+    row_coords, col_coords = np.divmod(valid_idx, C)
+    centroid_rows = np.bincount(
+        valid_labels,
+        weights=row_coords.astype(np.float64),
+        minlength=K,
+    )
+    centroid_cols = np.bincount(
+        valid_labels,
+        weights=col_coords.astype(np.float64),
+        minlength=K,
+    )
+    safe_areas = np.maximum(areas, 1.0)
+    centroids = np.column_stack([centroid_rows / safe_areas, centroid_cols / safe_areas])
+
+    # --- Pearson residuals ------------------------------------------------
+    # mu_kj = depth_k * gene_j / N_total
+    if N_total == 0:
+        return np.zeros((K, G), dtype=np.float64), areas, depths, centroids
+
+    expected = (depths[:, None] * gene_totals[None, :]) / N_total
+    np.subtract(agg_counts, expected, out=agg_counts)
+    np.maximum(expected, 1e-12, out=expected)
+    np.sqrt(expected, out=expected)
+    np.divide(agg_counts, expected, out=agg_counts)
+
+    return agg_counts, areas, depths, centroids

kintsugi/demo/__init__.py

@@ -0,0 +1,5 @@
+"""Kintsugi demo — runnable via ``python -m kintsugi.demo``."""
+
+from .._demo import main, make_toy_dataset
+
+__all__ = ["main", "make_toy_dataset"]

kintsugi/demo/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m kintsugi.demo``."""
+
+from .._demo import main
+
+main()

kintsugi/graph.py

@@ -0,0 +1,74 @@
+"""Spatial graph construction from an irregular tessellation.
+
+Builds a region adjacency graph: two regions are connected if they share
+at least one pair of rook-adjacent (4-connected) native bins.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import scipy.sparse as sp
+
+
+def build_spatial_graph(
+    labels: np.ndarray,
+) -> sp.csr_matrix:
+    """Build a symmetric binary adjacency matrix from region labels.
+
+    Parameters
+    ----------
+    labels : ndarray, shape (R, C), dtype int32
+        Region labels from ``adaptive_tessellation``.  Values in
+        ``[0, K)``.  Bins with label -1 are ignored.
+
+    Returns
+    -------
+    adjacency : csr_matrix, shape (K, K)
+        Symmetric binary adjacency (no self-loops).
+    """
+    if labels.ndim != 2:
+        raise ValueError("labels must be a 2D array.")
+
+    R, C = labels.shape
+    valid_labels = labels[labels >= 0]
+    if valid_labels.size == 0:
+        return sp.csr_matrix((0, 0), dtype=np.uint8)
+    K = int(valid_labels.max()) + 1
+
+    edges_r: list[np.ndarray] = []
+    edges_c: list[np.ndarray] = []
+
+    # Horizontal neighbours: compare labels[:, :-1] with labels[:, 1:]
+    left = labels[:, :-1].ravel()
+    right = labels[:, 1:].ravel()
+    valid = (left >= 0) & (right >= 0) & (left != right)
+    edges_r.append(left[valid])
+    edges_c.append(right[valid])
+
+    # Vertical neighbours: compare labels[:-1, :] with labels[1:, :]
+    top = labels[:-1, :].ravel()
+    bot = labels[1:, :].ravel()
+    valid = (top >= 0) & (bot >= 0) & (top != bot)
+    edges_r.append(top[valid])
+    edges_c.append(bot[valid])
+
+    if not any(edge.size for edge in edges_r):
+        return sp.csr_matrix((K, K), dtype=np.uint8)
+
+    row = np.concatenate(edges_r)
+    col = np.concatenate(edges_c)
+
+    # Symmetrize.
+    row_sym = np.concatenate([row, col])
+    col_sym = np.concatenate([col, row])
+    data = np.ones(row_sym.size, dtype=np.uint8)
+
+    adj = sp.coo_matrix((data, (row_sym, col_sym)), shape=(K, K))
+    # Remove duplicates and ensure binary.
+    adj = adj.tocsr()
+    adj.data[:] = 1
+    # Remove any self-loops (should not exist but be safe).
+    adj.setdiag(0)
+    adj.eliminate_zeros()
+
+    return adj

kintsugi/io/__init__.py

@@ -0,0 +1,20 @@
+"""Input/output adapters for Kintsugi grid data."""
+
+from .anndata import to_anndata
+from .grid import build_regular_grid, parse_visium_barcode_coordinates
+from .visium_hd import (
+    load_10x_feature_matrix,
+    load_visium_hd,
+    load_visium_hd_from_dir,
+    read_tissue_positions,
+)
+
+__all__ = [
+    "build_regular_grid",
+    "load_10x_feature_matrix",
+    "load_visium_hd",
+    "load_visium_hd_from_dir",
+    "parse_visium_barcode_coordinates",
+    "read_tissue_positions",
+    "to_anndata",
+]