← Volver al módulo Datos

Fuentes de datos

API Reference

Clases

class OGIMETDownloader
from pyhydra.data_sources.rainfall.ogimet import OGIMETDownloader

Widget Jupyter interactivo para seleccionar estaciones SYNOP en un mapa y descargar series temporales con un solo clic.

Parámetros del constructor

Nombre Tipo Defecto Descripción
stations_csv str | None None Ruta al CSV con metadatos de estaciones. Si es None usa el CSV incluido en el paquete.
output_dir str "." Directorio de salida para los archivos descargados.

Métodos

display display() → None

Muestra el widget completo (mapa ipyleaflet + controles de fecha + botones) en el notebook.

Ejemplo

from pyhydra.data_sources.rainfall.ogimet import OGIMETDownloader
widget = OGIMETDownloader(output_dir="./datos_sinopticos")
widget.display()
class AEMETDownloader
from pyhydra.data_sources.rainfall.aemet import AEMETDownloader

Widget interactivo (ipywidgets) para descargar series pluviométricas de la API REST de AEMET OpenData. Permite seleccionar estaciones de un shapefile, definir el rango temporal y lanzar la descarga directamente desde un notebook.

Parámetros del constructor

Nombre Tipo Defecto Descripción
netcdf_folder str — Carpeta donde se guardarán los NetCDF descargados.
stations_shapefile str | None None Shapefile con las estaciones AEMET. Si None, usa la red completa.

Ejemplo

from pyhydra.data_sources.rainfall.aemet import AEMETDownloader
widget = AEMETDownloader(netcdf_folder='./aemet_data/', stations_shapefile='estaciones.shp')
widget  # Displays the interactive widget in Jupyter
class AemetCSVLoader
from pyhydra.data_sources.rainfall.aemet import AemetCSVLoader

Carga y valida la calidad de series pluviométricas a partir de los CSV exportados por el portal web de AEMET. Aplica controles de calidad estándar: rangos físicos, valores sospechosos y detección de rachas de ceros.

Métodos

load_station_data

Carga metadatos de la estación desde un CSV AEMET.

Parámetro Tipo Descripción
csv_path str Ruta al archivo CSV.

Returns: dict con nombre, coordenadas y altitud de la estación.

load_series_data

Carga la serie temporal de precipitación del CSV.

Parámetro Tipo Descripción
csv_path str Ruta al archivo CSV.

Returns: pd.Series indexada por fecha con precipitación diaria en mm.

analyze_series_quality

Evalúa la calidad de una serie: período, datos faltantes, rachas de ceros y valores atípicos.

Parámetro Tipo Descripción
series pd.Series Serie de precipitación diaria.

Returns: dict con métricas de calidad: missing_pct, zero_runs, outliers, etc.

Ejemplo

from pyhydra.data_sources.rainfall.aemet import AemetCSVLoader
loader = AemetCSVLoader()
meta = loader.load_station_data('aemet_2868.csv')
precip = loader.load_series_data('aemet_2868.csv')
quality = loader.analyze_series_quality(precip)
class GPMDownloader
from pyhydra.data_sources.rainfall.gpm import GPMDownloader

Descarga y extrae datos GPM IMERG desde NASA Earthdata. Soporta resolución horaria, diaria y mensual. Puede extraer series puntuales o subconjuntos espaciales.

Dependencia: Requiere: pip install earthaccess tqdm xarray y credenciales NASA Earthdata.

Métodos

set_region set_region(points=None, lat_bounds=None, lon_bounds=None) → None

Define la región espacial de descarga.

Parámetro Tipo Descripción
points list[tuple] Lista de tuplas (lat, lon) para extracción puntual.
lat_bounds tuple[float, float] (lat_min, lat_max) para región rectangular.
lon_bounds tuple[float, float] (lon_min, lon_max) para región rectangular.
search search(start_date, end_date, resolution='hourly') → list

Busca los gránulos disponibles en el rango temporal y región definida.

Parámetro Tipo Descripción
start_date str Fecha inicio 'YYYY-MM-DD'.
end_date str Fecha fin.
resolution str 'hourly', 'daily', o 'monthly'.

Returns: Lista de gránulos earthaccess.

open_dataset open_dataset(results, variable='precipitation', ...) → pd.DataFrame | None

Descarga, procesa y guarda los gránulos GPM.

Parámetro Tipo Descripción
results list Gránulos de search().
variable str Variable a extraer.
output_folder str Directorio de salida.

Returns: DataFrame de series temporales si se extraen puntos, None si se guardan NetCDF.

Ejemplo

from pyhydra.data_sources.rainfall.gpm import GPMDownloader
gpm = GPMDownloader()
gpm.set_region(lat_bounds=(36, 44), lon_bounds=(-10, 4))
results = gpm.search("2020-01-01", "2020-12-31", resolution="daily")
gpm.open_dataset(results, output_folder="./gpm_data")
class PERSSIANDownloader
from pyhydra.data_sources.rainfall.persiann import PERSSIANDownloader

Descarga datos PERSIANN-CCS desde el servidor FTP de UCI. Resolución 0.04° global (60°S–60°N). Soporta modo puntual y modo área.

Parámetros del constructor

Nombre Tipo Defecto Descripción
lon float | list[float] | None None Longitud(es) para extracción puntual.
lat float | list[float] | None None Latitud(es) para extracción puntual.
lon_min/lon_max float — Límites de longitud para modo área.
lat_min/lat_max float — Límites de latitud para modo área.
path_output str "output" Directorio de salida.
max_workers int 2 Hilos FTP paralelos.

Métodos

download_daily download_daily(start_date, end_date) → pd.Series | None

Descarga acumulados diarios. En modo puntual devuelve Series; en modo área guarda NetCDF.

download_hourly download_hourly(start_date, end_date) → pd.Series | None

Descarga datos horarios.

Ejemplo

from pyhydra.data_sources.rainfall.persiann import PERSSIANDownloader
dl = PERSSIANDownloader(lon=-3.7, lat=40.4, path_output="./persiann")
series = dl.download_daily("2015-01-01", "2015-12-31")

Funciones

function download_synop
from pyhydra.data_sources.rainfall.ogimet import download_synop

Descarga datos SYNOP diarios de una estación desde ogimet.com. Procesa la respuesta HTML y devuelve un DataFrame con variables meteorológicas con índice multi-nivel.

Parámetros

Nombre Tipo Defecto Descripción
station_id int | str — Código SYNOP numérico (ej. 8023).
start_date str | datetime — Fecha de inicio.
end_date str | datetime — Fecha de fin.
progress IntProgress | None None Widget ipywidgets para mostrar progreso.
cancel_flag dict | None None Dict con clave "cancel": True para interrumpir desde otro hilo.

Returns

pd.DataFrame con columnas multi-nivel, o None si la descarga falla.

Ejemplo

from pyhydra.data_sources.rainfall.ogimet import download_synop
df_raw = download_synop(8023, "2020-01-01", "2020-12-31")
function process_all_meteorological_variables
from pyhydra.data_sources.rainfall.ogimet import process_all_meteorological_variables

Convierte un DataFrame bruto de OGIMET a una serie diaria limpia. Convierte direcciones de viento, gestiona precipitación traza ('ip') y agrega observaciones 3-horarias a diarias.

Parámetros

Nombre Tipo Defecto Descripción
df pd.DataFrame — DataFrame bruto de download_synop().

Returns

pd.DataFrame con columnas limpias y una fila por día.

Ejemplo

from pyhydra.data_sources.rainfall.ogimet import process_all_meteorological_variables
daily = process_all_meteorological_variables(df_raw)
function download_aemet_daily_data
from pyhydra.data_sources.rainfall.aemet import download_aemet_daily_data

Descarga datos climatológicos diarios de todas las estaciones AEMET mediante la API OpenData. Almacena los resultados en NetCDF particionados por chunk temporal.

Dependencia: Requiere API key gratuita en https://opendata.aemet.es

Parámetros

Nombre Tipo Defecto Descripción
path_output str — Directorio para los archivos NetCDF.
api_key str — Clave de API AEMET OpenData.
start_date_str str — Fecha inicio '%Y-%m-%dT%H:%M:%S[UTC]'.
end_date_str str — Fecha fin, mismo formato.
interval_days int 15 Chunk en días (límite API AEMET = 15).

Returns

None. Archivos escritos en path_output.

Ejemplo

from pyhydra.data_sources.rainfall.aemet import download_aemet_daily_data
download_aemet_daily_data(
    path_output="./aemet/",
    api_key="tu_api_key",
    start_date_str="2000-01-01T00:00:00UTC",
    end_date_str="2023-12-31T00:00:00UTC",
)
function download_era5
from pyhydra.data_sources.rainfall.era5 import download_era5

Descarga datos ERA5 del Copernicus CDS para un rango de años y meses. Soporta descarga paralela por hilo y guarda archivos NetCDF combinados.

Dependencia: Requiere: pip install cdsapi y fichero ~/.cdsapirc con credenciales CDS.

Parámetros

Nombre Tipo Defecto Descripción
folder_out str — Directorio de salida.
api_key str — Clave API de Copernicus CDS.
url str — URL del CDS API.
area list[float] — Bounding box [N, W, S, E] en grados.
variables_list list[str] — Lista de nombres de variables CDS.
years list[int] | range — Años a descargar.
months range range(1, 13) Meses a descargar.
max_workers int 5 Hilos de descarga paralela.
file_format str "netcdf" Formato de salida: 'netcdf' o 'grib'.
frequency str "hourly" 'hourly' o 'monthly'.

Returns

None. Archivos NetCDF escritos en folder_out.

Ejemplo

from pyhydra.data_sources.rainfall.era5 import download_era5
download_era5(
    folder_out="./era5/",
    api_key="tu_uid:tu_api_key",
    url="https://cds.climate.copernicus.eu/api/v2",
    area=[44, -10, 35, 5],
    variables_list=["total_precipitation", "2m_temperature"],
    years=range(2000, 2024),
    frequency="monthly",
)
function download_glofas
from pyhydra.data_sources.river_discharge.glofas import download_glofas

Descarga datos de caudal GloFAS (reanálisis, repronóstico u operacional) desde el Copernicus EWDS. Envía una única petición CDS para todos los años y meses seleccionados.

Dependencia: Requiere: pip install cdsapi y cuenta en https://ewds.climate.copernicus.eu

Parámetros

Nombre Tipo Defecto Descripción
area list[float] — Bounding box [Norte, Oeste, Sur, Este] en grados decimales.
years list[int] | range — Años a descargar.
output_dir str — Directorio de salida.
dataset str "cems-glofas-historical" 'cems-glofas-historical', 'cems-glofas-reforecast', o 'cems-glofas-forecast'.
system_version str "version_4_0" Versión del sistema GloFAS.
months list[int] | None None Lista de meses 1–12. Por defecto todos.
api_key str | None None Clave CDS. Si None lee de ~/.cdsapirc.

Returns

Lista de rutas a los archivos descargados.

Ejemplo

from pyhydra.data_sources.river_discharge.glofas import download_glofas
rutas = download_glofas(
    area=[44, -10, 35, 5],
    years=[2000, 2001, 2002],
    output_dir="./glofas_data",
)
function download_glofas_by_year
from pyhydra.data_sources.river_discharge.glofas import download_glofas_by_year

Igual que download_glofas pero envía una petición CDS por año, evitando peticiones muy grandes que pueden agotar el tiempo del servidor.

Parámetros

Nombre Tipo Defecto Descripción
area list[float] — Bounding box [N, O, S, E].
years list[int] | range — Años a descargar (uno por archivo).
output_dir str — Directorio de salida.
dataset str "cems-glofas-historical" Dataset CDS.

Returns

Lista de rutas (una por año).

Ejemplo

from pyhydra.data_sources.river_discharge.glofas import download_glofas_by_year
# Descarga un NetCDF por año (útil para series largas >10 años)
rutas = download_glofas_by_year(
    area=[44, -10, 35, 5],
    years=range(1980, 2024),
    output_dir="./glofas_data",
)
function read_glofas_nc
from pyhydra.data_sources.river_discharge.glofas import read_glofas_nc

Extrae una serie temporal de caudal de un archivo NetCDF de GloFAS en un punto geográfico.

Parámetros

Nombre Tipo Defecto Descripción
filepath str — Ruta al archivo .nc de GloFAS.
lat float — Latitud del punto (grados decimales).
lon float — Longitud del punto.
variable str "dis24" Nombre de la variable NetCDF de caudal.

Returns

pd.DataFrame con columnas 'date' y 'discharge' (m³/s).

Ejemplo

from pyhydra.data_sources.river_discharge.glofas import download_glofas_by_year, read_glofas_nc
rutas = download_glofas_by_year(area=[44, -10, 35, 5], years=range(2000, 2023), output_dir="./glofas/")
df = read_glofas_nc(rutas[0], lat=43.35, lon=-3.80)
print(df.head())
function read_grdc
from pyhydra.data_sources.river_discharge.grdc import read_grdc

Parsea un archivo GRDC diario o mensual (.day / .mon) a un DataFrame ordenado. El formato GRDC usa valores centinela (-999) para datos faltantes.

Dependencia: Los datos GRDC se solicitan manualmente en https://portal.grdc.bafg.de — no hay API de descarga.

Parámetros

Nombre Tipo Defecto Descripción
filepath str — Ruta al archivo .day o .mon de GRDC.

Returns

pd.DataFrame con columnas 'date' (Timestamp) y 'discharge' (m³/s, NaN donde faltan datos).

Ejemplo

from pyhydra.data_sources.river_discharge.grdc import read_grdc, analyze_grdc_quality
df = read_grdc("6335020_Q_Day.Cmd.day")
stats = analyze_grdc_quality(df)
function read_grdc_metadata
from pyhydra.data_sources.river_discharge.grdc import read_grdc_metadata

Extrae metadatos de estación del cabecero del archivo GRDC (nombre, río, país, lat/lon, cuenca).

Parámetros

Nombre Tipo Defecto Descripción
filepath str — Ruta al archivo GRDC.

Returns

Dict con claves 'station', 'river', 'country', 'latitude', 'longitude', 'altitude_m', 'catchment_area_km2', 'grdc_no'.

Ejemplo

from pyhydra.data_sources.river_discharge.grdc import read_grdc, read_grdc_metadata
meta = read_grdc_metadata("6335020_Q_Day.Cmd.day")
print(meta['station'], meta['latitude'], meta['longitude'])
function read_grdc_folder
from pyhydra.data_sources.river_discharge.grdc import read_grdc_folder

Lee todos los archivos GRDC de una carpeta que coincidan con un patrón glob.

Parámetros

Nombre Tipo Defecto Descripción
folder str — Directorio con archivos GRDC.
pattern str "*.day" Patrón glob. Usar '*.mon' para mensual.

Returns

Dict nombre_archivo → DataFrame.

Ejemplo

from pyhydra.data_sources.river_discharge.grdc import read_grdc_folder
series_dict = read_grdc_folder("./grdc_data/", pattern="*.day")
# {'6335020_Q_Day.Cmd.day': pd.DataFrame(...), ...}
function analyze_grdc_quality
from pyhydra.data_sources.river_discharge.grdc import analyze_grdc_quality

Estadísticas básicas de calidad de una serie GRDC: fecha inicio/fin, días totales, % faltantes, media y máximo.

Parámetros

Nombre Tipo Defecto Descripción
df pd.DataFrame — Salida de read_grdc().

Returns

Dict con claves 'start', 'end', 'n_days', 'missing_pct', 'mean_m3s', 'max_m3s'.

function download_usgs
from pyhydra.data_sources.river_discharge.usgs import download_usgs

Descarga caudal diario medio de una o más estaciones USGS NWIS (sin registro requerido). Los valores de caudal se convierten de ft³/s a m³/s por defecto.

Parámetros

Nombre Tipo Defecto Descripción
site_no str | list[str] — Número(s) de estación USGS (ej. '08279500').
start_date str — Fecha inicio 'YYYY-MM-DD'.
end_date str — Fecha fin.
units str "metric" 'metric' (m³/s) o 'imperial' (ft³/s).
max_retries int 3 Reintentos por petición fallida.

Returns

pd.DataFrame con DatetimeIndex y columnas 'Q_<site_no>' por estación.

Ejemplo

from pyhydra.data_sources.river_discharge.usgs import download_usgs, search_usgs_sites
# Buscar estaciones en el río Colorado
estaciones = search_usgs_sites(bbox=(-115, 31, -110, 37))
# Descargar caudal
df = download_usgs(["09380000", "09163500"], "2010-01-01", "2020-12-31")
function get_usgs_site_info
from pyhydra.data_sources.river_discharge.usgs import get_usgs_site_info

Obtiene metadatos de una estación USGS: nombre, coordenadas, área de cuenca y altitud.

Parámetros

Nombre Tipo Defecto Descripción
site_no str — Número de estación USGS (ej. '08279500').

Returns

pd.DataFrame con columnas site_no, station_nm, dec_lat_va, dec_long_va, drain_area_va, drain_area_km2.

Ejemplo

from pyhydra.data_sources.river_discharge.usgs import get_usgs_site_info
info = get_usgs_site_info("08279500")  # Rio Grande at Embudo, NM
print(info.T)
function search_usgs_sites
from pyhydra.data_sources.river_discharge.usgs import search_usgs_sites

Encuentra estaciones USGS de caudal dentro de un bounding box.

Parámetros

Nombre Tipo Defecto Descripción
bbox tuple[float, float, float, float] — (west, south, east, north) en grados decimales.
parameter_cd str "00060" Código de parámetro NWIS. '00060' = caudal.

Returns

pd.DataFrame con columnas 'site_no', 'station_nm', 'dec_lat_va', 'dec_long_va', 'drain_area_km2'.

Ejemplo

from pyhydra.data_sources.river_discharge.usgs import search_usgs_sites
# Buscar estaciones de caudal en la Península Ibérica
estaciones = search_usgs_sites(bbox=(-9, 36, 3, 44))
print(estaciones[['site_no', 'station_nm', 'dec_lat_va', 'dec_long_va']].head())
function download_soilgrids
from pyhydra.data_sources.soils.soilgrids import download_soilgrids

Descarga los GeoTIFF de arena/limo/arcilla de SoilGrids 2017 (ISRIC, 250 m) para 7 profundidades de suelo. Total 21 capas.

Parámetros

Nombre Tipo Defecto Descripción
output_dir str — Directorio de destino (se crea si no existe).
max_retries int 10 Intentos por archivo.
include_metadata bool False También descargar archivos XML y CSV de metadatos.

Returns

None. Archivos escritos en output_dir.

Ejemplo

from pyhydra.data_sources.soils.soilgrids import download_soilgrids
download_soilgrids("./soilgrids_data")
function download_CDS_CMIP6
from pyhydra.data_sources.climate_change.copernicus import download_CDS_CMIP6

Descarga proyecciones CMIP6 del Copernicus CDS con ejecución paralela por año y reintento automático en fallos transitorios.

Dependencia: Requiere: pip install cdsapi y ~/.cdsapirc con credenciales Copernicus CDS.

Parámetros

Nombre Tipo Defecto Descripción
url str — URL del CDS API.
api_key str — Clave del CDS API.
start_date str — Año de inicio (ej. '1950-01-01').
end_date str — Año de fin (ej. '2100-12-31').
temporal_resolution str — 'daily' o 'monthly'.
model str — Nombre del modelo o 'All' para todos los disponibles.
experiments list[str] — Lista de experimentos (ej. ['historical', 'ssp245', 'ssp585']).
variables list[str] — Lista de variables CDS CMIP6.
download_base_dir str — Directorio raíz de descarga.
area list[float] — Bounding box [N, W, S, E].
max_workers int 5 Hilos paralelos por modelo.
max_retries int 3 Reintentos por año.

Returns

None. Archivos descargados en download_base_dir.

function get_dataset_metadata
from pyhydra.data_sources.climate_change.esgf import get_dataset_metadata

Consulta el índice ESGF y devuelve metadatos de los datasets disponibles que coinciden con los filtros dados.

Parámetros

Nombre Tipo Defecto Descripción
filters dict — Dict de filtros ESGF, por ejemplo {'source_id': 'MPI-ESM1-2-HR', 'experiment_id': 'historical'}.
limit int 5000 Número máximo de resultados a recuperar.

Returns

pd.DataFrame con columnas: dataset_id, model, experiment, variable, variant, table, start, end.

Ejemplo

from pyhydra.data_sources.climate_change.esgf import get_dataset_metadata
df = get_dataset_metadata({'source_id': 'MPI-ESM1-2-HR', 'experiment_id': 'ssp585', 'variable_id': 'pr'})
function get_all_urls
from pyhydra.data_sources.climate_change.esgf import get_all_urls

Obtiene todas las URLs de descarga para un dataset ESGF dado su dataset_id. Devuelve tanto enlaces HTTPServer como OPeNDAP.

Parámetros

Nombre Tipo Defecto Descripción
dataset_id str — Identificador completo del dataset ESGF.

Returns

Lista de dicts con claves 'url' y 'url_type' ('HTTPServer' u 'OPeNDAP').

function get_combination_if_complete
from pyhydra.data_sources.climate_change.esgf import get_combination_if_complete

Verifica si una combinación (modelo, experimento, variante) tiene todas las variables requeridas disponibles en ESGF. Útil para filtrar combinaciones incompletas antes de descargar.

Parámetros

Nombre Tipo Defecto Descripción
model str — Identificador del modelo CMIP6.
experiment str — Experimento CMIP6 (ej. 'historical', 'ssp245').
variant str — Etiqueta de variante (ej. 'r1i1p1f1').
variables list[str] — Variables requeridas.

Returns

Lista de filas de metadata si la combinación está completa, lista vacía si falta alguna variable.

function download_file
from pyhydra.data_sources.climate_change.esgf import download_file

Descarga un archivo desde una URL HTTPServer de ESGF con reintentos y reanudación parcial.

Parámetros

Nombre Tipo Defecto Descripción
url str — URL HTTPServer del archivo a descargar.
local_path str — Ruta local de destino.
chunk_size int 1048576 Tamaño de chunk en bytes (1 MB por defecto).
max_retries int 3 Número máximo de reintentos.

Returns

True si la descarga fue exitosa, False en caso contrario.

function process_file
from pyhydra.data_sources.climate_change.esgf import process_file

Descarga (o lee vía OPeNDAP) un archivo CMIP6 desde ESGF, recorta al bounding box indicado y guarda el resultado como NetCDF en path_output.

Parámetros

Nombre Tipo Defecto Descripción
url str — URL del archivo (HTTPServer u OPeNDAP).
path_output str — Directorio de salida para el NetCDF recortado.
lat_min float — Latitud mínima del bounding box.
lat_max float — Latitud máxima.
lon_min float — Longitud mínima.
lon_max float — Longitud máxima.
url_type str "OPENDAP" 'OPENDAP' o 'HTTPServer'.

Returns

Cadena de estado: '[OK]' si éxito, '[SKIPPED]' si ya existe, '[ERROR] ...' con mensaje de error.

Ejemplo

from pyhydra.data_sources.climate_change.esgf import get_dataset_metadata, get_all_urls, process_file
df = get_dataset_metadata({'source_id': 'MPI-ESM1-2-HR', 'experiment_id': 'historical', 'variable_id': 'pr'})
urls = get_all_urls(df.iloc[0]['dataset_id'])
status = process_file(urls[0]['url'], './cmip6/', lat_min=35, lat_max=44, lon_min=-10, lon_max=5)