Metadata-Version: 2.4
Name: samudra-ai
Version: 2.7.1
Summary: Paket Python untuk koreksi bias model iklim global (Convolutional Neural Network) dan pemodelan graf spasial-klimatologis (Graph Neural Network).
Author-email: Adityo Wicaksono <adityo.wicaksono@bmkg.go.id>
License: MIT License
Project-URL: Homepage, https://github.com/adityoAJA/samudra-ai
Project-URL: Bug Tracker, https://github.com/adityoAJA/samudra-ai/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xarray
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: tensorflow
Requires-Dist: torch
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: h5netcdf
Requires-Dist: netCDF4
Requires-Dist: cftime
Requires-Dist: scikit-image
Requires-Dist: joblib
Requires-Dist: seaborn
Requires-Dist: scipy
Requires-Dist: openpyxl
Requires-Dist: cartopy
Dynamic: license-file

# SamudraAI & SamudraGraph 🌊🌐

![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
[![PyPI version](https://badge.fury.io/py/samudra-ai.svg)](https://pypi.org/project/samudra-ai/)
[![Python](https://img.shields.io/pypi/pyversions/samudra-ai.svg)](https://pypi.org/project/samudra-ai/)
[![Framework: PyTorch & TensorFlow](https://img.shields.io/badge/Framework-PyTorch%20%7C%20TensorFlow-blue.svg)](https://pypi.org/project/samudra-ai/)
[![Downloads](https://pepy.tech/badge/samudra-ai)](https://pepy.tech/project/samudra-ai)

**SamudraAI** adalah platform komputasi cerdas iklim (*Deep Climate Science*) terpadu untuk wilayah kepulauan Indonesia. Paket ini menyediakan arsitektur **Dual-Engine** canggih:

1. **Engine 1 (`samudra_ai`)**: Koreksi bias model iklim global (GCM) dan *downscaling* resolusi spasial berbasis Convolutional Neural Network (CNN, ConvLSTM2D, U-Net, dan Conv1D-BiGRU-Attention).
2. **Engine 2 (`samudra_graph`)**: Pemodelan graf spasial-klimatologis dan rekonstruksi iklim (*Graph Neural Networks*) berbasis Dynamic Relational GATv2, topologi heterogen stasiun BMKG & sel reanalisis ERA5, kuantifikasi ketidakpastian konformal, serta pembuktian fisis termodinamika.

---

## 🚀 Apa yang Baru di v2.7.1?

- ⚡ **High-Level Interactive API**: Otomatisasi visualisasi dan evaluasi dengan parameter `plot=True` dan `evaluate=True` pada `fit()`, `predict()`, `hindcast()`, `fill_gaps()`, dan `virtual_stations()`.
- 🔍 **Guided Feature Exploration & VIF Screening (`model.screen_features()`)**: Evaluasi multikolinearitas pra-pelatihan otomatis, penghitungan Variance Inflation Factor eksak, dan pemangkasan fitur redundan secara stepwise dengan output tabel ranking & plot grafik batang.
- 📁 **Ekspor 1-Pintu (`export_all()`)**: Ekspor seluruh hasil rekonstruksi sekaligus ke standar biner internasional CF-1.8 DSG NetCDF-4 dan BMKG archive CSV.
- 🌐 **Spatio-Temporal GNN Level 2 (`"st-gnn"`)**: Arsitektur unggulan `MultiVariableSpatioTemporalGAT2` dengan modular `window_size` (default: 3 bulan = 1 fase monsun penuh).
- 🏆 **State-of-the-Art GNN-Attention (GATv2)**: Pembobotan pesan dinamis (*anisotropic dynamic attention*) yang mempertimbangkan jarak fisik geodesik, relief orografi topografi riil ($\Delta z$), dan tipe relasi busur RGAT.
- 🌫️ **Graph Masked Autoencoder Pretraining**: Regulasi *masked node dropout* induktif yang melatih model merekonstruksi informasi secara mandiri saat sensor stasiun padam (*blackout*). Peningkatan akurasi *gap-filling* **$+13.8\%$ hingga $+38.5\%$**!
- 🎯 **Graph Conformal Prediction (G-CP)**: Kuantifikasi ketidakpastian probabilistik adaptif dengan jaminan cakupan fisik matematis $90\%$ yang mematuhi batas fisis (RH $[0, 100\%]$, Hujan $\ge 0$).
- 🧭 **Modular Edge Attributes (2D / 4D / 5D)**: Pilihan atribut busur dari baseline parsimonious 2D (`[distance, elevation]`), 4D kompas arah periodik, hingga 5D proyeksi vektor adveksi angin monsun.
- 🔬 **Physics Explainability Suite**: Generator bukti fisis otomatis via `model.explain()` (peta atensi spasial, manifold PCA topografi, verifikasi *adiabatic lapse rate*, dan audit batas analitik).

---

## 📦 Instalasi

Paket dapat diinstal langsung dari PyPI:

```bash
pip install --upgrade samudra-ai
```

Setelah instalasi, kedua modul dapat langsung diimpor:
```python
import samudra_ai     # Engine 1: CNN GCM Bias Correction
import samudra_graph  # Engine 2: Spatial Graph Neural Networks
```

---

# 🌐 ENGINE 2: SAMUDRAGRAPH (`samudra_graph`)

`samudra_graph` dirancang khusus untuk merekonstruksi dan memodelkan variabel iklim multivariat di wilayah kepulauan Indonesia dengan topografi kompleks dan keterbatasan jaringan sensor *in-situ*.

### ⚡ Quickstart Bersih & Interaktif (Colab Ready)

```python
from samudra_graph import SamudraGraph

# 1. Inisialisasi model Level 2 ST-GNN
model = SamudraGraph(
    architecture="st-gnn",
    variables=["temp", "rh", "rain", "pressure"],
    window_size=3,
    era5_grid_strategy="radius",
    era5_radius_km=25.0,
    nc_path="data/data_ERA5_indo_1950_2026.nc",
)

# 2. Latih model (otomatis plot topologi & kurva loss)
model.fit(
    train_data="data/bmkg_monthly_aligned_1981_2026.csv",
    train_start="1991-01-01",
    train_end="2020-12-01",
    epochs=35,
    plot=True,
)

# 3. Prediksi out-of-sample forward (otomatis hitung metrik & plot)
preds = model.predict(
    test_start="2021-01-01",
    test_end="2024-07-01",
    evaluate=True,
    plot=True,
)

# 4. Rekonstruksi 3 Pilar: Hindcast, Gap-Filling, & Virtual Stations
hindcast = model.hindcast(start_date="1981-01-01", end_date="1990-12-01", plot=True)
imputed = model.fill_gaps(station_data="data/bmkg_monthly_aligned_1981_2026.csv", plot=True)
virtual = model.virtual_stations(start_date="2021-01-01", end_date="2024-07-01", plot=True)

# 5. Ekspor produk lengkap ke CF-1.8 DSG NetCDF-4 & BMKG CSV
model.export_all(hindcast=hindcast, filled=imputed, virtual=virtual, forecast=preds)

# 6. Terbitkan bukti fisik hubungan fisis (Physics Explainability Suite)
model.explain()
```

### 🏛️ Arsitektur yang Didukung

| Arsitektur (`architecture`) | Status | Implementasi Saintifik | Karakteristik Utama |
| :--- | :--- | :--- | :--- |
| **`"st-gnn"`** *(Roadmap Level 2)* | **SOTA Spatio-Temporal** | `MultiVariableSpatioTemporalGAT2` | Perambatan pesan spasial GATv2 relasional dikombinasikan dengan asimilasi deret waktu rekuren (Node-wise GRU) melalui jendela waktu bergerak modular (`window_size`, default: 3 bulan). Mampu melacak akumulasi lengas tanah, panas laut, dan transisi fase monsun secara dinamis. Alias: `"st_gnn"`, `"st-gat"`, `"spatiotemporal"`. |
| **`"gnn-attention"`** *(Rekomendasi Spasial)* | **SOTA Spasial** | `MultiVariableSourceAwareGAT2` | Dynamic anisotropic attention (GATv2), atribut busur fisik kontinu, orografi $\Delta z$, pembedaan relasi RGAT, dan Tweedie deviance loss ($p=1.5$) untuk presipitasi. Alias: `"gat"`, `"gat2"`. |
| **`"simple-gnn"`** | **Qualified Baseline** | `MultiVariableSourceAwareGNN` | Uniform relational message-passing lintas simpul heterogen (BMKG + ERA5) dengan LayerNorm, residual connection, dan aktivasi batas fisis. Alias: `"lite"`. |

#### ⏱️ Penggunaan Modular Time Window (`window_size`):
Pada arsitektur `"st-gnn"`, parameter panjang jendela waktu deret bulan (`window_size`, atau alias `time_window`) bersifat modular dan dapat diatur bebas sesuai kebutuhan riset:
```python
# Default rekomendasi: window_size=3 (merepresentasikan 1 musim penuh monsun Indonesia)
model = SamudraGraph(architecture="st-gnn", window_size=3)

# Eksplorasi siklus transisi monsun (misal 6 bulan atau 9 bulan)
model_6m = SamudraGraph(architecture="st-gnn", window_size=6)
```

### 📊 Hasil Uji Benchmark Utama SamudraGraph
- **Spatio-Temporal Memory (Level 2 ST-GNN)**: Integrasi memori rekuren GRU modular ($W=3$) memangkas error barometrik tekanan stasiun sebesar **$+55.31\%$** (MAE $10.99 \to 4.91\text{ hPa}$), menurunkan error curah hujan sebesar **$+20.62\%$** (MAE $156.4 \to 124.15\text{ mm}$), dan melesatkan korelasi hujan ke **$r = 0.5586$** (vs $r=0.3050$ pada baseline snapshot).
- **Akurasi Suhu Permukaan**: Rekor MAE terendah **$0.6030^\circ\text{C}$** dicapai pada strategi *Physical Radius Cutoff* $25\text{ km}$ (**$+10.72\%$ skill gain** dibanding baseline), dan meningkat ke **$0.5288^\circ\text{C}$** pada ST-GNN $W=9$.
- **Akurasi Kelembapan Relatif**: MAE **$2.7708\%$** (**$+5.28\%$ skill gain**).
- **Korelasi Tekanan Stasiun**: Korelasi Pearson melonjak dari $r=0.2751$ ke **$r=0.7014$** nasional (**$r=0.8385$** di Sumatra dan **$r=0.9809$** di Jawa) berkat integrasi orografi geopotensial riil dan memori barometrik.
- **Puncak Monsun Barat**: Varian adveksi angin 5D memangkas MAE menjadi **$0.6189^\circ\text{C}$** (**$+3.82\%$ skill gain** saat monsun Asia aktif melintasi Laut Jawa).
- **Validasi Hukum Termodinamika**: Gradien adiabatik suhu empiris terhadap elevasi terbukti mematuhi *environmental lapse rate* atmosfer tropis ($-5.82^\circ\text{C} / \text{km}$).

---

# 🌊 ENGINE 1: SAMUDRAAI (`samudra_ai`)

`samudra_ai` berfokus pada koreksi bias data iklim global (GCM) terhadap observasi *grid* atau stasiun BMKG menggunakan *deep learning*.

### 📊 Perbandingan 4 Model SamudraAI

| Fitur | SamudraAI | SamudraAI2 | SamudraAI3 | SamudraAI1D |
|---|:---:|:---:|:---:|:---:|
| **Arsitektur** | CNN + BiLSTM | ConvLSTM2D | U-Net + ConvLSTM | Conv2D + BiGRU + Attention |
| **Tipe Output** | Grid 2D | Grid 2D Sequence | Grid 2D Sequence | **Titik Stasiun** |
| **Input Data** | Grid GCM | Grid GCM | Grid GCM | Grid GCM + Stasiun |
| **VRAM Usage** | 🟢 2-4 GB | 🟡 6-8 GB | 🔴 12-16 GB | 🟢 4-6 GB |
| **Training Speed** | 🟢 Cepat | 🟡 Sedang | 🔴 Lambat | 🟡 Sedang |
| **Detail Spasial** | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **Konteks Temporal** | ⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| **Uncertainty** | ❌ | ❌ | ❌ | ✅ MC Dropout |
| **Best Use Case** | Baseline cepat | Sequence forecast | High-precision grid | **Koreksi stasiun** |

### 🎯 Panduan Pemilihan Model SamudraAI
- **SamudraAI (CNN-BiLSTM)**: Training paling cepat & konsumsi VRAM paling ringan. Cocok untuk studi regional skala besar atau baseline cepat.
- **SamudraAI2 (ConvLSTM2D)**: Memodelkan dependensi spasial & temporal secara bersamaan. Keseimbangan baik antara akurasi & komputasi.
- **SamudraAI3 (U-Net + ConvLSTM)**: Ekstraksi fitur multi-skala dengan *skip connections*. Unggul untuk wilayah dengan topografi kompleks dan hujan ekstrem.
- **SamudraAI1D (Conv1D + BiGRU + Attention)**: Model *station-based downscaling* dengan integrasi metadata fisik (lat/lon, elevasi, seasonal) dan MC Dropout 95% confidence interval.

---

## 🛠️ Ringkasan API SamudraAI

```python
import samudra_ai

# Contoh penggunaan SamudraAI1D untuk koreksi stasiun
model_cnn = samudra_ai.SamudraAI1D(time_seq=9, mode="suhu")
model_cnn.fit(gcm_grid, station_df)
corrected = model_cnn.correction(gcm_grid, station_df)
model_cnn.evaluate_and_plot(raw_gcm_data, ref_data, output_dir="outputs/plots")
```

---

## 📋 Persyaratan Lingkungan (*Requirements*)

- **Python**: `>= 3.9`
- **Machine Learning**: `torch >= 2.0.0`, `tensorflow >= 2.10`
- **Sains Data & Geospasial**: `numpy`, `pandas`, `xarray`, `netCDF4`, `h5netcdf`, `scipy`, `scikit-learn`
- **Visualisasi**: `matplotlib`, `seaborn`, `cartopy` (opsional untuk peta geografis)

---

## 📄 Lisensi & Sitasi

Proyek ini dilisensikan di bawah **MIT License**. Lihat berkas [LICENSE](LICENSE) untuk detailnya.

Jika Anda menggunakan SamudraAI atau SamudraGraph dalam penelitian ilmiah, silakan sitasi:

```bibtex
@software{samudra_ai_2026,
  author = {Adityo Wicaksono},
  title = {SamudraAI: Deep Learning & Graph Neural Networks for Climate Science},
  version = {2.7.0},
  year = {2026},
  url = {https://pypi.org/project/samudra-ai/}
}
```

---

## 📧 Kontak & Kolaborasi

- **Pusat Riset**: BMKG (Badan Meteorologi, Klimatologi, dan Geofisika), Indonesia
- **Author**: Adityo Wicaksono ([adityo.wicaksono@bmkg.go.id](mailto:adityo.wicaksono@bmkg.go.id))
- **GitHub**: [https://github.com/adityoAJA/samudra-ai](https://github.com/adityoAJA/samudra-ai)
- **PyPI Package**: [https://pypi.org/project/samudra-ai/](https://pypi.org/project/samudra-ai/)
