← Volver al módulo Modelos

Modelización

API Reference

Funciones

function generate_gage
from pyhydra.modeling.hydrology.hec_hms import generate_gage

Escribe o añade entradas de pluviómetro a un archivo .gage de HEC-HMS.

Dependencia: Requiere HEC-HMS 4.x (Windows) o HEC_HMS_DIR + xvfb (Linux/Docker).

Parámetros

Nombre Tipo Defecto Descripción
name_model str — Nombre del proyecto (sin extensión).
names_stations list[str] — Lista de nombres de pluviómetro.
time_interval str — Paso de tiempo HEC-HMS (ej. '1HOUR', '1DAY').
path_model str — Directorio del modelo.
start_time str — Inicio simulación (ej. '1 January 2010, 00:00').
end_time str — Fin simulación.
file_dss str — Archivo DSS de precipitación.
exists_gage bool False Si True, añade al archivo existente.

Returns

None. Escribe o actualiza el archivo .gage en path_model.

Ejemplo

from pyhydra.modeling.hydrology.hec_hms import generate_gage, generate_met, generate_flow
generate_gage(
    name_model='cuenca', names_stations=['P1', 'P2'],
    time_interval='1DAY', path_model='./hms/',
    start_time='1 January 2000, 00:00', end_time='31 December 2020, 00:00',
    file_dss='precipitacion.dss',
)
generate_met(
    name_model='cuenca', names_stations=['P1', 'P2'],
    names_subbasins=['Sub1', 'Sub2'], path_model='./hms/', file_dss='precipitacion.dss',
)
Q = generate_flow(path_dss='./hms/resultados.dss', station_name='Sub1', run_name='Run1')
function generate_met
from pyhydra.modeling.hydrology.hec_hms import generate_met

Genera o actualiza el archivo .met de modelo meteorológico de HEC-HMS, asignando pluviómetros a subcuencas.

Parámetros

Nombre Tipo Defecto Descripción
name_model str — Nombre del proyecto.
names_stations list[str] — Nombres de pluviómetros.
names_subbasins list[str] — Nombres de subcuencas.
path_model str — Directorio del modelo.
file_dss str — Archivo DSS referenciado.

Returns

None. Escribe o actualiza el archivo .met en path_model.

function generate_flow
from pyhydra.modeling.hydrology.hec_hms import generate_flow

Lee los resultados de caudal de una simulación HEC-HMS desde un archivo DSS.

Dependencia: Requiere: pip install pydsstools (ARM64 no compatible — usar Docker linux/amd64).

Parámetros

Nombre Tipo Defecto Descripción
path_dss str — Ruta al archivo DSS de resultados.
station_name str — Nombre de la subcuenca o punto de control.
run_name str — Nombre de la ejecución en el proyecto HEC-HMS.

Returns

pd.Series de caudal con DatetimeIndex.

function write_precipitation_file
from pyhydra.modeling.hydrology.swat import write_precipitation_file

Escribe un archivo de precipitación SWAT+ multi-estación en formato .pcp (formato legado SWAT 2012, una sola línea por día con todas las estaciones).

Parámetros

Nombre Tipo Defecto Descripción
df_coords pd.DataFrame — DataFrame con columnas ['Station', 'Lati', 'Long', 'Elev'].
df_series pd.DataFrame — DataFrame con DatetimeIndex y una columna por estación (mm/día).
output_path str — Ruta del archivo de salida (ej. 'TxtInOut/pcp1.pcp').
missing_value float -99.0 Valor para datos faltantes.

Returns

None. Escribe el archivo .pcp en output_path.

Ejemplo

from pyhydra.modeling.hydrology.swat import write_precipitation_file
import pandas as pd
df_coords = pd.DataFrame({'Station': ['P1'], 'Lati': [43.3], 'Long': [-3.7], 'Elev': [10]})
write_precipitation_file(df_coords, df_precip, output_path='TxtInOut/pcp1.pcp')
function write_swatplus_precipitation_files
from pyhydra.modeling.hydrology.swat import write_swatplus_precipitation_files

Escribe archivos de precipitación individuales para SWAT+ (un .pcp por estación) referenciados desde pcp.cli.

Parámetros

Nombre Tipo Defecto Descripción
df_stations pd.DataFrame — DataFrame con columnas ['name', 'lat', 'lon', 'elev'].
df_series pd.DataFrame — DataFrame con DatetimeIndex y una columna por estación (mm/día).
txtinout_dir str — Directorio TxtInOut de SWAT+.
missing_value float -99.0 Valor para datos faltantes.

Returns

None. Archivos .pcp escritos en txtinout_dir.

Ejemplo

from pyhydra.modeling.hydrology.swat import write_swatplus_precipitation_files, write_swatplus_temperature_files
import pandas as pd
df_st = pd.DataFrame({'name': ['P1','P2'], 'lat': [43.3,43.4], 'lon': [-3.7,-3.8], 'elev': [10,20]})
write_swatplus_precipitation_files(df_st, df_precip_mm, txtinout_dir='TxtInOut/')
write_swatplus_temperature_files(df_st, df_tmax, df_tmin, txtinout_dir='TxtInOut/')
function write_swatplus_temperature_files
from pyhydra.modeling.hydrology.swat import write_swatplus_temperature_files

Escribe archivos de temperatura individuales para SWAT+ (un .tmp por estación) referenciados desde tmp.cli.

Parámetros

Nombre Tipo Defecto Descripción
df_stations pd.DataFrame — DataFrame con columnas ['name', 'lat', 'lon', 'elev'].
df_tmax pd.DataFrame — Temperatura máxima diaria (°C), columnas = nombres de estación.
df_tmin pd.DataFrame — Temperatura mínima diaria (°C), misma estructura.
txtinout_dir str — Directorio TxtInOut de SWAT+.
missing_value float -99.0 Valor para datos faltantes.

Returns

None. Archivos .tmp y tmp.cli escritos en txtinout_dir.

function write_temperature_file
from pyhydra.modeling.hydrology.swat import write_temperature_file

Escribe el archivo de temperatura SWAT+ (.tmp) con Tmax y Tmin diarios.

Parámetros

Nombre Tipo Defecto Descripción
df_coords pd.DataFrame — DataFrame con columnas ['Station', 'Lati', 'Long', 'Elev'].
df_tmax pd.DataFrame — Temperatura máxima diaria (°C).
df_tmin pd.DataFrame — Temperatura mínima diaria (°C).
output_path str — Ruta de salida (ej. TxtInOut/tmp1.tmp).

Returns

None. Escribe el archivo .tmp en output_path.

function edit_file_cio
from pyhydra.modeling.hydrology.swat import edit_file_cio

Edita el file.cio de SWAT+ para establecer el periodo de simulación (IYR y NBYR).

Parámetros

Nombre Tipo Defecto Descripción
file_cio_path str — Ruta al file.cio.
start_year int — Primer año de simulación.
end_year int — Último año de simulación.

Returns

None. Modifica el archivo en lugar.

Ejemplo

from pyhydra.modeling.hydrology.swat import edit_file_cio, run_swat
edit_file_cio('TxtInOut/file.cio', start_year=2000, end_year=2020)
ret = run_swat('TxtInOut/', swat_exe='./swat_rev60_64rel.exe')
print("SWAT+ exitoso" if ret == 0 else f"Error: {ret}")
function run_swat
from pyhydra.modeling.hydrology.swat import run_swat

Ejecuta el binario de SWAT+ en el directorio del modelo.

Parámetros

Nombre Tipo Defecto Descripción
model_dir str — Directorio con los archivos TxtInOut de SWAT+.
swat_exe str — Ruta al ejecutable SWAT+.
timeout int 3600 Tiempo máximo de ejecución en segundos.

Returns

Código de retorno del proceso (0 = éxito).

function modify_unsteady_file
from pyhydra.modeling.hydraulic.hec_ras import modify_unsteady_file

Escribe un hietograma o hidrograma en un archivo de flujo no estacionario de HEC-RAS (.u##). Actualiza los datos de flujo para cada condición de contorno.

Dependencia: Requiere HEC-RAS 6.x (Windows). Para ejecución automática: pip install rascontrol.

Parámetros

Nombre Tipo Defecto Descripción
path_project str — Directorio del proyecto.
name_project str — Nombre del proyecto.
file_number int — Número del archivo de flujo (ej. 1 → '.u01').
rainfall_plan_name int — Identificador entero del nuevo plan.
flow_series pd.DataFrame — DataFrame con índice datetime y una columna por condición de contorno.
bc_pathnames list[str] — Rutas DSS identificando cada condición de contorno.

Returns

None. Escribe los datos de flujo en el archivo .u## indicado.

Ejemplo

from pyhydra.modeling.hydraulic.hec_ras import modify_unsteady_file, modify_plan_file, modify_project_file
for i, Q_df in enumerate(hidrogramas):
    modify_unsteady_file('./proyecto/', 'cuenca', file_number=i+1,
                         rainfall_plan_name=i+1, flow_series=Q_df,
                         bc_pathnames=['/CUENCA/CAUDAL//1DAY/RUN:1/'])
    modify_plan_file('./proyecto/', 'cuenca', plan_number=1, new_flow_number=i+1)
function modify_plan_file
from pyhydra.modeling.hydraulic.hec_ras import modify_plan_file

Modifica un archivo de plan HEC-RAS (.p##) para referenciar un archivo de flujo diferente, permitiendo automatizar múltiples escenarios.

Parámetros

Nombre Tipo Defecto Descripción
path_project str — Directorio del proyecto.
name_project str — Nombre del proyecto.
plan_number int — Número del plan a modificar.
new_flow_number int — Número del nuevo archivo de flujo.

Returns

None. Modifica el archivo .p## en disco.

function modify_project_file
from pyhydra.modeling.hydraulic.hec_ras import modify_project_file

Establece el plan activo en el archivo de proyecto HEC-RAS (.prj). Necesario antes de lanzar una ejecución automática cuando se alternan planes.

Parámetros

Nombre Tipo Defecto Descripción
path_project str — Directorio del proyecto.
name_project str — Nombre del proyecto.
plan_number int — Número del plan original.
rainfall_plan_name int — Número del nuevo plan a activar.

Returns

None. Modifica el archivo .prj en disco.

function create_flow_series
from pyhydra.modeling.hydraulic.hec_ras import create_flow_series

Suaviza una serie de caudal con un máximo rodante. Útil para preparar series de condición de contorno en HEC-RAS donde los picos abruptos generan inestabilidades numéricas.

Parámetros

Nombre Tipo Defecto Descripción
df pd.DataFrame — DataFrame con la serie de caudal.
col str — Nombre de la columna a procesar.
window int 5 Tamaño de ventana del máximo rodante.

Returns

pd.Series con la serie suavizada.

Ejemplo

from pyhydra.modeling.hydraulic.hec_ras import create_flow_series
Q_smooth = create_flow_series(df_sim, col='Q_outlet', window=5)
function run_hec_ras
from pyhydra.modeling.hydraulic.hec_ras import run_hec_ras

Abre y ejecuta HEC-RAS mediante la interfaz COM rascontrol (solo Windows). Abre el proyecto, lanza el cálculo, espera la finalización y cierra el proceso.

Dependencia: Solo Windows. Requiere HEC-RAS 6.x y rascontrol instalado (pip install rascontrol).

Parámetros

Nombre Tipo Defecto Descripción
path_project str — Directorio del proyecto.
name_project str — Nombre del proyecto (sin extensión).
ras_version int 641 Código entero de versión (ej. 641 = v6.4.1).

Returns

None. Lanza RuntimeError si rascontrol no puede conectarse o la simulación falla.

Ejemplo

from pyhydra.modeling.hydraulic.hec_ras import (
    modify_project_file, modify_plan_file, run_hec_ras
)
for i, plan in enumerate(plans):
    modify_project_file(proj_dir, 'modelo', plan_number=1, rainfall_plan_name=i+1)
    run_hec_ras(proj_dir, 'modelo', ras_version=641)
function setup_sfincs_model
from pyhydra.modeling.hydraulic.sfincs import setup_sfincs_model

Configura un modelo SFINCS para una cuenca a partir de un DEM. Construye la rejilla desde el DEM recortado a la cuenca, configura puntos fuente de caudal, y fija el periodo de simulación.

Dependencia: Requiere: pip install hydromt_sfincs rasterio geopandas

Parámetros

Nombre Tipo Defecto Descripción
basin_geom GeoDataFrame — GeoDataFrame (fila única) con el polígono de la cuenca.
dem_path str — Ruta al DEM GeoTIFF de entrada.
output_dir str — Directorio raíz para los archivos del modelo SFINCS.
discharge_series pd.DataFrame — DataFrame con índice datetime y una columna por punto fuente (m³/s).
src_points GeoDataFrame — Geometrías de los puntos fuente de caudal.
crs int 32630 Código EPSG del CRS del modelo.
resolution float 100.0 Resolución de la rejilla en metros.
manning float 0.04 Rugosidad de Manning uniforme.
tref/tstart/tstop str — Periodo de simulación en formato 'YYYYMMDD HHMMSS'.

Returns

SfincsModel configurado (no escrito — llamar mod.write() para persistir).

Ejemplo

from pyhydra.modeling.hydraulic.sfincs import setup_sfincs_model, run_sfincs
mod = setup_sfincs_model(
    basin_geom=basin_gdf,
    dem_path="dem.tif",
    output_dir="sfincs_run/",
    discharge_series=Q_df,
    src_points=src_gdf,
)
mod.write()
run_sfincs("sfincs_run/", sfincs_exe="./sfincs")
function write_manning_wl_boundary
from pyhydra.modeling.hydraulic.sfincs import write_manning_wl_boundary

Añade una condición de contorno de nivel del agua (profundidad normal de Manning) en el borde aguas abajo de un directorio SFINCS existente. Modifica sfincs.msk, escribe sfincs.bnd y sfincs.bzs, y actualiza sfincs.inp.

Parámetros

Nombre Tipo Defecto Descripción
model_dir str — Directorio raíz de la ejecución SFINCS (contiene sfincs.inp).
discharge_series pd.DataFrame — DataFrame con índice datetime y una columna Q (m³/s).
ch_w float — Anchura del canal (m).
ch_zb float — Elevación del fondo del canal aguas abajo (m).
mann_n float 0.035 Manning's n del canal.
slope float 2e-4 Pendiente longitudinal del fondo (m/m).
tref str — Tiempo de referencia 'YYYYMMDD HHMMSS'.

Returns

None. Archivos modificados/escritos en model_dir.

Ejemplo

from pyhydra.modeling.hydraulic.sfincs import setup_sfincs_model, write_manning_wl_boundary, run_sfincs
mod = setup_sfincs_model(basin_gdf, "dem.tif", "sfincs_run/", Q_df, src_gdf)
mod.write()
write_manning_wl_boundary("sfincs_run/", discharge_series=Q_df, ch_w=50, ch_zb=2.5, tref="20000101 000000")
ret = run_sfincs("sfincs_run/", sfincs_exe="./sfincs")
function run_sfincs
from pyhydra.modeling.hydraulic.sfincs import run_sfincs

Ejecuta el binario SFINCS.

Parámetros

Nombre Tipo Defecto Descripción
model_dir str — Directorio con los archivos de entrada SFINCS.
sfincs_exe str — Ruta al ejecutable SFINCS.
timeout int 7200 Tiempo máximo de ejecución en segundos.

Returns

Código de retorno del proceso (0 = éxito).

function generate_manning_combinations
from pyhydra.modeling.hydraulic.sensitivity import generate_manning_combinations

Ajusta distribuciones a valores de Manning por uso del suelo y genera combinaciones Monte Carlo para análisis de sensibilidad.

Parámetros

Nombre Tipo Defecto Descripción
manning_dist_csv str — Ruta al CSV con valores n por tipo de uso del suelo.
n_samples int 1000 Número de combinaciones a generar.
mc_size int 10000 Muestra MC intermedia antes del muestreo sin reemplazo.
seed int | None None Semilla aleatoria.

Returns

pd.DataFrame de forma (n_samples, n_usos_suelo) con combinaciones de n de Manning.

Ejemplo

from pyhydra.modeling.hydraulic.sensitivity import (
    generate_manning_combinations, load_flood_ensemble, manning_flood_regression
)
combs = generate_manning_combinations("manning_dist.csv", n_samples=500)
ensemble = load_flood_ensemble("./resultados_sfincs/")
df_reg = manning_flood_regression(ensemble, manning_ensemble)
function load_flood_ensemble
from pyhydra.modeling.hydraulic.sensitivity import load_flood_ensemble

Carga mapas de inundación GeoTIFF en un xarray DataArray ordenado numéricamente. Corrige el bug de ordenación lexicográfica del glob.

Parámetros

Nombre Tipo Defecto Descripción
results_dir str — Directorio con GeoTIFF de resultados.
pattern str "hamax_sim_*.tif" Patrón glob.
threshold float 0.05 Umbral de profundidad (m) para definir celda inundada.

Returns

xr.DataArray de forma (n_sims, y, x) con dimensión simulation.

Ejemplo

from pyhydra.modeling.hydraulic.sensitivity import load_flood_ensemble, build_manning_ensemble
flood = load_flood_ensemble("./sfincs_runs/", pattern="hamax_sim_*.tif", threshold=0.05)
manning = build_manning_ensemble("usos_suelo.tif", combinations_dir="./manning_combinations/")
function build_manning_ensemble
from pyhydra.modeling.hydraulic.sensitivity import build_manning_ensemble

Construye un DataArray de rugosidad de Manning reclasificando el raster de usos del suelo para cada simulación.

Parámetros

Nombre Tipo Defecto Descripción
raster_path str — Raster de usos del suelo.
combinations_dir str — Directorio con CSVs de combinaciones.
simulation_numbers list[int] | None None Números de simulación. Si None usa todos los CSVs encontrados.

Returns

xr.DataArray de forma (n_sims, y, x).

Ejemplo

from pyhydra.modeling.hydraulic.sensitivity import build_manning_ensemble
manning = build_manning_ensemble(
    raster_path="usos_suelo.tif",
    combinations_dir="./manning_combinations/",
    simulation_numbers=list(range(500)),
)  # shape (500, nrows, ncols)
function manning_flood_regression
from pyhydra.modeling.hydraulic.sensitivity import manning_flood_regression

Calcula pares Manning–métrica de inundación por simulación para análisis de regresión. Extrae n medio y mediano (restringido a celdas mojadas), junto con profundidad media y área inundada.

Parámetros

Nombre Tipo Defecto Descripción
flood_ensemble xr.DataArray — Ensemble de inundación (n_sims, y, x).
manning_ensemble xr.DataArray — Ensemble de rugosidad (n_sims, y, x).
cell_area_m2 float 25.0 Área de celda en m².
threshold float 0.05 Umbral de profundidad para celda mojada (m).

Returns

pd.DataFrame indexado por simulación con columnas: 'manning_mean', 'manning_median', 'depth_mean', 'depth_median', 'flooded_area_m2'.

function filter_anomalous_simulations
from pyhydra.modeling.hydraulic.sensitivity import filter_anomalous_simulations

Elimina simulaciones con valores extremos (Z-score MAD > z_threshold) de uno o varios DataFrames, manteniendo el mismo conjunto de simulaciones en todos ellos.

Parámetros

Nombre Tipo Defecto Descripción
*results pd.DataFrame — Uno o más DataFrames indexados por número de simulación.
metrics list[str] | None None Columnas a evaluar. Si None usa todas las numéricas.
z_threshold float 3.0 Umbral Z-score normalizado por MAD.

Returns

Tupla (mask_booleana, DataFrame_filtrado).

Ejemplo

from pyhydra.modeling.hydraulic.sensitivity import (
    load_flood_ensemble, build_manning_ensemble,
    manning_flood_regression, filter_anomalous_simulations
)
flood = load_flood_ensemble("./sfincs_runs/")
manning = build_manning_ensemble("usos_suelo.tif", "./combinations/")
df_reg = manning_flood_regression(flood, manning)
mask, df_clean = filter_anomalous_simulations(df_reg, z_threshold=3.0)
print(f"Eliminadas {(~mask).sum()} simulaciones anómalas")
function flooded_area
from pyhydra.modeling.hydraulic.sensitivity import flooded_area

Calcula el área inundada (m²) por simulación aplicando un umbral de profundidad.

Parámetros

Nombre Tipo Defecto Descripción
ensemble xr.DataArray — Ensemble de inundación (n_sims, y, x).
cell_area_m2 float 25.0 Área de celda en m².
threshold float 0.05 Umbral de profundidad (m).

Returns

ndarray 1D de longitud n_sims con área inundada en m².

Ejemplo

from pyhydra.modeling.hydraulic.sensitivity import load_flood_ensemble, flooded_area, spatial_stats
flood = load_flood_ensemble("./sfincs_runs/")
areas = flooded_area(flood, cell_area_m2=100.0, threshold=0.05)
print(f"Área inundada media: {areas.mean()/1e6:.2f} km²")
function spatial_stats
from pyhydra.modeling.hydraulic.sensitivity import spatial_stats

Calcula media, mediana, desviación estándar y máximo espaciales por simulación. Reduce simultáneamente sobre (x, y) para evitar sesgo con NaN.

Parámetros

Nombre Tipo Defecto Descripción
ensemble xr.DataArray — Ensemble (n_sims, y, x).

Returns

pd.DataFrame con índice = números de simulación y columnas ['mean', 'median', 'std', 'max'].

Ejemplo

from pyhydra.modeling.hydraulic.sensitivity import load_flood_ensemble, spatial_stats
flood = load_flood_ensemble("./sfincs_runs/")
df = spatial_stats(flood)
print(df.describe())  # media y dispersión de calados por simulación