Metadata-Version: 2.4
Name: climatix
Version: 1.0.1
Summary: Climatix: Standardized Pluviothermal Anomaly Index (SPAI) & Bioclimatic Analysis Toolkit
Author-email: "Kh. LATRECHE" <k.latreche@univ-boumerdes.dz>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/latreche-kh/climatix
Project-URL: Documentation, https://climatix.readthedocs.io/
Project-URL: Repository, https://github.com/latreche-kh/climatix
Project-URL: Bug-Tracker, https://github.com/latreche-kh/climatix/issues
Project-URL: Changelog, https://github.com/latreche-kh/climatix/releases
Keywords: drought,climate-change,climatology,spai,gamma-index,meteorology,bioclimatology,hydrology,environmental-science
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: ipywidgets>=7.0.0
Requires-Dist: tqdm>=4.60.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Requires-Dist: myst-parser>=1.0.0; extra == "docs"
Provides-Extra: analysis
Requires-Dist: scikit-learn>=1.2.0; extra == "analysis"
Requires-Dist: statsmodels>=0.13.0; extra == "analysis"
Requires-Dist: netcdf4>=1.6.0; extra == "analysis"
Provides-Extra: xai
Requires-Dist: xgboost>=1.7.0; extra == "xai"
Requires-Dist: shap>=0.41.0; extra == "xai"
Requires-Dist: lime>=0.2.0; extra == "xai"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/latreche-kh/climatix/main/assets/climatix_logo_transparent.png" alt="Climatix logo" width="220">
</p>

<h1 align="center">Climatix: Standardized Pluviothermal Anomaly Index (SPAI) Toolkit</h1>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.8%2B-blue.svg" alt="Python">
  <img src="https://img.shields.io/badge/license-GPLv3-blue.svg" alt="License">
  <img src="https://img.shields.io/badge/status-active_development-orange.svg" alt="Status">
  <img src="https://img.shields.io/badge/docs-in_progress-yellow.svg" alt="Docs">
  <img src="https://img.shields.io/badge/DOI-10.XXXX%2FXXXXX-brightgreen" alt="DOI">
</p>

## 📖 Overview

Climatix is an advanced Python library for high-resolution bioclimatic analysis, implementing the **Standardized Pluviothermal Anomaly Index (SPAI) framework** — a physically-grounded, PET-free approach to drought monitoring and bioclimatic assessment.

## 🚀 Why Climatix?

Traditional drought indices (SPI, SPEI) rely on monthly aggregations and complex Potential Evapotranspiration (PET) models with significant uncertainties. Climatix offers:

- **🔬 PET-Free Framework**: Uses the robust $P = 2T$ relationship (Gaussen's law) to define water balance, eliminating PET estimation errors
- **📊 Sub-Monthly Resolution**: Employs PCHIP spline interpolation to detect climatic transitions (flash droughts, frost periods) occurring within calendar months
- **🎯 Dual Diagnostic Approach**:
  - **SPAI-Z**: Statistical anomaly detection (Z-score standardization)
  - **SPAI-U**: Absolute physical water status assessment
- **🌡️ Gamma Index Integration**: Combines SPAI with Gamma distribution theory for bioclimatic comfort probability assessment

## 📈 Key Features

- **Multi-Scale Analysis**: Temporal scales from 1 to 48 months
- **High-Resolution Visualization**: Daily, monthly, and seasonal heatmaps
- **Bioclimatic Assessment**: Gamma index for thermal comfort probability
- **Unified API**: Simple, seaborn-like interface for all functionality
- **Modular Architecture**: Easy extension and customization
- **Batch Processing**: Automated analysis of multiple stations

## 📚 Citation

**Manuscript in Preparation** — Target: Proceedings of the National Academy of Sciences (PNAS)

If you use Climatix in your research, please cite:

> LATRECHE, Kh. (2026). Climatix: The Standardized Pluviothermal Anomaly Index—A PET-free framework for global drought monitoring and bioclimatic assessment. Manuscript in preparation. DOI: 10.XXXX/XXXXX

**BibTeX:**
```bibtex
@article{latreche2026climatix,
  title={Climatix: The Standardized Pluviothermal Anomaly Index—A PET-free framework for global drought monitoring and bioclimatic assessment},
  author={Latreche, Kh.},
  journal={Proceedings of the National Academy of Sciences},
  year={2026},
  volume={},
  number={},
  pages={},
  doi={10.XXXX/XXXXX}
}
```

## 🛠 Installation

**Prerequisites**
- Python 3.8 or higher
- pip package manager

**Quick Install**
```bash
# Install from PyPI
pip install climatix

# Or install in development mode from source
git clone https://github.com/latreche-kh/climatix.git
cd climatix
pip install -e .
```

**Dependencies**

Climatix requires the following core dependencies:
- NumPy ≥1.20.0
- pandas ≥1.3.0
- SciPy ≥1.7.0
- Matplotlib ≥3.4.0
- seaborn ≥0.11.0
- openpyxl ≥3.0.0

## 🚀 Quick Start

**Basic Analysis (Command Line)**
```bash
# Complete analysis with visualizations
climatix data/station.xlsx

# Analysis with specific SPAI scales
climatix data/station.xlsx --scales 1 12 24

# Analysis without graphics
climatix data/station.xlsx --no-viz

# Verbose mode with details
climatix data/station.xlsx --verbose
```

**Python API — Unified Interface**
```python
import climatix as clx

# Core calculations
df_gamma = clx.gamma('data/station.xlsx')
df_spai = clx.spai('data/station.xlsx')

# Batch processing
df_batch = clx.batch('data/folder/', output_dir='results', mode='gamma')

# Visualizations
result = clx.gplot('gamma_report.xlsx', station_name="Reykjavik, IC")
fig = clx.barcode('spai_report.xlsx', scales=[1, 6, 12])

# Direct plot functions
fig = clx.plot_gamma_index(df, station_name='Station')
fig = clx.plot_spai_ridge('data.xlsx', years=20, score='U')
```

**Direct Imports (Alternative Style)**
```python
from climatix import gamma, spai, batch, gplot
from climatix.plots import spai_barcode, plot_gamma_index

# Calculate indices
df = gamma('data.xlsx')
df = spai('data.xlsx')

# Generate plots
df_batch = batch('folder/', mode='gamma')
result = gplot('report.xlsx')
fig = spai_barcode('data.xlsx')
```

## 📊 Visualization Gallery

Climatix provides comprehensive visualization capabilities:

| Visualization | Description | Use Case |
|---|---|---|
| SPAI Heatmap | Monthly/annual matrix with triple legend | Seasonal pattern analysis |
| Ridge Plot | High-resolution daily SPAI distribution | Inter-annual comparison |
| Horizon Plot | Multi-level intensity visualization | Trend identification |
| SPAI Barcode | Temporal severity strip | Drought chronology |
| Gamma Plot | Bioclimatic comfort analysis | Thermal stress assessment |
| Stream Graph | Temporal dynamics visualization | Pattern recognition |

## 🏗️ Project Structure

```text
climatix/
├── src/
│   └── climatix/               # Main package
│       ├── __init__.py         # Unified API interface
│       ├── climate_analyzer.py # Main API functions
│       ├── pipeline.py         # Analysis orchestration
│       ├── core/                # Mathematical engines
│       │   ├── spai_engine.py   # SPAI algorithm
│       │   ├── gamma_engine.py  # Gamma adjustments
│       │   ├── core_engine.py   # Splines and integrals
│       │   ├── interpolator.py  # PCHIP interpolation
│       │   └── standardizer.py  # Z/U-score standardization
│       ├── plots/                # Visualization modules
│       │   ├── __init__.py
│       │   ├── seasonal.py       # Matrix, Ridge, Horizon
│       │   └── timeseries.py     # Barcode, Streamgraph, Gamma plots
│       └── utils/                # Utilities
│           ├── io.py             # Data loading and cleaning
│           ├── models.py         # Result wrappers
│           └── constants.py      # Scientific constants
├── examples/                    # Tutorial notebooks
├── tests/                       # Unit tests
├── docs/                        # Documentation
├── data/                        # Sample datasets
├── pyproject.toml               # Package configuration
├── README.md                    # This file
└── LICENSE                      # GPL v3.0
```

## 📖 Documentation

Comprehensive documentation is available:
- **User Guide**: Getting started and basic usage
- **API Reference**: Complete API documentation
- **Methodology**: SPAI and Gamma index theory
- **Tutorials**: Step-by-step examples
- **Case Studies**: Real-world applications

**Building Documentation**
```bash
# Install documentation dependencies
pip install climatix[docs]

# Build documentation
cd docs
make html
```

## 🔬 Scientific Methodology

**SPAI Framework**

SPAI is grounded in the bioclimatic equilibrium $P = 2T$. Rather than a simple monthly difference, SPAI integrates the signed area between PCHIP spline interpolants of precipitation, $S_P(m)$, and twice the temperature, $S_T(m)$, over each inter-month segment:

$$\Delta A_i = \int_{m_i}^{m_{i+1}} \left[ S_P(m) - S_T(m) \right] \, dm$$

This continuous geometric anomaly is then standardized in two complementary ways:

- **U-score** (anchored to the physical threshold $P=2T$, enabling calibration-free cross-biome comparison):

$$SPAI_U = \frac{\Delta A_i}{\sigma(\Delta A)}$$

- **Z-score** (anomaly relative to local climatology):

$$SPAI_Z = \frac{\Delta A_i - \mu_{\Delta A}}{\sigma(\Delta A)}$$

Where $\sigma(\Delta A)$ and $\mu_{\Delta A}$ are the standard deviation and mean of $\Delta A$ over the reference record.

**Gamma Index**

The Gamma index ($G$) represents the probability of bioclimatic comfort:

$$G = \frac{A_{ws}}{A_{ws} + A_{ds} + A_{As}}$$

Where:
- $A_{ws}$: Water surplus area
- $A_{ds}$: Hot drought area
- $A_{As}$: Cold aridity area

## 📈 Applications

**Research Applications**
- Drought monitoring and early warning
- Climate change impact assessment
- Ecological vulnerability mapping
- Agricultural risk management
- Hydrological modeling

**Case Studies**
- **Icelandic Coastal Climate**: Detection of sub-monthly frost periods
- **Mediterranean Drought**: Multi-scale drought pattern analysis
- **Tropical Ecosystems**: NDVI-SPAI correlation studies

## 🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

**Development Setup**
```bash
# Clone repository
git clone https://github.com/latreche-kh/climatix.git
cd climatix

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run code quality checks
black src/
flake8 src/
mypy src/
```

**Code Style**
- Follow PEP 8 guidelines
- Use type hints for function signatures
- Write docstrings in Google style format
- Include unit tests for new features

## 📄 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

```text
Climatix: Standardized Pluviothermal Anomaly Index Toolkit
Copyright (C) 2026 Kh. LATRECHE

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
```

## 👥 Authors and Acknowledgments

**Primary Author**
- Kh. LATRECHE — Department of Biology, University M'Hamed Bougara of Boumerdes
  - Email: k.latreche@univ-boumerdes.dz
  - ORCID: 0000-0002-2038-8140

**Acknowledgments**
- University M'Hamed Bougara of Boumerdes, Algeria
- Faculty of Sciences, Department of Biology
- Meteorological stations and data providers

**Funding**

This research received no specific grant from any funding agency in the public, commercial, or not-for-profit sectors.

## 📞 Contact and Support

- **Issues**: GitHub Issues
- **Discussions**: GitHub Discussions
- **Email**: k.latreche@univ-boumerdes.dz
- **Institution**: University M'Hamed Bougara of Boumerdes, Faculty of Sciences, Department of Biology, Railway Station Road, 35000 Boumerdes, Algeria

## 🔗 Links

- **Source Code**: https://github.com/latreche-kh/climatix
- **Documentation**: https://climatix.readthedocs.io/
- **PyPI Package**: https://pypi.org/project/climatix/
- **DOI**: 10.XXXX/XXXXX

---

<p align="center"><i>Climatix: Advancing bioclimatic analysis through innovative, physically-grounded methodologies.</i></p>
