da-stdk 0.1.0

DA-STDK: Data-adaptive spatio-temporal distributional prediction (cluster-adaptive bases, conformal calibration)

DA-STDK

Reference implementation of DA-STDK for spatio-temporal distributional prediction, with a cluster-focused design. The method extends DeepKriging with cluster-adaptive spatial bases (learnable centers/scales) and cluster-aware conformal calibration for reliable prediction intervals under heterogeneous observation patterns. The current numerical-study pipeline targets the KAUST benchmark datasets (2a/2b).

Quick Start

Prerequisites

• Conda (Miniconda or Anaconda)
• Poetry (will be installed automatically if not present)

Installation

Option 1: Using Makefile (Recommended)

# Install project dependencies with Poetry
make install

# Install development dependencies in conda environment
make install-dev

Option 2: Manual Setup

# Create and build conda environment
bash envs/conda/build_conda_env.sh

# Activate environment
conda activate st-dadk

# Install dependencies
poetry install --with dev

Using as a library

Install in editable mode and import the da_stdk package:

pip install -e .
# or with poetry: poetry install

import da_stdk
from da_stdk.models import STInterpMLP, create_model
from da_stdk.dataio.kaust_loader import load_kaust_csv_single
from da_stdk.viz import plot_training_curves, plot_observation_density_maps
# See da_stdk.viz.__all__, da_stdk.losses, da_stdk.training for full API

Visualization (matplotlib, seaborn, da_stdk.viz) is included in the default install; no separate [viz] extra is required.

Available Make Commands

• make install: Install project dependencies with Poetry
• make install-dev: Install development dependencies in conda environment
• make test: Run tests
• make test-cov: Run tests with coverage report
• make lint: Run linters (black, isort, mypy)
• make format: Format code with black and isort
• make run-local-jupyter: Start Jupyter Lab server
• make table44: Run KAUST experiment (all scenarios × models)
• make clean: Clean up temporary files

Project Structure

• da_stdk/: Main package code
• scripts/: Training and analysis scripts
• configs/: Configuration files
• data/: Dataset files
• envs/: Environment setup scripts (conda and jupyter)
• envs/.bin/: Utility scripts

Usage

Training

python scripts/train_st_interp.py --config configs/config_st_interp.yaml

KAUST experiment (all scenarios × models)

python scripts/run_kaust_data.py --config configs/config_st_interp.yaml --n_experiments 10
python scripts/analyze_table_4_4.py --results_dir results/kaust_data_<timestamp>

Non-crossing λ is tuned via grid search (scripts/grid_search_non_crossing_lambda.py); pass --non_crossing_lambda to run_kaust_data.py for the chosen value.

Jupyter Lab

make run-local-jupyter
# or
bash envs/jupyter/start_jupyter_lab.sh

Troubleshooting

Conda not found

Make sure Conda is installed and initialized in your shell:

conda init bash  # or zsh

Permission denied

Make shell scripts executable:

chmod +x envs/**/*.sh envs/.bin/*.sh

Credit

This project builds on ST-DADK (Spatio-Temporal Data-Adaptive DeepKriging) by gystat. We thank the original repository for the base implementation.