Metadata-Version: 2.4
Name: sqrt_etmax
Version: 0.2.0
Summary: Implementación de la distribución SQRT-ETmax para hidrología española.
Author-email: Gabriel Molina <gabriel.molina@um.es>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scipy>=1.7.0
Requires-Dist: numpy>=1.20.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Dynamic: license-file

# sqrt_etmax

Implementación en Python de la distribución estadística **SQRT-ETmax**, utilizada ampliamente en la hidrología española para el cálculo de caudales y precipitaciones máximas según la **Norma 5.2-IC** del Ministerio de Fomento.

Este paquete está construido sobre la interfaz `scipy.stats.rv_continuous`, lo que significa que hereda toda la funcionalidad estándar de Scipy (cálculo de cuantiles, intervalos de confianza, generación de números aleatorios, etc.).

---

## Instalación

Una vez publicado en el índice PyPI, el paquete se instalará directamente con:

```bash
pip install sqrt_etmax
```

Mientras tanto, se puede instalar desde el código fuente. Clona este repositorio y ejecuta:

```bash
pip install .
```

Si vas a modificar el código, se recomienda instalarlo en modo desarrollo:

```bash
pip install -e .
```

## Uso Básico

La distribución expone una instancia global llamada `sqrt_etmax` que puede usarse directamente como cualquier otra distribución de `scipy.stats`.

### 1. Ajuste de datos y cálculo de periodos de retorno

```python
import numpy as np
from sqrt_etmax.distribution import sqrt_etmax

# 1. Datos de ejemplo (ej. serie de precipitaciones máximas anuales)
datos = np.array([45.2, 56.1, 38.9, 78.4, 62.0, 41.5, 92.3, 55.6])

# 2. Ajuste de parámetros (k, alpha)
# Puedes utilizar fit_custom() (Máxima Verosimilitud) o fit_lmoments() (L-Momentos).
# NOTA: fit_lmoments() ahora utiliza la función cuantil analítica exacta (W de Lambert) mejorando su precisión y rendimiento.
k_est, alpha_est = sqrt_etmax.fit_custom(datos)
print(f"Parámetros ajustados -> k: {k_est:.4f}, alpha: {alpha_est:.4f}")

# 3. Crear un objeto congelado ("frozen") con los parámetros ajustados
dist = sqrt_etmax.freeze_params(k_est, alpha_est)

# 4. Calcular el cuantil para un Periodo de Retorno (T)
T = 100
probabilidad_no_excedencia = 1 - (1 / T)
valor_T100 = dist.ppf(probabilidad_no_excedencia)

print(f"Precipitación para T={T} años: {valor_T100:.2f} mm")
```

## Cómo citar

Si utilizas `sqrt_etmax` en tu investigación, cita el artículo correspondiente:

> Molina-Pérez, G., et al. (pendiente de publicación). *sqrt_etmax: distribución SQRT-ETmax para Python*. Journal of Open Source Software. DOI: [pendiente]

## Ejecución de Pruebas (Tests)

El proyecto incluye una suite de pruebas unitarias basadas en `pytest` para garantizar el comportamiento correcto de las funciones matemáticas (CDF, PDF, ajustes, etc.).

Para correr las pruebas, primero instala las dependencias de desarrollo:

```bash
pip install -e .[test]
pytest tests/
```

## Contribuciones y Reporte de Errores

Si deseas contribuir al código o has encontrado algún comportamiento matemático anómalo, por favor revisa el archivo CONTRIBUTING.md para más detalles sobre cómo abrir un *Pull Request* o un *Issue*.
