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.

