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.9.9?

• 📉 Garis Tren Linier Awal–Akhir (show_trendline=True) pada Plot 07 & Plot 10: Seluruh grafik deret waktu rekonstruksi Plot 07 (plot_07_deret_waktu_hindcast_historis.png, plot_07_stasiun_<id>.png, plot_07_ringkasan_multi_stasiun.png) dan Plot 10 (plot_10_deret_waktu_multi_stasiun_1950_2026.png) kini otomatis merender Garis Tren Linier OLS dari Awal hingga Akhir Periode (Garis Tren Linier (Awal–Akhir), garis putus-putus merah tebal) beserta kotak anotasi gradien tren per dekade (°C/dekade, %/dekade, mm/dekade) dan nilai awal $\to$ akhir (Awal: ... → Akhir: ...), membuktikan secara visual dan kuantitatif kontinuitas linier lintas-batas 1981 tanpa step-shifting.
• 🔬 Pilar ke-7 Physics Explainability Suite (plot_exp_07_audit_kopling_emisi_co2_iklim.png): Penambahan diagnostik fisis baru pada sg.explain() (Sel 11) melalui fungsi plot_co2_emission_climate_coupling_audit() yang menyajikan 3 panel pembuktian ilmiah:
  • Panel A: Ko-evolusi laju emisi antropogenik global ($5.83 \to 38.30\text{ GtCO}_2/\text{thn}$) dan kontinuitas suhu rata-rata kepulauan Indonesia (1950–2026, $r = 0.923$, $+0.19^\circ\text{C}/\text{dekade}$ tanpa step-shift di batas 1981).
  • Panel B: Regresi sensitivitas paksaan radiatif logaritmik IPCC AR6 ($\Delta F_{\text{CO}_2} = 5.35 \ln(\text{CO}_2/280)$ vs suhu tahunan, $r = 0.929, R^2 = 0.863$, sensitivitas transien $+0.80^\circ\text{C}/(\text{W}\cdot\text{m}^{-2})$) yang menempatkan era Hindcast (1950–1980) dan Observasi (1981–2026) pada satu garis hukum fisis yang sama.
  • Panel C: Distribusi spasial koefisien sensitivitas pemanasan stasiun ($\beta_i$) lintas 4 sabuk kepulauan Indonesia dan pembuktian kopling termodinamika Clausius-Clapeyron ($+6.8%$ uap air jenuh/$^\circ\text{C}$) terhadap peningkatan akurasi RH dan curah hujan.
• 🎯 Dukungan Penuh Pemilihan Stasiun Sampel Manual (sample_stations): Parameter sample_stations=["96001", "96749", "96171", "97072"] pada predict(), hindcast(), dan export_all() untuk memilih stasiun spesifik yang diplot pada Plot 05, Plot 07, dan Plot 10.

📦 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_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_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.9.8},
  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/