da-stdk 0.1.0__tar.gz

da_stdk-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: da-stdk
+Version: 0.1.0
+Summary: DA-STDK: Data-adaptive spatio-temporal distributional prediction (cluster-adaptive bases, conformal calibration)
+Author: Wen-Ting Wang
+Author-email: egpivo@gmail.com
+Requires-Python: >=3.10.13,<4.0.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: joblib (>=1.3.0,<2.0.0)
+Requires-Dist: k-means-constrained (>=0.7.3,<0.8.0)
+Requires-Dist: matplotlib (>=3.7.0,<4.0.0)
+Requires-Dist: numpy (>=1.24.0,<2.0.0)
+Requires-Dist: pandas (>=2.0.0,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
+Requires-Dist: scikit-learn (>=1.3.0,<2.0.0)
+Requires-Dist: scipy (>=1.12.0,<2.0.0)
+Requires-Dist: seaborn (>=0.13.0,<0.14.0)
+Requires-Dist: torch (>=2.0.0,<3.0.0)
+Requires-Dist: tqdm (>=4.65.0,<5.0.0)
+Description-Content-Type: text/markdown
+
+# 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)
+
+```bash
+# Install project dependencies with Poetry
+make install
+
+# Install development dependencies in conda environment
+make install-dev
+```
+
+#### Option 2: Manual Setup
+
+```bash
+# 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:
+
+```bash
+pip install -e .
+# or with poetry: poetry install
+```
+
+```python
+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
+
+```bash
+python scripts/train_st_interp.py --config configs/config_st_interp.yaml
+```
+
+### KAUST experiment (all scenarios × models)
+
+```bash
+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
+
+```bash
+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:
+```bash
+conda init bash  # or zsh
+```
+
+### Permission denied
+
+Make shell scripts executable:
+```bash
+chmod +x envs/**/*.sh envs/.bin/*.sh
+```
+
+## Credit
+
+This project builds on [**ST-DADK**](https://github.com/gystat/ST-DADK) (Spatio-Temporal Data-Adaptive DeepKriging) by [**gystat**](https://github.com/gystat). We thank the original repository for the base implementation.
+

da_stdk-0.1.0/README.md

@@ -0,0 +1,119 @@
+# 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)
+
+```bash
+# Install project dependencies with Poetry
+make install
+
+# Install development dependencies in conda environment
+make install-dev
+```
+
+#### Option 2: Manual Setup
+
+```bash
+# 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:
+
+```bash
+pip install -e .
+# or with poetry: poetry install
+```
+
+```python
+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
+
+```bash
+python scripts/train_st_interp.py --config configs/config_st_interp.yaml
+```
+
+### KAUST experiment (all scenarios × models)
+
+```bash
+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
+
+```bash
+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:
+```bash
+conda init bash  # or zsh
+```
+
+### Permission denied
+
+Make shell scripts executable:
+```bash
+chmod +x envs/**/*.sh envs/.bin/*.sh
+```
+
+## Credit
+
+This project builds on [**ST-DADK**](https://github.com/gystat/ST-DADK) (Spatio-Temporal Data-Adaptive DeepKriging) by [**gystat**](https://github.com/gystat). We thank the original repository for the base implementation.

da_stdk-0.1.0/da_stdk/__init__.py

@@ -0,0 +1,5 @@
+"""
+DA-STDK: Data-adaptive spatio-temporal distributional prediction.
+Cluster-adaptive bases and conformal calibration for prediction intervals.
+"""
+__version__ = "0.1.0"

da_stdk-0.1.0/da_stdk/dataio/__init__.py

@@ -0,0 +1,25 @@
+"""
+Data I/O for STNF-XAttn
+"""
+from .kaust_loader import (
+    load_kaust_csv,
+    sample_observed_sites,
+    KAUSTWindowDataset,
+    create_dataloaders,
+    prepare_test_context,
+    predictions_to_csv
+)
+from .obs_sampling import create_spatial_obs_prob_fn, sample_observations
+from .splits import split_train_valid
+
+__all__ = [
+    'load_kaust_csv',
+    'sample_observed_sites',
+    'KAUSTWindowDataset',
+    'create_dataloaders',
+    'prepare_test_context',
+    'predictions_to_csv',
+    'create_spatial_obs_prob_fn',
+    'sample_observations',
+    'split_train_valid',
+]