← Volver al módulo Clima

Análisis climático

API Reference

Clases

class HierarchicalGEV
from pyhydra.climate.spatial_analysis.bayes_hierarchical import HierarchicalGEV

Modelo GEV jerárquico bayesiano estimado por MCMC (PyMC + NUTS). Usa parametrización no centrada para mejor mezcla cuando las series de estación son cortas o heterogéneas. Valores NaN en la matriz de máximos anuales se enmascaran automáticamente.

Dependencia: Requiere PyMC (prod/Azure) o PyStan 3 (local). Sin compilación C++ con PyMC.

Parámetros del constructor

Nombre Tipo Defecto Descripción
T_values tuple[int, ...] (2, 10, 50, 100) Periodos de retorno para cuantiles a posteriori.
n_chains int 4 Cadenas MCMC.
n_samples int 1000 Muestras por cadena tras calentamiento.
warmup int 1000 Pasos de calentamiento.
adapt_delta float 0.99 Target acceptance rate del sampler NUTS.

Métodos

fit fit(data_dict) → self

Ajusta el modelo jerárquico. Usa PyMC si está instalado; cae automáticamente a PyStan 3.

Parámetro Tipo Descripción
data_dict dict[str, array-like] nombre_estacion → array 1D de máximos anuales.
posterior_summary posterior_summary() → pd.DataFrame

Resumen a posteriori: media, SD, HDI 94 %, R-hat por parámetro.

return_levels return_levels() → pd.DataFrame

Niveles de retorno a posteriori por estación y periodo T.

Ejemplo

from pyhydra.climate.spatial_analysis.bayes_hierarchical import HierarchicalGEV
model = HierarchicalGEV(T_values=(10, 50, 100), n_chains=4)
model.fit({"Est_A": am_a, "Est_B": am_b, "Est_C": am_c})
print(model.return_levels())
class IDWInterpolator
from pyhydra.climate.spatial_analysis.interpolation import IDWInterpolator

Interpolación espacial por distancia inversa ponderada (IDW). Implementación pura NumPy, sin dependencias externas.

Parámetros del constructor

Nombre Tipo Defecto Descripción
power float 2.0 Exponente de decaimiento con la distancia.

Métodos

fit fit(data, x_col="lon", y_col="lat", value_col="value") → self

Almacena coordenadas y valores de estación.

predict predict(grid_data, x_col="lon", y_col="lat") → np.ndarray

Interpola en nuevas ubicaciones.

Returns: ndarray de forma (n_grid,).

Ejemplo

from pyhydra.climate.spatial_analysis.interpolation import IDWInterpolator
idw = IDWInterpolator(power=2)
idw.fit(estaciones_df, x_col='lon', y_col='lat', value_col='precip')
grid_values = idw.predict(rejilla_df)
class KrigingInterpolator
from pyhydra.climate.spatial_analysis.interpolation import KrigingInterpolator

Kriging Universal espacial via pykrige. Estima variograma automáticamente y produce predicción más varianza de error.

Dependencia: Requiere: pip install pykrige

Parámetros del constructor

Nombre Tipo Defecto Descripción
variogram_model str "spherical" 'spherical', 'gaussian', 'exponential', 'linear'.
drift_terms list[str] ["regional_linear"] Términos de tendencia para Kriging Universal.

Métodos

fit fit(data, x_col="lon", y_col="lat", value_col="value") → self

Ajusta el variograma a los datos de estación.

predict predict(grid_data, x_col="lon", y_col="lat") → tuple[ndarray, ndarray]

Interpola.

Returns: (predicciones, varianza_error).

Ejemplo

from pyhydra.climate.spatial_analysis.interpolation import KrigingInterpolator
krig = KrigingInterpolator(variogram_model='spherical')
krig.fit(estaciones_df, x_col='lon', y_col='lat', value_col='precip_anual')
preds, variance = krig.predict(rejilla_df)
class GaussianProcessInterpolator
from pyhydra.climate.spatial_analysis.interpolation import GaussianProcessInterpolator

Regresión por Proceso Gaussiano (GPR) con scikit-learn. Soporta covariables adicionales (altitud, aspecto, etc.).

Dependencia: Requiere: pip install scikit-learn

Parámetros del constructor

Nombre Tipo Defecto Descripción
kernel Kernel | None None Kernel de covarianza. Por defecto RBF + WhiteKernel.
normalize_y bool True Normalizar la variable respuesta.

Métodos

fit fit(data, feature_cols, value_col="value") → self

Ajusta el GP.

Parámetro Tipo Descripción
feature_cols list[str] Columnas features, ej. ['lon', 'lat', 'elev'].
predict predict(grid_data, feature_cols) → tuple[ndarray, ndarray]

Predice.

Returns: (media, desviación_estándar).

Ejemplo

from pyhydra.climate.spatial_analysis.interpolation import GaussianProcessInterpolator
gpr = GaussianProcessInterpolator()
gpr.fit(estaciones_df, feature_cols=['lon', 'lat', 'elev'], value_col='precip_anual')
mean, std = gpr.predict(rejilla_df, feature_cols=['lon', 'lat', 'elev'])
class NeopreneGPReconstructor
from pyhydra.climate.spatial_analysis.interpolation import NeopreneGPReconstructor

Combina el modelo de lluvia NSRP (NEOPRENE) con un Proceso Gaussiano para reconstruir y simular precipitación en estaciones o rejillas espaciales. Calibra un generador estocástico por estación y usa un GP para la covariación espacial entre estaciones, permitiendo generar campos sintéticos coherentes espacialmente.

Parámetros del constructor

Nombre Tipo Defecto Descripción
gp_covariates list[str] | None None Covariables espaciales para el GP (ej. ['lon', 'lat', 'elev']). Si None, usa solo coordenadas.
temporal_resolution str "d" Resolución temporal: 'd' (diaria) o 'h' (horaria).
seasonality str "monthly" 'monthly' o 'seasonal' — agrupa parámetros NSRP por mes o por estación.
n_restarts_optimizer int 3 Reinicios del optimizador GP para evitar óptimos locales.

Métodos

fit

Calibra el generador NSRP para cada estación y el GP espacial.

Parámetro Tipo Descripción
station_obs dict[str, pd.Series] Dict {station_id: series_diaria}.
verbose bool Imprime progreso.
simulate_stations

Genera series sintéticas para las estaciones calibradas.

Parámetro Tipo Descripción
year_ini int Año de inicio de la simulación.
year_fin int Año de fin.

Returns: dict {station_id: pd.Series}.

simulate_spatial

Genera campos de precipitación en puntos de rejilla interpolando el GP.

Parámetro Tipo Descripción
station_meta pd.DataFrame Metadatos de estaciones con columnas lat, lon, [elev].
grid_meta pd.DataFrame Puntos de rejilla destino con columnas lat, lon, [elev].
year_ini int Año de inicio.
year_fin int Año de fin.

Returns: xr.Dataset con precipitación diaria por punto de rejilla.

Ejemplo

from pyhydra.climate.spatial_analysis.interpolation import NeopreneGPReconstructor
rec = NeopreneGPReconstructor(gp_covariates=['lon', 'lat', 'elev'], seasonality='monthly')
rec.fit(station_obs)
synth_stations = rec.simulate_stations(2030, 2070)
class CopulaCDFEmulator
from pyhydra.climate.spatial_analysis.interpolation import CopulaCDFEmulator

Sustituto de proceso gaussiano (emulador) para la CDF de cópulas multidimensionales costosas de evaluar. Entrena sobre millones de muestras Monte Carlo de la cópula original y luego predice P(X≤x) en milisegundos. Útil cuando la CDF de la cópula se necesita millones de veces (ej. nivel de retorno multivariante en rejilla).

Dependencia: Requiere openturns para el entrenamiento del GP. La predicción solo requiere numpy.

Parámetros del constructor

Nombre Tipo Defecto Descripción
n_mc_samples int 1_000_000 Muestras Monte Carlo para entrenar el emulador.
batch_size int 50_000 Tamaño de lote para predicción vectorizada.

Métodos

fit

Genera muestras de la cópula y entrena el GP emulador.

Parámetro Tipo Descripción
copula_model object Cópula con método sample(n) y jcdf(x) — ej. VineCopula.
n_dims int Número de dimensiones de la cópula.
predict

Evalúa la CDF emulada en puntos de consulta.

Parámetro Tipo Descripción
query_points ndarray Array shape (N, d) con valores entre 0 y 1.

Returns: ndarray shape (N,) con probabilidades acumuladas estimadas.

Ejemplo

from pyhydra.climate.spatial_analysis.interpolation import CopulaCDFEmulator
from pyhydra.climate.spatial_analysis.copulas import VineCopula
vine = VineCopula()
vine.fit(data)
emu = CopulaCDFEmulator(n_mc_samples=500_000)
emu.fit(vine, n_dims=3)
probs = emu.predict(query_grid)
class BivariateCopula
from pyhydra.climate.spatial_analysis.copulas import BivariateCopula

Cópula Archimediana bivariante para análisis de periodo de retorno en inundación compuesta. Ajusta marginales univariantes (GEV/log-normal/gamma por AIC) y una cópula paramétrica calibrada por τ de Kendall.

Parámetros del constructor

Nombre Tipo Defecto Descripción
family str "gumbel" 'gumbel', 'clayton', 'frank'.
marginal_families tuple ("gev", "lognorm", "gamma") Candidatos de marginal. Se elige el mejor por AIC.

Métodos

fit fit(x, y, labels=("X", "Y")) → self

Ajusta marginales y cópula.

Parámetro Tipo Descripción
x array-like Primera variable.
y array-like Segunda variable.
return_period return_period(x0, y0, scenario="OR") → float

T = 1 / P(exceedance).

Parámetro Tipo Descripción
scenario str 'OR': unión; 'AND': intersección.
return_period_contour return_period_contour(T, scenario="OR", n_pts=300) → tuple

Curva iso-T en espacio físico.

Returns: (x_curva, y_curva).

most_probable_event most_probable_event(T, scenario="OR", n_pts=500) → tuple

Evento de Diseño Más Probable (MPDE): punto de máxima densidad sobre la curva iso-T.

Returns: (x_mpde, y_mpde) o (None, None) si el contorno está vacío.

plot_contours plot_contours(T_list=(2, 5, 10, 25, 50, 100), scenario="both", data=True) → Figure

Gráfico estándar de periodo de retorno bivariante.

Ejemplo

from pyhydra.climate.spatial_analysis.copulas import BivariateCopula
cop = BivariateCopula(family='gumbel')
cop.fit(caudal, nivel_mar, labels=('Q (m³/s)', 'SL (m)'))
xc, yc = cop.return_period_contour(100, scenario='OR')
x_mpde, y_mpde = cop.most_probable_event(100)
class TrivariateCopula
from pyhydra.climate.spatial_analysis.copulas import TrivariateCopula

Cópula Archimediana trivariante para análisis de inundación compuesta con tres variables (p.ej. caudal, nivel del mar y precipitación). Ajusta tres marginales y un único parámetro de cópula (exchangeable) estimado mediante la τ de Kendall media de los tres pares.

Parámetros del constructor

Nombre Tipo Defecto Descripción
family str "gumbel" 'gumbel', 'clayton', 'frank'.
marginal_families tuple ("gev", "lognorm", "gamma") Candidatos de marginal seleccionados por AIC.

Métodos

fit fit(x, y, z, labels=("X","Y","Z")) → self

Ajusta marginales y parámetro de cópula trivariante.

Parámetro Tipo Descripción
x array-like Primera variable (ej. caudal).
y array-like Segunda variable (ej. nivel del mar).
z array-like Tercera variable (ej. precipitación).
joint_exceedance joint_exceedance(x0, y0, z0, scenario="OR") → float

P(X>x0, Y>y0, Z>z0) para escenario OR o AND.

return_period return_period(x0, y0, z0, scenario="OR") → float

T = 1 / P(exceedance).

conditional_contours conditional_contours(z_quantile, T_list, scenario="AND", n_pts=250) → dict

Curvas iso-T en el plano (X, Y) condicionadas a Z ≥ su cuantil z_quantile.

Returns: dict {T: (x_curva, y_curva)}.

plot plot(T_list=(2,10,50,100), z_quantiles=(0.5,0.8,0.95), scenario="AND") → Figure

Rejilla de contornos condicionales OR y AND para múltiples niveles de Z.

Ejemplo

from pyhydra.climate.spatial_analysis.copulas import TrivariateCopula
cop = TrivariateCopula(family='gumbel')
cop.fit(caudal, nivel_mar, precipitacion, labels=('Q', 'SL', 'P'))
contours = cop.conditional_contours(z_quantile=0.9, T_list=[50, 100, 500])
class FloodEventCopula
from pyhydra.climate.spatial_analysis.copulas import FloodEventCopula

Cópula Normal multivariante para generación sintética de hidrogramas de crecida. Ajusta marginales BIC-seleccionadas y una cópula Normal al catálogo de eventos observados.

Dependencia: Requiere: conda install -c conda-forge openturns

Parámetros del constructor

Nombre Tipo Defecto Descripción
continuous_vars list[str] ['Qmax', 'Qmed', 'Duracion'] Variables continuas — marginal automática por BIC.
discrete_vars list[str] ['shape_type'] Variables discretas — distribución empírica.

Métodos

fit fit(data) → self

Ajusta marginales y cópula Normal.

Parámetro Tipo Descripción
data pd.DataFrame DataFrame con una columna por variable.
sample sample(n_samples) → pd.DataFrame

Genera n_samples eventos sintéticos.

plot_marginals plot_marginals() → None

ECDF vs CDF ajustada por variable.

Ejemplo

from pyhydra.climate.spatial_analysis.copulas import FloodEventCopula
cop = FloodEventCopula(['Qmax', 'Qmed', 'Duracion'], ['shape_type'])
cop.fit(eventos_clasificados_df)
sinteticos = cop.sample(5000)
class VineCopula
from pyhydra.climate.spatial_analysis.copulas import VineCopula

Cópula vine d-dimensional (pair-copula construction) basada en pyvinecopulib. Soporta familias paramétricas (Gaussian, t, Clayton, Gumbel, Frank, Joe) y selección automática de estructura. Permite calcular la CDF conjunta, el período de retorno de Kendall y generar tormentas de diseño multivariantes.

Parámetros del constructor

Nombre Tipo Defecto Descripción
family_set list[str] | None None Familias candidatas. None = todas. Ej: ['gaussian', 'gumbel'].
marginal_families tuple[str] ("gev", "lognorm", "gamma") Familias candidatas para las marginales univariantes.

Métodos

fit

Ajusta marginales (por AIC) y estructura vine.

Parámetro Tipo Descripción
data pd.DataFrame | ndarray Observaciones shape (n, d).
labels list[str] | None Nombres de las variables.
sample

Genera muestras en el espacio original.

Parámetro Tipo Descripción
n_samples int Número de muestras.
seed int | None Semilla aleatoria.

Returns: pd.DataFrame.

jcdf

Evalúa la CDF conjunta en un punto.

Parámetro Tipo Descripción
x array-like Punto en espacio original, shape (d,).

Returns: float — P(X₁≤x₁, …, Xd≤xd).

kendall_return_period

Período de retorno de Kendall para un punto.

Parámetro Tipo Descripción
x array-like Punto en espacio original.

Returns: float — T en años.

most_probable_event

Evento de diseño más probable para T años.

Parámetro Tipo Descripción
T float Período de retorno.
n_pts int Puntos de búsqueda Monte Carlo.

Returns: ndarray — vector de diseño.

design_storm_ensemble

Ensemble de eventos para T años.

Parámetro Tipo Descripción
T float Período de retorno.
n_ensemble int Tamaño del ensemble.

Returns: pd.DataFrame con n_ensemble filas.

Ejemplo

from pyhydra.climate.spatial_analysis.copulas import VineCopula
vine = VineCopula(family_set=['gumbel', 'frank', 'gaussian'])
vine.fit(station_df[['P1', 'P2', 'P3']])
synth = vine.sample(10000)
T_kendall = vine.kendall_return_period([80, 60, 45])
class GaussianCopulaSampler
from pyhydra.climate.spatial_analysis.copulas import GaussianCopulaSampler

Cópula gaussiana con marginales pre-especificadas. A diferencia de FloodEventCopula (que usa openturns), acepta objetos scipy.stats como marginales — útil cuando los parámetros ya están ajustados externamente.

Parámetros del constructor

Nombre Tipo Defecto Descripción
marginals list[rv_continuous] — Lista de distribuciones scipy.stats con parámetros fijados.
names list[str] — Nombres de las variables.

Métodos

sample

Genera muestras correlacionadas de las marginales.

Parámetro Tipo Descripción
n_samples int Número de muestras.
rho ndarray Matriz de correlación (d×d).
seed int | None Semilla aleatoria.

Returns: pd.DataFrame con columnas según names.

from_data

Método de clase: ajusta marginales y estima la matriz de correlación de la cópula a partir de datos.

Parámetro Tipo Descripción
data pd.DataFrame Observaciones.
families list[str] Familias candidatas para cada marginal, ej. ['gev', 'lognorm'].

Returns: GaussianCopulaSampler ajustado.

Ejemplo

from scipy.stats import lognorm, gamma
from pyhydra.climate.spatial_analysis.copulas import GaussianCopulaSampler
marginals = [lognorm(s=0.8, scale=50), gamma(a=2.5, scale=10)]
sampler = GaussianCopulaSampler(marginals, names=['Qmax', 'Dur'])
import numpy as np
rho = np.array([[1.0, 0.65], [0.65, 1.0]])
samples = sampler.sample(5000, rho)
class BiasCorrection
from pyhydra.climate.bias_correction.quantile import BiasCorrection

Corrección de sesgo cuantílica para series de modelo climático. Implementa mapeo cuantílico aditivo empírico, mapeo delta cuantílico multiplicativo y mapeo de distribución escalada (SDM) paramétrico.

Parámetros del constructor

Nombre Tipo Defecto Descripción
obs array-like — Serie observada (periodo de calibración).
mod array-like — Serie modelo histórico (mismo periodo).
sce array-like — Serie modelo escenario futuro a corregir.

Métodos

quantile_mapping quantile_mapping() → np.ndarray

Mapeo cuantílico aditivo empírico: aplica el delta de cuantil entre obs y mod histórico a la serie de escenario.

Returns: Array con la serie de escenario corregida.

quantile_deltamapping quantile_deltamapping() → np.ndarray

Mapeo delta cuantílico multiplicativo: preserva la señal de cambio relativa del modelo mientras corrige la distribución.

Returns: Array con la serie de escenario corregida.

scaled_distribution_mapping scaled_distribution_mapping(variable, **kwargs) → np.ndarray

Mapeo de distribución escalada paramétrico. Usa distribución gamma para precipitación ('pr') y normal para temperatura.

Parámetro Tipo Descripción
variable str 'pr' para precipitación (gamma); cualquier otro string para temperatura (normal).

Returns: Array con la serie de escenario corregida.

Ejemplo

from pyhydra.climate.bias_correction.quantile import BiasCorrection
bc = BiasCorrection(obs=precip_obs, mod=precip_hist, sce=precip_fut)
corrected_qm  = bc.quantile_mapping()
corrected_qdm = bc.quantile_deltamapping()
corrected_sdm = bc.scaled_distribution_mapping(variable='pr')
class HydrographClassifier
from pyhydra.climate.hybrid_downscaling.classification import HydrographClassifier

Clasifica hidrogramas de crecida en tipos morfológicos mediante PCA + K-means. Estandariza los hidrogramas a n_points antes de reducir a componentes principales.

Dependencia: Requiere: pip install scikit-learn

Parámetros del constructor

Nombre Tipo Defecto Descripción
discharge pd.Series — Serie de caudal con DatetimeIndex.
events_bounds pd.DataFrame — DataFrame con columnas 'start' y 'end' de cada evento.
n_types int — Número de tipos morfológicos (clusters K-means).
n_points int 100 Puntos de resampleo por hidrograma.

Métodos

fit fit() → pd.DataFrame

Ejecuta PCA + K-means y devuelve el catálogo de eventos clasificados.

Returns: DataFrame con columnas Qmax, Qmed, Duracion, shape_type por evento.

Ejemplo

from pyhydra.climate.hybrid_downscaling.classification import HydrographClassifier
clf = HydrographClassifier(discharge=Q, events_bounds=bounds, n_types=4)
classified = clf.fit()
class HydrographReconstructor
from pyhydra.climate.hybrid_downscaling.reconstruction import HydrographReconstructor

Reconstruye hidrogramas sintéticos a partir de la cópula FloodEventCopula y el clasificador de tipos. Aplica MaxDiss para reducir el catálogo a n_representatives eventos de simulación.

Parámetros del constructor

Nombre Tipo Defecto Descripción
discharge pd.Series — Serie de caudal histórica con DatetimeIndex.
synthetic_matrix pd.DataFrame — Eventos sintéticos de la cópula (Qmax, Qmed, Duracion, shape_type).
classified_events pd.DataFrame — Catálogo clasificado de HydrographClassifier.fit().
n_types int — Número de tipos morfológicos.
n_representatives int 400 Eventos representativos a seleccionar con MaxDiss.
output_dir str "." Directorio de salida para CSV de hidrogramas.
plot bool False Visualizar los hidrogramas reconstruidos.

Métodos

run run() → tuple[pd.DataFrame, pd.DataFrame]

Selecciona representativos, reconstruye hidrogramas y escribe Hidrograma_{j}.csv y centroids.csv.

Returns: (centroids_df, synthetic_matrix_filtered).

Ejemplo

from pyhydra.climate.hybrid_downscaling.reconstruction import HydrographReconstructor
rec = HydrographReconstructor(Q, synthetic_df, classified_df, n_types=4, n_representatives=400, output_dir='./hidrogramas')
centroids, subset = rec.run()
class FloodEventSelector
from pyhydra.climate.hybrid_downscaling.event_selection import FloodEventSelector

Pipeline completo de selección de eventos de inundación: extrae picos de caudal independientes, clasifica por forma del hidrograma, ajusta marginales, calibra una cópula multivariante y genera un catálogo sintético. Núcleo del flujo de trabajo de downscaling hidrológico.

Parámetros del constructor

Nombre Tipo Defecto Descripción
discharge pd.Series — Serie de caudal diario (m³/s).
threshold float — Umbral para extracción de eventos (m³/s).
threshold2 float | None None Segundo umbral para clasificación de tipos.
n_types int 25 Tipos de hidrograma a clasificar.
n_synthetic int 5000 Tamaño del catálogo sintético.
plot bool False Genera figuras diagnóstico.
output_dir str | None None Directorio para guardar figuras y CSV.

Métodos

extract_events

Extrae picos POT independientes.

Returns: pd.DataFrame con eventos.

classify_events

Clasifica eventos por forma (K-Means en características del hidrograma).

fit_marginals

Ajusta distribuciones marginales por tipo de evento.

fit_copula

Calibra la cópula multivariante sobre los eventos reales.

generate_synthetic

Muestrea el catálogo sintético de la cópula.

Parámetro Tipo Descripción
seed int | None Semilla aleatoria.

Returns: pd.DataFrame con catálogo sintético.

run

Ejecuta el pipeline completo de forma secuencial.

Parámetro Tipo Descripción
seed int | None Semilla aleatoria.

Returns: pd.DataFrame — catálogo sintético.

summary

Imprime resumen de los eventos extraídos y el ajuste.

Ejemplo

from pyhydra.climate.hybrid_downscaling.event_selection import FloodEventSelector
sel = FloodEventSelector(
    discharge=Q, threshold=200, n_types=25, n_synthetic=5000,
    plot=True, output_dir='./output'
)
synthetic_df = sel.run(seed=42)
class FloodCopulaComparison
from pyhydra.climate.hybrid_downscaling.event_selection import FloodCopulaComparison

Compara cuatro familias de cópulas bivariantes (Gaussiana, Gumbel, Clayton, Frank) para un conjunto de eventos de inundación. Ayuda a seleccionar la familia más adecuada antes de construir la cópula multivariante.

Métodos

fit

Ajusta las cuatro cópulas al DataFrame de eventos.

Parámetro Tipo Descripción
events_df pd.DataFrame DataFrame con columnas de características del evento.
summary_table

Devuelve tabla con AIC, BIC y τ de Kendall para cada familia.

Returns: pd.DataFrame.

best_family

Devuelve el nombre de la familia con menor AIC.

Returns: str.

plot_comparison

Figura 2×2 con scatter de probabilidades uniformes para cada familia.

Returns: matplotlib Figure.

Ejemplo

from pyhydra.climate.hybrid_downscaling.event_selection import FloodCopulaComparison
comp = FloodCopulaComparison()
comp.fit(events_df[['Qmax', 'Vol']])
print(comp.summary_table())
print("Best:", comp.best_family())
comp.plot_comparison()
class FloodMapInterpolator
from pyhydra.climate.hybrid_downscaling.interpolation import FloodMapInterpolator

Interpola mapas de inundación para el catálogo sintético completo mediante k-NN ponderado por distancia en el espacio de cópula. Calcula mapas de periodo de retorno pixel a pixel.

Dependencia: Requiere: conda install gdal

Parámetros del constructor

Nombre Tipo Defecto Descripción
synthetic_matrix pd.DataFrame — Catálogo sintético completo (Qmax, Qmed, Duracion, shape_type).
centroids pd.DataFrame — Centroides representativos seleccionados por MaxDiss.
simulations_dir str — Directorio con los GeoTIFF de simulación (hamax_sim_{j}.tif).
n_simulations int — Número total de simulaciones hidráulicas.
k_neighbors int 6 Vecinos k-NN para la interpolación.
landa float 4.943 Tasa media anual de eventos (λ) para la conversión a periodo de retorno.
output_dir str | None None Directorio para guardar GeoTIFF de periodo de retorno.

Métodos

compute_return_period_maps compute_return_period_maps(return_periods=(5,10,25,50,100,200,500,1000), n_blocks=20) → tuple

Calcula los mapas de periodo de retorno por bloques para gestionar memoria.

Returns: Tupla (calados_dict, geotiff_paths_list) — dict {T: ndarray(nrows,ncols)} y lista de rutas GeoTIFF.

Ejemplo

from pyhydra.climate.hybrid_downscaling.interpolation import FloodMapInterpolator
interp = FloodMapInterpolator(
    synthetic_matrix=subset, centroids=centroids,
    simulations_dir='./sfincs_runs/', n_simulations=400,
    landa=4.943, output_dir='./return_period_maps/'
)
calados, paths = interp.compute_return_period_maps(return_periods=(10, 50, 100, 500))
class FloodMapInterpolatorCC
from pyhydra.climate.hybrid_downscaling.interpolation import FloodMapInterpolatorCC

Extiende FloodMapInterpolator para cambio climático. Interpola mapas para dos catálogos sintéticos (histórico + escenario CC) usando los mismos hidrogramas de simulación, permitiendo comparar mapas de periodo de retorno entre periodos.

Dependencia: Requiere: conda install gdal

Parámetros del constructor

Nombre Tipo Defecto Descripción
synthetic_matrix pd.DataFrame — Catálogo sintético histórico.
centroids pd.DataFrame — Centroides representativos históricos.
simulations_dir_hist str — Directorio de simulaciones históricas.
simulations_dir_cc str — Directorio de simulaciones de cambio climático.
n_simulations_hist int — Número de simulaciones históricas.
n_simulations_cc int — Número de simulaciones CC.
k_neighbors int 6 Vecinos k-NN.
landa float 4.943 Tasa media anual de eventos λ.
output_dir str | None None Directorio de salida GeoTIFF.

Ejemplo

from pyhydra.climate.hybrid_downscaling.interpolation import FloodMapInterpolatorCC
interp_cc = FloodMapInterpolatorCC(
    synthetic_matrix=subset_hist, centroids=centroids_hist,
    simulations_dir_hist='./sfincs_hist/', simulations_dir_cc='./sfincs_cc/',
    n_simulations_hist=400, n_simulations_cc=400,
    landa=4.943, output_dir='./return_period_cc/'
)
calados_hist, calados_cc = interp_cc.compute_return_period_maps(return_periods=(10, 50, 100, 500))

Funciones

function extract_events
from pyhydra.climate.time_series.events import extract_events

Punto de entrada unificado para extracción de eventos. Redirige a la función específica según el tipo de variable y el método elegido.

Parámetros

Nombre Tipo Defecto Descripción
series pd.Series — Serie temporal con DatetimeIndex.
threshold float — Umbral de detección de eventos.
variable str "discharge" 'discharge' o 'precipitation'.
method str "spell" Precipitación: 'spell' (manchas húmedas), 'pot' (picos sobre umbral), 'nday' (acumulación N días).
threshold2 float | None None Caudal: pico mínimo para retener un evento.
min_duration int 1 Precipitación spell: duración mínima del evento (días).
min_sep int 7 POT: separación máxima entre excedencias del mismo cluster (días).
n_days int 3 N-day: ventana de acumulación en días.

Returns

Tupla (stats, bounds) — stats: DataFrame con métricas del evento; bounds: DataFrame con columnas 'start', 'end'.

Ejemplo

from pyhydra.climate.time_series.events import extract_events
stats, bounds = extract_events(caudal, threshold=200, variable='discharge')
stats_precip, _ = extract_events(precip, threshold=30, variable='precipitation', method='pot')
function extract_discharge_events
from pyhydra.climate.time_series.events import extract_discharge_events

Identifica eventos de crecida en una serie de caudal mediante el método de puntos de inflexión. Los eventos empiezan antes de que el limbo ascendente cruce el umbral y terminan cuando el limbo descendente baja por debajo.

Parámetros

Nombre Tipo Defecto Descripción
series pd.Series — Serie de caudal con DatetimeIndex.
threshold float — Caudal mínimo para definir un evento (m³/s).
threshold2 float | None None Pico mínimo para retener el evento. Por defecto igual a threshold.
plot bool False Si True, muestra el evento más grande con marcadores.

Returns

Tupla (stats, bounds). stats: DataFrame con [peak, mean, duration, volume, date_peak]. bounds: DataFrame con [start, end].

Ejemplo

from pyhydra.climate.time_series.events import extract_discharge_events
stats, bounds = extract_discharge_events(caudal_diario, threshold=200, threshold2=400)
print(f"{len(stats)} eventos | pico máximo: {stats['peak'].max():.0f} m³/s")
function extract_precipitation_events_pot
from pyhydra.climate.time_series.events import extract_precipitation_events_pot

Extrae eventos extremos de precipitación mediante POT con declustering. Identifica excedencias, las agrupa en clusters, retiene el pico de cada cluster y lo expande a la mancha húmeda contigua. Produce eventos aproximadamente independientes, adecuados para ajustar GPD o GEV.

Parámetros

Nombre Tipo Defecto Descripción
series pd.Series — Serie de precipitación diaria con DatetimeIndex.
threshold float — Precipitación diaria mínima para excedencia POT (mm). Típicamente percentil 90–95 de días lluviosos.
min_sep int 7 Máximo gap en días entre excedencias del mismo cluster.

Returns

Tupla (stats, bounds). stats: DataFrame con [peak, total, duration, mean_intensity, date_peak].

Ejemplo

from pyhydra.climate.time_series.events import extract_precipitation_events_pot
stats, bounds = extract_precipitation_events_pot(
    precip_diaria, threshold=30.0, min_sep=7
)
function extract_concurrent_events
from pyhydra.climate.time_series.events import extract_concurrent_events

Extrae estadísticos en múltiples estaciones durante las ventanas de eventos detectados en una estación objetivo. Útil para análisis de extremos compuestos/concurrentes y construcción de datasets multivariantes.

Parámetros

Nombre Tipo Defecto Descripción
event_bounds pd.DataFrame — Ventanas de eventos con columnas 'start' y 'end' — salida de cualquier extract_*_events().
series_dict dict[str, pd.Series] — Dict nombre_estacion → pd.Series, todos con el mismo DatetimeIndex.
buffer_days int 0 Extiende cada ventana N días a cada lado para capturar respuestas desfasadas.
stats tuple[str, ...] ('max', 'mean', 'total') Estadísticos a calcular: 'max', 'mean', 'total'.

Returns

pd.DataFrame con una fila por evento y columnas '<nombre>_max', '<nombre>_mean', '<nombre>_total' por estación.

Ejemplo

from pyhydra.climate.time_series.events import extract_discharge_events, extract_concurrent_events
_, bounds = extract_discharge_events(Q_salida, threshold=200)
concurrent = extract_concurrent_events(
    bounds,
    series_dict={'P_cuenca': precip, 'Q_entrada': Q_entrada},
    buffer_days=2,
)
function extract_precipitation_events
from pyhydra.climate.time_series.events import extract_precipitation_events

Extrae manchas húmedas (wet spells) de una serie de precipitación. Pasos de tiempo consecutivos con precipitación superior a threshold forman un evento. Los huecos secos más cortos que min_gap se fusionan. Eventos más cortos que min_duration se descartan.

Parámetros

Nombre Tipo Defecto Descripción
series pd.Series — Serie de precipitación con DatetimeIndex.
threshold float 0.0 Precipitación mínima para considerar un paso húmedo (mm).
min_duration int 1 Duración mínima del evento en pasos de tiempo.
min_gap int 1 Días secos entre dos períodos húmedos que se fusionan en un evento.

Returns

Tupla (stats, bounds). stats: DataFrame con [peak, total, duration, mean_intensity, date_start]. bounds: DataFrame con [start, end].

Ejemplo

from pyhydra.climate.time_series.events import extract_precipitation_events
stats, bounds = extract_precipitation_events(precip, threshold=1.0, min_duration=2)
function extract_precipitation_events_nday
from pyhydra.climate.time_series.events import extract_precipitation_events_nday

Extrae eventos basados en la acumulación N-días rodante. Identifica ventanas donde la suma N-días supera un umbral, agrupa ventanas solapadas y retiene el máximo de cada cluster. Útil para cuencas donde la acumulación multidía es el desencadenante de inundación.

Parámetros

Nombre Tipo Defecto Descripción
series pd.Series — Serie de precipitación diaria con DatetimeIndex.
n_days int 3 Ventana de acumulación en días.
threshold float | None None Acumulación mínima N-días (mm). Por defecto percentil 90 de la suma rodante.
min_sep int | None None Separación mínima en días entre picos retenidos. Por defecto n_days.

Returns

Tupla (stats, bounds). stats: DataFrame con [peak_nday, total, duration, date_peak]. bounds: DataFrame con [start, end].

Ejemplo

from pyhydra.climate.time_series.events import extract_precipitation_events_nday
stats, bounds = extract_precipitation_events_nday(precip, n_days=3, threshold=80.0)
function extract_block_maxima
from pyhydra.climate.time_series.extremes import extract_block_maxima

Extrae los máximos por bloque de una serie temporal. Equivalente GEV/Block-Maxima para análisis de frecuencia.

Parámetros

Nombre Tipo Defecto Descripción
series pd.Series — Serie temporal con DatetimeIndex.
freq str "YE" Frecuencia de bloque: 'YE' (anual), 'QE' (estacional), 'ME' (mensual).

Returns

pd.Series con máximos por bloque indexados por fecha de fin de bloque.

Ejemplo

from pyhydra.climate.time_series.extremes import extract_block_maxima
maximos_anuales = extract_block_maxima(caudal_diario, freq='YE')
function extract_pot
from pyhydra.climate.time_series.extremes import extract_pot

Extrae picos independientes sobre umbral (POT) para ajuste GPD. Detecta máximos locales e impone independencia mediante ventana mínima de separación.

Parámetros

Nombre Tipo Defecto Descripción
series pd.Series — Serie temporal con DatetimeIndex.
threshold float — Valor mínimo para que un pico sea retenido.
min_gap int 7 Pasos mínimos entre picos independientes.

Returns

pd.Series con picos indexados por timestamp.

function threshold_stability_plot
from pyhydra.climate.time_series.extremes import threshold_stability_plot

Gráfico de estabilidad del umbral GPD (exceso medio y parámetro de forma vs umbral). Un umbral adecuado es el más bajo donde ambos gráficos son aproximadamente lineales/planos.

Parámetros

Nombre Tipo Defecto Descripción
series pd.Series — Serie temporal.
thresholds ndarray | None None Umbrales a evaluar. Por defecto percentiles 50–95 en pasos del 1 %.
min_peaks int 10 Excedencias mínimas para incluir un punto.

Returns

pd.DataFrame con columnas: threshold, n_exceed, mean_excess, gpd_shape, gpd_scale.

function fit_gev
from pyhydra.climate.time_series.extremes import fit_gev

Ajusta una GEV a máximos por bloque. MLE robusto con arranque L-moments y varios puntos de inicio, o estimación pura por L-moments.

Parámetros

Nombre Tipo Defecto Descripción
data array-like — Máximos anuales o por bloque.
method str "mle" 'mle', 'lmom', o 'both'.
xi_bounds tuple (-0.5, 0.8) Límites del parámetro de forma para MLE.

Returns

dict con claves mu (localización), sigma (escala), xi (forma). xi > 0 → Fréchet; xi = 0 → Gumbel; xi < 0 → Weibull.

Ejemplo

from pyhydra.climate.time_series.extremes import extract_block_maxima, fit_gev
am = extract_block_maxima(caudal)
params = fit_gev(am, method='mle')  # {'mu': 450, 'sigma': 120, 'xi': 0.08}
function fit_gpd
from pyhydra.climate.time_series.extremes import fit_gpd

Ajusta una GPD a excedencias sobre un umbral. Extrae picos independientes con extract_pot y ajusta la distribución de Pareto Generalizada por MLE o L-momentos. Devuelve escala, forma, umbral, número de excedencias y tasa anual λ.

Parámetros

Nombre Tipo Defecto Descripción
series pd.Series | ndarray — Serie temporal completa (no pre-extraída).
threshold float — Umbral de excedencia.
method str "mle" 'mle' o 'lmom'.
min_gap int 7 Pasos mínimos entre picos independientes.
xi_bounds tuple (-0.5, 1.0) Límites del parámetro de forma para MLE.

Returns

dict con claves: scale, shape (xi), threshold, n_exceed, lambda_rate (picos/año).

Ejemplo

from pyhydra.climate.time_series.extremes import fit_gpd, return_level_gpd
params = fit_gpd(caudal, threshold=500, method='mle')
q100 = return_level_gpd(params, T=100)
function return_level_gev
from pyhydra.climate.time_series.extremes import return_level_gev

Calcula el nivel de retorno GEV para un período de retorno T (años).

Parámetros

Nombre Tipo Defecto Descripción
params dict — Salida de fit_gev() — claves: mu, sigma, xi.
T float — Período de retorno en años.

Returns

float — nivel de retorno para T años.

Ejemplo

from pyhydra.climate.time_series.extremes import extract_block_maxima, fit_gev, return_level_gev
am = extract_block_maxima(caudal_diario)
params = fit_gev(am, method='mle')
q100 = return_level_gev(params, T=100)
print(f"Q100 = {q100:.1f} m³/s")
function return_level_gpd
from pyhydra.climate.time_series.extremes import return_level_gpd

Calcula el nivel de retorno GPD para un período de retorno T (años) usando el modelo de proceso de Poisson: x_T = u + (σ/ξ) × ((λ·T)^ξ − 1).

Parámetros

Nombre Tipo Defecto Descripción
params dict — Salida de fit_gpd() — claves: scale, shape, threshold, lambda_rate.
T float — Período de retorno en años.

Returns

float — nivel de retorno para T años.

Ejemplo

from pyhydra.climate.time_series.extremes import fit_gpd, return_level_gpd
params = fit_gpd(caudal_diario, threshold=500, method='mle')
q100 = return_level_gpd(params, T=100)
print(f"Q100 (GPD) = {q100:.1f} m³/s")
function return_levels
from pyhydra.climate.time_series.extremes import return_levels

Calcula niveles de retorno para múltiples períodos T a partir de parámetros GEV o GPD ajustados.

Parámetros

Nombre Tipo Defecto Descripción
params dict — Salida de fit_gev() o fit_gpd().
T_values list[float] — Lista de períodos de retorno.
dist str "gev" 'gev' o 'gpd'.

Returns

pd.Series indexada por período de retorno.

Ejemplo

from pyhydra.climate.time_series.extremes import fit_gev, return_levels
params = fit_gev(annual_max)
rl = return_levels(params, [10, 50, 100, 500])
function return_level_ci
from pyhydra.climate.time_series.extremes import return_level_ci

Intervalo de confianza bootstrap para un nivel de retorno. Remuestrea los datos con reemplazamiento y ajusta la distribución en cada réplica para construir la banda de incertidumbre.

Parámetros

Nombre Tipo Defecto Descripción
data array-like — Máximos por bloque (GEV) o serie completa (GPD).
T float — Período de retorno.
dist str "gev" 'gev' o 'gpd'.
method str "mle" 'mle' o 'lmom'.
n_bootstrap int 500 Réplicas bootstrap.
ci float 0.95 Cobertura del intervalo.
threshold float | None None Requerido cuando dist=gpd.

Returns

Tupla (estimación_puntual, lower, upper).

Ejemplo

from pyhydra.climate.time_series.extremes import extract_block_maxima, return_level_ci
am = extract_block_maxima(caudal_diario)
q100, lo, hi = return_level_ci(am, T=100, dist='gev', n_bootstrap=500)
print(f"Q100 = {q100:.0f}  IC95% [{lo:.0f}, {hi:.0f}] m³/s")
function fit_gev_map
from pyhydra.climate.time_series.extremes import fit_gev_map

Estimación MAP (Maximum A Posteriori) de la GEV. Usa prior log-Normal en sigma y priors normales en mu y xi. No requiere MCMC: rápido y estable con priors débilmente informativos. Alternativa a fit_gev_mcmc para series largas.

Parámetros

Nombre Tipo Defecto Descripción
data array-like — Máximos por bloque.
mu_prior_mean float | None None Media del prior para mu. Por defecto media muestral.
sigma_prior_scale float 0.5 Desviación típica en escala log del prior de sigma.
xi_prior_std float 0.3 Desviación típica del prior de xi (centrado en 0).

Returns

dict con claves mu, sigma, xi, map_logpost.

Ejemplo

from pyhydra.climate.time_series.extremes import extract_block_maxima, fit_gev_map, return_level_gev
am = extract_block_maxima(caudal_diario)
params = fit_gev_map(am)
q100 = return_level_gev(params, T=100)
print(f"MAP: mu={params['mu']:.1f}, sigma={params['sigma']:.1f}, xi={params['xi']:.3f}")
function fit_gev_fisher
from pyhydra.climate.time_series.extremes import fit_gev_fisher

Incertidumbre de la GEV mediante la matriz de información de Fisher (covarianza asintótica). Mucho más rápido que MCMC. Válido cuando la serie es suficientemente larga (regla empírica: n ≥ 20). Muestrea de la distribución normal multivariante centrada en el MLE.

Parámetros

Nombre Tipo Defecto Descripción
data array-like — Máximos por bloque.
n_samples int 1000 Muestras de parámetros a generar.

Returns

pd.DataFrame con columnas mu, sigma, xi — una fila por muestra.

Ejemplo

from pyhydra.climate.time_series.extremes import fit_gev_fisher, return_level_gev
samples = fit_gev_fisher(annual_max, n_samples=2000)
rl_samples = samples.apply(lambda r: return_level_gev(r.to_dict(), 100), axis=1)
print(rl_samples.quantile([0.025, 0.5, 0.975]))
function fit_gev_mcmc
from pyhydra.climate.time_series.extremes import fit_gev_mcmc

Ajuste GEV bayesiano completo por MCMC para una única estación. Usa PyMC (NUTS) si está disponible; si no, PyStan 3 con código Stan incluido. Parametrización no centrada para mejor mezcla de cadenas.

Dependencia: Requiere PyMC o PyStan 3. Para análisis multi-estación usar HierarchicalGEV.

Parámetros

Nombre Tipo Defecto Descripción
data array-like — Máximos por bloque.
n_samples int 2000 Muestras por cadena tras calentamiento.
n_chains int 4 Cadenas MCMC.
adapt_delta float 0.95 Target acceptance rate NUTS.

Returns

pd.DataFrame con columnas mu, sigma, xi — muestras del posterior.

Ejemplo

from pyhydra.climate.time_series.extremes import extract_block_maxima, fit_gev_mcmc, return_level_gev
am = extract_block_maxima(caudal_diario)
posterior = fit_gev_mcmc(am, n_samples=2000, n_chains=4)
rl100 = posterior.apply(lambda r: return_level_gev(r.to_dict(), 100), axis=1)
print(rl100.quantile([0.025, 0.5, 0.975]))
function plot_return_levels
from pyhydra.climate.time_series.extremes import plot_return_levels

Curva de nivel de retorno con banda de confianza bootstrap. Muestra datos empíricos, ajuste GEV/GPD y banda de incertidumbre al nivel especificado.

Parámetros

Nombre Tipo Defecto Descripción
data array-like — Máximos por bloque o serie para POT.
params dict — Parámetros ajustados — salida de fit_gev() o fit_gpd().
dist str "gev" 'gev' o 'gpd'.
T_range tuple (1.5, 1000) Rango de períodos de retorno en el eje X.
n_bootstrap int 200 Réplicas para la banda de incertidumbre.
ci float 0.95 Cobertura de la banda de confianza.

Returns

matplotlib Axes.

function plot_diagnostic
from pyhydra.climate.time_series.extremes import plot_diagnostic

Panel diagnóstico 2×2: curva de nivel de retorno, densidad, Q-Q y P-P. Permite evaluar visualmente la calidad del ajuste GEV o GPD.

Parámetros

Nombre Tipo Defecto Descripción
data array-like — Máximos por bloque.
params dict — Salida de fit_gev() o fit_gpd().
dist str "gev" 'gev' o 'gpd'.

Returns

matplotlib Figure.

Ejemplo

from pyhydra.climate.time_series.extremes import fit_gev, plot_diagnostic
params = fit_gev(annual_max, method='mle')
fig = plot_diagnostic(annual_max, params, dist='gev')
function fit_gev_mle
from pyhydra.climate.spatial_analysis.rfa import fit_gev_mle

Ajusta GEV por MLE con optimización multi-arranque y parámetro de forma acotado. Diseñado para series cortas en análisis regional de frecuencia. Cae a L-moments si MLE falla.

Parámetros

Nombre Tipo Defecto Descripción
data array-like — Array 1D de máximos anuales.
xi_bounds tuple (-0.5, 0.8) Límites de xi.

Returns

dict con claves mu, sigma, xi.

function fit_gev_lmom
from pyhydra.climate.spatial_analysis.rfa import fit_gev_lmom

Ajusta una GEV por el método de L-momentos. Más robusto que MLE para muestras pequeñas (n < 30) aunque sin intervalos de confianza directos.

Dependencia: Requiere: pip install lmoments3

Parámetros

Nombre Tipo Defecto Descripción
data array-like — Array 1D de máximos anuales.

Returns

dict con claves mu (localización), sigma (escala), xi (forma).

Ejemplo

from pyhydra.climate.spatial_analysis.rfa import fit_gev_lmom, fit_gev_mle, return_level
params_lmom = fit_gev_lmom(maximos_anuales)
params_mle  = fit_gev_mle(maximos_anuales)
print(f"L-mom xi={params_lmom['xi']:.3f}  MLE xi={params_mle['xi']:.3f}")
q100 = return_level(params_lmom, 100)
function return_level
from pyhydra.climate.spatial_analysis.rfa import return_level

Calcula el nivel de retorno para un periodo T dado a partir de parámetros GEV.

Parámetros

Nombre Tipo Defecto Descripción
params dict — dict con mu, sigma, xi — salida de fit_gev_mle() o fit_gev_lmom().
T float | array-like — Periodo(s) de retorno en años.

Returns

Nivel de retorno — misma forma que T.

Ejemplo

from pyhydra.climate.spatial_analysis.rfa import fit_gev_mle, return_level
params = fit_gev_mle(maximos_anuales)
q100 = return_level(params, 100)
function fit_gev_bayes
from pyhydra.climate.spatial_analysis.rfa import fit_gev_bayes

Ajusta una GEV bayesiana mediante MCMC (PyMC + NUTS) para una única estación. Devuelve el posterior completo.

Dependencia: Requiere PyMC. Para análisis multi-estación usar HierarchicalGEV.

Parámetros

Nombre Tipo Defecto Descripción
data array-like — Array 1D de máximos anuales.
n_chains int 4 Cadenas MCMC.
n_samples int 1000 Muestras por cadena.

Returns

pd.DataFrame con columnas mu, sigma, xi (muestras del posterior).

Ejemplo

from pyhydra.climate.spatial_analysis.rfa import fit_gev_bayes, return_level_bayes
posterior = fit_gev_bayes(maximos_anuales, n_chains=4, n_samples=1000)
result = return_level_bayes(posterior, T=100)
print(f"Q100 = {result['median']:.0f} [{result['lower']:.0f}, {result['upper']:.0f}] m³/s")
function return_level_bayes
from pyhydra.climate.spatial_analysis.rfa import return_level_bayes

Calcula la distribución posterior del nivel de retorno para un periodo T a partir de muestras MCMC.

Parámetros

Nombre Tipo Defecto Descripción
posterior pd.DataFrame — Posterior de fit_gev_bayes() con columnas mu, sigma, xi.
T float — Periodo de retorno en años.
credible float 0.95 Amplitud del intervalo creíble.

Returns

dict con claves 'median', 'lower', 'upper'.

Ejemplo

from pyhydra.climate.spatial_analysis.rfa import fit_gev_bayes, return_level_bayes
posterior = fit_gev_bayes(maximos_anuales, n_samples=1000)
ic = return_level_bayes(posterior, T=100, credible=0.95)
print(f"mediana={ic['median']:.0f}  IC95%=[{ic['lower']:.0f}, {ic['upper']:.0f}]")
function regional_index_flood
from pyhydra.climate.spatial_analysis.rfa import regional_index_flood

Normaliza cada serie estacional por su crecida índice (media de máximos anuales). Paso previo al análisis regional de frecuencia.

Parámetros

Nombre Tipo Defecto Descripción
data_dict dict[str, array-like] — nombre_estacion → array 1D de máximos anuales.

Returns

Tupla (normalised_dict, index_floods_Series) — series normalizadas y crecidas índice por estación.

Ejemplo

from pyhydra.climate.spatial_analysis.rfa import regional_index_flood, fit_regional_gev
data = {'Est_A': am_a, 'Est_B': am_b, 'Est_C': am_c}
norm_dict, index_floods = regional_index_flood(data)
regional_params, _ = fit_regional_gev(data, method='lmom')
function fit_regional_gev
from pyhydra.climate.spatial_analysis.rfa import fit_regional_gev

Ajusta una GEV regional a los datos normalizados y agrupados de todas las estaciones.

Parámetros

Nombre Tipo Defecto Descripción
data_dict dict[str, array-like] — nombre_estacion → array 1D de máximos anuales.
method str "lmom" 'lmom' o 'mle'.

Returns

Tupla (regional_params_dict, index_floods_Series).

Ejemplo

from pyhydra.climate.spatial_analysis.rfa import fit_regional_gev, regional_return_levels
data = {'Est_A': am_a, 'Est_B': am_b, 'Est_C': am_c}
params, index_floods = fit_regional_gev(data, method='lmom')
df_rl = regional_return_levels(data, T_values=(10, 50, 100))
function regional_return_levels
from pyhydra.climate.spatial_analysis.rfa import regional_return_levels

Calcula los niveles de retorno para T años en cada estación mediante la GEV regional.

Parámetros

Nombre Tipo Defecto Descripción
data_dict dict[str, array-like] — nombre_estacion → array 1D de máximos anuales.
T_values tuple[int, ...] (2, 5, 10, 20, 50, 100) Periodos de retorno en años.
method str "lmom" 'lmom' o 'mle'.

Returns

pd.DataFrame (estaciones × periodos T) con niveles de retorno.

Ejemplo

from pyhydra.climate.spatial_analysis.rfa import regional_return_levels
df = regional_return_levels({'Est_A': am_a, 'Est_B': am_b}, T_values=(10, 50, 100))
function delta_method
from pyhydra.climate.bias_correction.delta import delta_method

Aplica el método Delta para proyectar una serie observada a condiciones futuras. Calcula deltas mensuales entre el modelo histórico y futuro, y los aplica multiplicativamente (precipitación) o aditivamente (temperatura).

Parámetros

Nombre Tipo Defecto Descripción
serie_raw pd.Series — Serie observada a modificar (DatetimeIndex).
serie_hist pd.Series — Serie modelo histórico.
serie_mod pd.Series — Serie modelo futuro.
var str — 'pr' para precipitación (delta multiplicativo); cualquier otro string para delta aditivo (temperatura, etc.).
stat str — 'mean' o 'median' — cómo agregar deltas de múltiples modelos.

Returns

pd.Series con valores corregidos e índice temporal desplazado al periodo futuro.

Ejemplo

from pyhydra.climate.bias_correction.delta import delta_method
fut = delta_method(precip_obs, precip_hist_model, precip_fut_model, var='pr', stat='mean')
function find_spatial_arrangement
from pyhydra.climate.hybrid_downscaling.classification import find_spatial_arrangement

Encuentra la disposición espacial óptima de los centroides de tipos de hidrograma en una rejilla n_rows × n_cols minimizando la distancia total de flujo (algoritmo D8).

Parámetros

Nombre Tipo Defecto Descripción
n_rows int — Filas de la rejilla de disposición.
n_cols int — Columnas de la rejilla.
centers array-like — Centroides PCA de los tipos de hidrograma.
iters int 200000 Iteraciones de búsqueda aleatoria.
method str "D8" Algoritmo de conectividad: 'D8'.

Returns

Lista con la mejor permutación de tipos en la rejilla.

Ejemplo

from pyhydra.climate.hybrid_downscaling.classification import HydrographClassifier, find_spatial_arrangement
clf = HydrographClassifier(Q, bounds, n_types=25)
classified = clf.fit()
# Organizar los 25 tipos en rejilla 5x5 para el modelo SFINCS
arrangement = find_spatial_arrangement(n_rows=5, n_cols=5, centers=clf.pca_centers_)
function maxdiss
from pyhydra.climate.hybrid_downscaling.reconstruction import maxdiss

Selección MaxDiss (Maximally Dissimilar): elige n_select eventos representativos del conjunto sintético maximizando la disimilaridad entre ellos. Algoritmo greedy de complejidad O(n × k).

Parámetros

Nombre Tipo Defecto Descripción
data pd.DataFrame — Conjunto de eventos sintéticos.
n_select int — Número de eventos representativos a seleccionar.
scalar_cols list[str] — Columnas escalares para el cálculo de distancia.
seed_positions list[int] — Índices semilla para inicializar la selección.

Returns

Tupla (subset_df, positions_list) — eventos seleccionados y sus índices en el conjunto original.

Ejemplo

from pyhydra.climate.hybrid_downscaling.reconstruction import maxdiss
subset, positions = maxdiss(
    synthetic_df, n_select=400,
    scalar_cols=['Qmax', 'Qmed', 'Duracion'],
    seed_positions=[0, 1],
)
print(f"Seleccionados {len(subset)} de {len(synthetic_df)} eventos sintéticos")
function pixel_return_period
from pyhydra.climate.hybrid_downscaling.return_period import pixel_return_period

Calcula el periodo de retorno pixel a pixel a partir de un bloque de calados de eventos mediante una distribución de Poisson–GEV. Implementación vectorizada sobre ndarray.

Dependencia: Requiere: conda install gdal

Parámetros

Nombre Tipo Defecto Descripción
events_block list[ndarray] — Lista de arrays 2D (nrows, ncols) con calados de cada evento.
landa float — Tasa media anual de eventos (λ).
return_periods tuple[int, ...] (5,10,25,50,100,200,500,1000) Periodos de retorno a calcular.

Returns

Dict {T: ndarray(nrows, ncols)} con el calado máximo esperado para cada periodo de retorno.

function save_return_period_geotiffs
from pyhydra.climate.hybrid_downscaling.return_period import save_return_period_geotiffs

Exporta los mapas de periodo de retorno como archivos GeoTIFF usando un raster de plantilla para georreferenciación.

Dependencia: Requiere: conda install gdal

Parámetros

Nombre Tipo Defecto Descripción
calados dict[int, ndarray] — Dict {T: ndarray} de salida de pixel_return_period().
template_tif str — Ruta al GeoTIFF de plantilla con CRS y geotransformación de referencia.
output_dir str — Directorio de salida para los GeoTIFF generados.

Returns

Lista de objetos Path a los archivos GeoTIFF generados.

Ejemplo

from pyhydra.climate.hybrid_downscaling.return_period import pixel_return_period, save_return_period_geotiffs
calados = pixel_return_period(events_block, landa=4.943, return_periods=(10, 50, 100, 500))
paths = save_return_period_geotiffs(calados, template_tif='hamax_sim_0.tif', output_dir='./output/')