spatial-link 0.1.0

Spatial-Link: Weekly BFS + Monte Carlo framework for detecting statistically significant directed linkages from spatio-temporal data.

Spatial-Link

Spatial-Link is a weekly graph-based framework (BFS → Monte Carlo) for detecting
statistically significant directed linkages in spatio-temporal data.

Spatial-Link was originally developed to address a core iHARP research problem:
understanding the interaction between sea ice retreat and ice shelf melting in the Antarctic.
Within this context, the method was designed to capture how heterogeneous spatio-temporal phenomena interact across space, specifically identifying how changes in one region systematically influence other regions over time.

Although motivated by polar climate science, Spatial-Link is a general and reusable framework for discovering linkages between heterogeneous spatio-temporal phenomena. Each node represents a spatial region or entity, and a directed linkage indicates that one region or node exerts a statistically significant influence on other regions or nodes across time. Spatial-Link identifies such influence pathways while filtering out spurious connections caused by background variability or noise.

This work is part of the NSF HDR Institute for Harnessing Data and Model Revolution in the Polar Regions (iHARP):
https://iharp.umbc.edu/

---

Dataset Used

We validate Spatial-Link using a single synthetic velocity dataset that mimics realistic wind-driven transport behavior.

• 30 spatial regions (nodes)
• 30 days of data
• Daily 30 × 30 velocity matrices
• Each entry ( V_{ij} ) represents the velocity-driven influence from region or node i to j
• The graph is dense and directed
• A small number of persistent strong linkages are injected across days
• All other edges represent weaker background transport

If these strong linkages consistently dominate the background velocities, Spatial-Link is expected to detect them as statistically significant.

---

Installation (Development)

pip install -e .

Usage

import numpy as np
from spatial_link import weekly_spatial_link

def generate_realistic_velocity(
    n_days=30,
    n_regions=30,
    base_mean=5.0,
    base_std=1.0,
    noise_std=0.8,
    strong_links=10,
    strong_boost=8.0,
    seed=0
):
    """
    Generate realistic synthetic velocity data.

    - Dense directed graph
    - Velocity values roughly in the range 3–17
    - A small set of persistent strong linkages across all days
    """
    rng = np.random.default_rng(seed)

    # Base velocity field (shared across days)
    base = rng.normal(base_mean, base_std, size=(n_regions, n_regions))
    base = np.clip(base, 0.5, None)
    np.fill_diagonal(base, 0)

    # Inject persistent strong linkages
    strong_edges = set()
    while len(strong_edges) < strong_links:
        i, j = rng.integers(0, n_regions, size=2)
        if i != j:
            strong_edges.add((i, j))

    for (i, j) in strong_edges:
        base[i, j] += strong_boost

    # Generate daily velocity matrices
    vel = np.zeros((n_days, n_regions, n_regions))
    for d in range(n_days):
        noise = rng.normal(0, noise_std, size=(n_regions, n_regions))
        day_mat = base + noise
        day_mat = np.clip(day_mat, 0, None)
        np.fill_diagonal(day_mat, 0)
        vel[d] = day_mat

    return vel, strong_edges


# Generate synthetic velocity data
vel, planted_edges = generate_realistic_velocity(
    n_days=30,
    n_regions=30,
    strong_links=12,
    strong_boost=10.0,
    seed=42
)

# Inspect daily velocity ranges
for d in range(vel.shape[0]):
    pos = vel[d][vel[d] > 0]
    print(f"Day {d:02d}: min={pos.min():.2f}, max={pos.max():.2f}")

# Run weekly Spatial-Link
adj, windows = weekly_spatial_link(
    vel,
    days_per_week=7,
    min_days=7,
    drop_last_incomplete=True,
    n_mc=200,
    alpha=0.05,
    max_depth=4,
)

print("Adjacency shape:", adj.shape)
print("Weekly windows:", windows)
 

Interpretation

• Spatial-Link first aggregates daily velocities into weekly mean graphs
• BFS identifies reachable candidate pathways
• Monte Carlo testing filters out edges that are not consistently stronger than random velocity fluctuations
• If true velocity-driven linkages exist, they emerge as significant directed edges in the weekly adjacency matrices

Citation If you use spatial-link in your research, please cite the following paper:

@inproceedings{devnath2025spatiallink,
  author    = {Maloy Kumar Devnath and Sudip Chakraborty and Vandana P. Janeja},
  title     = {Modeling Heterogeneity across Varying Spatial Extents: Discovering Linkages between Sea Ice Retreat and Ice Shelf Melt in the Antarctic},
  booktitle = {Proceedings of the 33rd ACM International Conference on Advances in Geographic Information Systems},
  year      = {2025},
  publisher = {ACM},
  pages     = {261--264}
}

Full Reference

Maloy Kumar Devnath, Sudip Chakraborty, and Vandana P. Janeja. 2025. Modeling Heterogeneity across Varying Spatial Extents: Discovering Linkages between Sea Ice Retreat and Ice Shelf Melt in the Antarctic. Proceedings of the 33rd ACM International Conference on Advances in Geographic Information Systems, pp. 261–264.