SamudraAI & SamudraGraph 🌊🌐

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:

pip install --upgrade samudra-ai

Setelah instalasi, kedua modul dapat langsung diimpor:

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)

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

⏱️ 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:

# 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

🎯 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

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 untuk detailnya.

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

@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)
• GitHub: https://github.com/adityoAJA/samudra-ai
• PyPI Package: https://pypi.org/project/samudra-ai/