Metadata-Version: 2.4
Name: samudra-ai
Version: 2.5.9
Summary: Paket Python untuk pengolahan koreksi bias pada model iklim global menggunakan deep learning menggunakan CNN dan LSTM.
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: 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

# samudra-ai

Library Python samudra-ai versi terbaru

# SamudraAI 🌊

![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/)
[![TensorFlow](https://img.shields.io/badge/TensorFlow-2.10+-orange.svg)](https://www.tensorflow.org/)
[![Downloads](https://pepy.tech/badge/samudra-ai)](https://pepy.tech/project/samudra-ai)

Paket Python versi terbaru untuk melakukan pengolahan koreksi bias model iklim global menggunakan arsitektur deep learning.

**SamudraAI** memudahkan peneliti dan praktisi di bidang ilmu iklim untuk menerapkan metode koreksi bias yang canggih pada data GCM (General Circulation Model) menggunakan data observasi sebagai referensi.

---

## ✨ Fitur Terbaru v2.5.6

- 🆕 **Physics-Aware Auto-Config**: Model secara otomatis menyesuaikan arsitektur berdasarkan karakteristik fisika variabel iklim (suhu vs hujan)
- 🆕 **Station-Based Downscaling**: SamudraAI1D dengan akurasi state-of-the-art untuk koreksi bias tingkat stasiun
- 🆕 **Uncertainty Quantification**: Monte Carlo Dropout untuk probabilistic forecasting dengan 95% confidence interval
- 🆕 **Smart Visualization**: Peta akurasi Cartopy, grafik time series, dan plot uncertainty otomatis
- 🆕 **Multi-Variable Support**: Optimasi khusus untuk suhu, curah hujan, angin, dan kelembaban
- 🆕 **4 Model Pilihan**: Dari yang ringan (SamudraAI) hingga high-precision (SamudraAI3/SamudraAI1D)

---

## 📊 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

### 1️⃣ SamudraAI (CNN-BiLSTM)

✅ **Kelebihan:**
- Training paling cepat & konsumsi VRAM paling ringan
- Robust terhadap noise & missing data berkat pooling & dropout
- Sangat baik menangkap tren temporal & rata-rata regional
- Bekerja stabil dengan dataset terbatas

⚠️ **Kekurangan:**
- Global pooling menghilangkan detail spasial resolusi tinggi
- Output spasial direkonstruksi dari Dense layer → cenderung smooth/blur
- Kurang optimal untuk pola lokal tajam (gradien pesisir, orografis)

🎯 **Kapan Dipilih:**
Bias correction parameter iklim, studi regional skala besar, environment dengan GPU terbatas, atau baseline cepat.

---

### 2️⃣ SamudraAI2 (ConvLSTM2D)

✅ **Kelebihan:**
- Memodelkan dependensi spasial & temporal secara bersamaan
- Struktur spasial lebih terjaga dibanding pooling-based model
- Evolusi temporal halus berkat filter rekuren spasial
- Keseimbangan baik antara akurasi & biaya komputasi

⚠️ **Kekurangan:**
- Dapat kesulitan dengan skala spasial sangat tidak seragam
- Output sequence-to-sequence perlu slicing manual untuk next-step prediction
- VRAM lebih tinggi dari SamudraAI

🎯 **Kapan Dipilih:**
Downscaling dan koreksi bias dengan transisi temporal yang penting dan resolusi temporal yang lebih tinggi.

---

### 3️⃣ SamudraAI3 (U-Net + ConvLSTM)

✅ **Kelebihan:**
- Ekstraksi fitur multi-skala (detail lokal + konteks global)
- Skip connections mempertahankan pola resolusi tinggi
- Dynamic resize menangani input dimensi ganjil/kecil secara robust (padding='same')

⚠️ **Kekurangan:**
- Konsumsi VRAM & waktu training paling tinggi
- Memerlukan tuning dropout & learning rate agar tidak overfit
- Rentan noise jika data training terlalu sedikit atau tidak stabil

🎯 **Kapan Dipilih:**
Koreksi bias high-precision (curah hujan ekstrem), region dengan topografi/pesisir kompleks.

### 4️⃣ SamudraAI1D (Conv1D + BiGRU + Attention) 🆕

**Arsitektur Station-Based untuk Koreksi Bias Presisi Tinggi**

✅ **Kelebihan:**
- **Physics-Aware**: Otomatis menyesuaikan `patch_size` berdasarkan variabel (3 untuk hujan, 5 untuk suhu)
- **Hybrid Architecture**: Dilated Conv2D (spasial) + BiGRU (temporal) + Attention (fokus kritis)
- **Metadata Fusion**: Mengintegrasikan koordinat (lat/lon), elevasi, dan fitur seasonal (sin/cos)
- **Robust Training**: Anti-NaN, anti-overfitting, dengan EarlyStopping & ReduceLROnPlateau
- **Uncertainty Quantification**: MC Dropout untuk 95% confidence interval
- **Production-Ready**: Validasi pada 117-182 stasiun BMKG se-Indonesia

⚠️ **Kekurangan:**
- Memerlukan data observasi stasiun (CSV/Excel)
- Training lebih lama untuk dataset besar (>100 stasiun)
- Memerlukan GPU dengan VRAM minimal 4GB

🎯 **Kapan Dipilih:**
- Koreksi bias tingkat stasiun dengan akurasi tinggi
- Downscaling dari GCM/Reanalysis ke titik observasi
- Aplikasi operasional BMKG, pertanian presisi, early warning system
- Ketika Anda butuh uncertainty quantification untuk risk assessment

---

## 🌍 Use Cases

| Use Case | Model Rekomendasi | Alasan |
|----------|:-----------------:|-------:|
| Downscaling cepat, GPU terbatas | **SamudraAI** | VRAM rendah, training cepat |
| Sequence forecasting | **SamudraAI2** | Output sequence native |
| Topografi kompleks | **SamudraAI3** | Detail spasial tajam |
| Koreksi bias stasiun | **SamudraAI1D** | Presisi tinggi + uncertainty |
| Early warning system | **SamudraAI1D** | Titik spesifik + risk assessment |
| Studi iklim regional | **SamudraAI / SamudraAI3** | Peta 2D lengkap |

---

## 📦 Instalasi

Anda dapat menginstal SamudraAI langsung dari PyPI menggunakan pip:

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

## 🛠️ API Reference

**SamudraAI (CNN-BiLSTM)**

Class untuk downscaling grid 2D.

Parameters:
- config (ModelConfig): Konfigurasi model

Methods:
- fit(gcm_input, obs_target): Training
- predict(gcm_input): Generate data masa depan terkoreksi
- correction(gcm_grid, station_df): Generate data historical terkoreksi
- evaluate_and_plot(raw_gcm_data, ref_data, ...): Evaluasi + visualisasi
- analyze_uncertainty(gcm_grid, var_label, ...): MC Dropout uncertainty
- save(path) / load(path): Persistensi

**SamudraAI2 (ConvLSTM2D)**

Class untuk sequence-to-sequence forecasting.

Parameters:
- config (ModelConfig2): Konfigurasi model

Methods:
- fit(gcm_input, obs_target): Training
- predict(gcm_input): Generate data masa depan terkoreksi
- correction(gcm_grid, station_df): Generate data historical terkoreksi
- evaluate_and_plot(raw_gcm_data, ref_data, ...): Evaluasi + visualisasi
- analyze_uncertainty(gcm_grid, var_label, ...): MC Dropout uncertainty
- save(path) / load(path): Persistensi

**SamudraAI3 (U-Net + ConvLSTM)**

Class untuk high-precision downscaling.

Parameters:
- config (ModelConfig3): Konfigurasi model

Methods:
- fit(gcm_input, obs_target): Training
- predict(gcm_input): Generate data masa depan terkoreksi
- correction(gcm_grid, station_df): Generate data historical terkoreksi
- evaluate_and_plot(raw_gcm_data, ref_data, ...): Evaluasi + visualisasi
- analyze_uncertainty(gcm_grid, var_label, ...): MC Dropout uncertainty
- save(path) / load(path): Persistensi

**SamudraAI1D (Station-Based) 🆕**

Class untuk station-based bias correction.

Parameters:
- time_seq (int): Ukuran window temporal (default: 9)
- config (ModelConfig1D, optional): Konfigurasi custom
- mode (str, optional): Mode auto-config (suhu, hujan, angin, kelembaban)
- patch_size (int, optional): Override patch size

Methods:
- fit(gcm_grid, station_df): Training
- correction(gcm_grid, station_df): Generate data terkoreksi
- evaluate_and_plot(raw_gcm_data, ref_data, ...): Evaluasi + visualisasi
- analyze_uncertainty(gcm_grid, var_label, ...): MC Dropout uncertainty
- save(path) / load(path): Persistensi


## Requirements

- Python >= 3.9
- TensorFlow >= 2.15
- NumPy, Pandas, Xarray
- Scikit-learn, Matplotlib
- Cartopy (opsional, untuk visualisasi geografis)

## ✅ Best Practice

- ✅ Disarankan menggunakan TensorFlow GPU untuk performa optimal
- ✅ Disarankan memiliki memory / RAM yang cukup untuk pengolahan data dengan resolusi tinggi dan luasan domain yang besar
- ✅ Jalankan versi tunning yang sudah ter hardcore. Bila hasil kurang optimal bisa menyesuaikan ulang parameter tunningnya secara manual
- ✅ Gunakan mode="suhu" atau mode="hujan" untuk auto-config optimal
- 💡 Format .nc/.xlsx hasil koreksi bisa langsung digunakan untuk plotting dan analisis

## How To Use :

https://github.com/adityoAJA/samudra-ai/blob/main/How-to-use-samudra-ai.txt

## 📄 Lisensi :

Proyek ini dilisensikan di bawah MIT License. Lihat file LICENSE untuk detailnya.

## 📧 Kontak:

Untuk pertanyaan, issue, atau peluang kolaborasi:
GitHub: https://github.com/adityoAJA/samudra-ai
Email: [adit007991@gmail.com]

@software{samudra_ai_2026,
  author = {Adityo A.J.},
  title = {SamudraAI: Deep Learning for Climate Bias Correction},
  version = {2.5.6},
  year = {2026},
  url = {https://pypi.org/project/samudra-ai/}
}
