Metadata-Version: 2.1
Name: climatix
Version: 1.0.0
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"

# Climatix: Standardized Pluviothermal Anomaly Index (SPAI) Toolkit

![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)
![License](https://img.shields.io/badge/license-GPLv3-blue.svg)
![Status](https://img.shields.io/badge/status-active_development-orange.svg)
![Docs](https://img.shields.io/badge/docs-in_progress-yellow.svg)
![DOI](https://img.shields.io/badge/DOI-10.XXXX%2FXXXXX-brightgreen)

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

The Standardized Pluviothermal Anomaly Index (SPAI) is computed as:

SPAI=P−2TσP−2TSPAI=σP−2T​P−2T​

Where:
    $P$: Precipitation (mm)
    $T$: Mean temperature (°C)
    $\sigma_{P-2T}$: Standard deviation of the $P-2T$ series

Gamma Index

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

G=AwsAws+Ads+AAsG=Aws​+Ads​+AAs​Aws​​

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

Climatix: Advancing bioclimatic analysis through innovative, physically-grounded methodologies.
