← Volver al módulo Simulación

Generación estocástica

API Reference

Clases

class NSRPModel
from pyhydra.climate.stochastic_generation.point import NSRPModel

Generador estocástico de precipitación en un punto (NSRP — Neyman-Scott Rectangular Pulses). Calibrado con PSO sobre estadísticos observados.

Dependencia: Requiere: pip install NEOPRENE (https://github.com/IHCantabria/NEOPRENE)

Parámetros del constructor

Nombre Tipo Defecto Descripción
temporal_resolution str "d" 'd' (diario) o 'h' (horario).
seasonality str "monthly" 'annual', 'seasonal', 'monthly', 'user_defined'.
n_iterations int 100 Iteraciones PSO.
n_bees int 100 Tamaño enjambre PSO. Usar 1000 para producción.

Métodos

fit fit(series) → self

Calibra NSRP con PSO.

Parámetro Tipo Descripción
series pd.Series Precipitación diaria con DatetimeIndex.
simulate simulate(from_year, to_year) → pd.Series

Genera precipitación sintética.

Parámetro Tipo Descripción
from_year int Año inicio.
to_year int Año fin.

Ejemplo

from pyhydra.climate.stochastic_generation.point import NSRPModel
modelo = NSRPModel(temporal_resolution='d', seasonality='monthly')
modelo.fit(precip_diaria)
sintetica = modelo.simulate(2000, 2100)
class STNSRPModel
from pyhydra.climate.stochastic_generation.spatial import STNSRPModel

Generador espacio-temporal de precipitación multi-estación (STNSRP). Preserva estadísticos puntuales y correlaciones cruzadas espaciales entre estaciones.

Dependencia: Requiere: pip install NEOPRENE

Parámetros del constructor

Nombre Tipo Defecto Descripción
temporal_resolution str "d" 'd' o 'h'.
seasonality str "monthly" 'annual', 'seasonal', 'monthly', 'user_defined'.
n_iterations int 100 Iteraciones PSO.
n_bees int 100 Tamaño enjambre PSO.
cell_radius list[float] [1.0, 50.0] Límites PSO del radio de celda de tormenta [min_km, max_km]. Debe ser lista de exactamente dos flotantes.
coordinates str "geographical" 'geographical' (lat/lon) o 'UTM'.

Métodos

fit fit(multisite_df, attributes) → self

Calibra STNSRP para múltiples estaciones preservando correlaciones espaciales.

Parámetro Tipo Descripción
multisite_df pd.DataFrame Precipitación con columnas por estación y DatetimeIndex.
attributes pd.DataFrame DataFrame con columnas 'ID', 'Lon', 'Lat', 'elevation'.
simulate simulate(from_year, to_year, attributes) → pd.DataFrame

Genera precipitación simultánea en todas las estaciones.

Ejemplo

from pyhydra.climate.stochastic_generation.spatial import STNSRPModel
attrs = pd.DataFrame({'ID': ['S1','S2'], 'Lon': [-3.7,-3.8], 'Lat': [43.3,43.4], 'elevation': [10,20]})
modelo = STNSRPModel(temporal_resolution='d', seasonality='monthly')
modelo.fit(multisite_precip_df, attributes=attrs)
sintetica = modelo.simulate(2000, 2100, attributes=attrs)
class SpatialFieldModel
from pyhydra.climate.stochastic_generation.fields import SpatialFieldModel

Generador espacio-temporal de campos aleatorios (enfoque VAR de CoSMoS_py). Genera campos en rejilla o en ubicaciones irregulares con distribución marginal y estructura de correlación espacio-temporal especificada.

Dependencia: Requiere: pip install cosmos_py (https://github.com/navass11/CoSMoS_py)

Parámetros del constructor

Nombre Tipo Defecto Descripción
dist str — Distribución marginal: 'gengamma', 'burrXII', 'paretoII', 'burrIII', 'gev'.
dist_params dict — Parámetros de la distribución marginal.
p0 float 0.0 Probabilidad de cero (intermitencia). Usar 0 para temperatura o viento.
p int 1 Orden VAR (profundidad de lag temporal).
stcs_id str "clayton" Estructura de correlación espacio-temporal: 'clayton', 'gneiting14', 'gneiting16'.
dep_structure str "gauss" Cópula de dependencia espacial: 'gauss', 'student', 'bardossy'.
dep_arg float | None None Grados de libertad (Student-t) o parámetro m (Bardossy).
anisotropy_id str "affine" Transformación de anisotropía: 'affine', 'swirl', 'wave'.
advection_id str "uniform" Campo de advección: 'uniform', 'rotation', 'spiral'.

Métodos

fit fit(spacepoints) → self

Construye el modelo VAR(p) para el layout espacial dado.

Parámetro Tipo Descripción
spacepoints int | ndarray (n×2) Entero m → rejilla m×m regular; array → n_sites ubicaciones irregulares (x, y).
simulate simulate(n_steps, fast=False) → np.ndarray

Simula n_steps del campo espacio-temporal.

Returns: ndarray de forma (n_steps, n_sites).

simulate_dataframe simulate_dataframe(n_steps, start_date=None, freq="D") → pd.DataFrame

Simula y devuelve DataFrame con DatetimeIndex.

diagnostics diagnostics(n_steps=1000) → dict

Ejecuta una simulación de prueba y compara estadísticos vs objetivos.

Ejemplo

from pyhydra.climate.stochastic_generation.fields import SpatialFieldModel
model = SpatialFieldModel(
    dist='gengamma',
    dist_params={'scale': 5.0, 'shape1': 0.8, 'shape2': 0.5},
    p0=0.65,
    stcs_id='clayton',
    dep_structure='gauss',
)
model.fit(spacepoints=10)  # rejilla 10×10
campo = model.simulate(n_steps=365)   # shape (365, 100)

Funciones

function analyze_ts
from pyhydra.climate.stochastic_generation.point import analyze_ts

Ajusta un modelo estocástico estacional a una serie diaria. Envuelve cosmos_py para ajustar marginal y estructura de autocorrelación por mes. Para precipitación usar NSRPModel.

Dependencia: Requiere: pip install cosmos_py (https://github.com/navass11/CoSMoS_py)

Parámetros

Nombre Tipo Defecto Descripción
series pd.Series — Serie con DatetimeIndex. Ceros tratados como pasos secos.
season str "month" 'month' o 'week'.
dist str "gengamma" 'gengamma', 'paretoII', 'burrXII', 'burrIII', 'gev', 'lnorm'.
acs_id str "weibull" Modelo de autocorrelación: 'weibull', 'paretoII', …
lag_max int 30 Lag máximo para estimación empírica de ACF.

Returns

Dict con el modelo ajustado (entrada para simulate_ts / report_ts).

Ejemplo

from pyhydra.climate.stochastic_generation.point import analyze_ts, simulate_ts
modelo = analyze_ts(caudal_diario, dist='gengamma')
sintetico = simulate_ts(modelo, from_date='2000-01-01', to_date='2099-12-31')
function report_ts
from pyhydra.climate.stochastic_generation.point import report_ts

Resume un modelo estocástico ajustado con estadísticos estacionales, ajustes marginales o ajustes ACS.

Parámetros

Nombre Tipo Defecto Descripción
analyzed dict — Salida de analyze_ts().
method str "stat" 'stat' (DataFrame), 'dist' (gráficos marginales), 'acs' (gráficos ACS).

Returns

DataFrame de estadísticos estacionales cuando method='stat', None en caso contrario.

Ejemplo

from pyhydra.climate.stochastic_generation.point import analyze_ts, report_ts
modelo = analyze_ts(caudal_diario, dist='gengamma')
stats_df = report_ts(modelo, method='stat')
report_ts(modelo, method='dist')  # gráficos de ajuste marginal
function simulate_ts
from pyhydra.climate.stochastic_generation.point import simulate_ts

Genera una serie temporal diaria sintética a partir de un modelo ajustado.

Parámetros

Nombre Tipo Defecto Descripción
analyzed dict — Salida de analyze_ts().
from_date str | None None Fecha de inicio (por defecto: inicio del periodo de calibración).
to_date str | None None Fecha de fin.

Returns

pd.Series sintética.

Ejemplo

from pyhydra.climate.stochastic_generation.point import analyze_ts, simulate_ts
modelo = analyze_ts(caudal_diario, dist='gengamma')
sintetico = simulate_ts(modelo, from_date='2000-01-01', to_date='2099-12-31')
print(f"Generados {len(sintetico)} días de serie sintética")
function fit_spatial_model
from pyhydra.climate.stochastic_generation.fields import fit_spatial_model

Ajusta un modelo VAR(p) espacio-temporal a un conjunto de ubicaciones. API funcional equivalente a SpatialFieldModel.fit().

Parámetros

Nombre Tipo Defecto Descripción
spacepoints int | ndarray — Entero m (rejilla m×m) o array (n×2) de ubicaciones irregulares.
p int — Orden VAR.
dist str — Distribución marginal.
dist_params dict — Parámetros de la distribución.
p0 float 0.0 Probabilidad de cero.
stcs_id str "clayton" Estructura de correlación espacio-temporal.

Returns

Dict del modelo ajustado (entrada para generate_random_field / check_random_field).

Ejemplo

from pyhydra.climate.stochastic_generation.fields import fit_spatial_model, generate_random_field, check_random_field
import numpy as np
locations = np.random.rand(15, 2) * 100  # 15 estaciones irregulares
model = fit_spatial_model(locations, p=1, dist='gengamma',
                          dist_params={'scale': 5.0, 'shape1': 0.8, 'shape2': 0.5}, p0=0.6)
campo = generate_random_field(n_steps=365, model=model)
stats = check_random_field(campo, model)
function generate_random_field
from pyhydra.climate.stochastic_generation.fields import generate_random_field

Simula n_steps del campo aleatorio espacio-temporal ajustado.

Parámetros

Nombre Tipo Defecto Descripción
n_steps int — Pasos de tiempo a simular.
model dict — Salida de fit_spatial_model().

Returns

ndarray de forma (n_steps, n_sites).

Ejemplo

from pyhydra.climate.stochastic_generation.fields import fit_spatial_model, generate_random_field
model = fit_spatial_model(spacepoints=8, p=1, dist='gengamma',
                          dist_params={'scale': 5.0, 'shape1': 0.8, 'shape2': 0.5})
campo = generate_random_field(n_steps=365*30, model=model)  # 30 años, rejilla 8×8
function check_random_field
from pyhydra.climate.stochastic_generation.fields import check_random_field

Diagnóstico: compara estadísticos del campo simulado vs objetivos.

Parámetros

Nombre Tipo Defecto Descripción
field ndarray (n_steps, n_sites) — Salida de generate_random_field().
model dict — Salida de fit_spatial_model().

Returns

Dict con claves 'marginal' (DataFrame), 'spatial_acf' (ndarray), 'temporal_acf' (ndarray).

Ejemplo

from pyhydra.climate.stochastic_generation.fields import fit_spatial_model, generate_random_field, check_random_field
model = fit_spatial_model(spacepoints=8, p=1, dist='gengamma',
                          dist_params={'scale': 5.0, 'shape1': 0.8, 'shape2': 0.5})
campo = generate_random_field(365, model)
diag = check_random_field(campo, model)
print(diag['marginal'])