Quick Start

This guide will get you running your first HydroRaVENS model.

Prepare Your Data

HydroRaVENS requires daily time series data in CSV format. Required and optional columns:

Input CSV Columns

Column Name

Units

When required

Date

YYYY-MM-DD

Always; must be continuous daily data with no gaps

Precipitation [mm/day]

mm/day

Always

Discharge [m^3/s]

m³/s

Always; used for scoring

Mean Temperature [C]

°C

Snowpack and frozen-ground modules

Minimum Temperature [C]

°C

DTR-based frozen-ground decay; ThorntwaiteChang2019 ET

Maximum Temperature [C]

°C

DTR-based frozen-ground decay; ThorntwaiteChang2019 ET

Photoperiod [hr]

hours

ThorntwaiteChang2019 ET method

Evapotranspiration [mm/day]

mm/day

datafile ET method

Example input (first few rows):

Date,Precipitation [mm/day],Discharge [m^3/s],Mean Temperature [C],Minimum Temperature [C],Maximum Temperature [C],Photoperiod [hr]
2010-01-01,0.0,15.2,-2.5,-6.1,1.2,9.1
2010-01-02,2.1,16.8,-1.3,-4.8,2.3,9.2
2010-01-03,0.5,15.9,0.2,-3.1,3.6,9.3

Create a Configuration File

HydroRaVENS is configured through a YAML file (config.yml). The example below uses a three-reservoir structure (soil → intermediate → deep), which is a recommended starting point for temperate catchments. See Configuration Reference for all available options and Calibration for guidance on choosing a model structure.

timeseries:
    datafile: input_data.csv

initial_conditions:
    water_reservoir_effective_depths__mm:
        - 50       # Soil reservoir
        - 500      # Intermediate (shallow GW / outwash)
        - 10000    # Deep groundwater
    snowpack__mm_SWE: 0

catchment:
    drainage_basin_area__km2: 3800
    evapotranspiration_method: ThorntwaiteChang2019
    water_year_start_month: 10

general:
    spin_up_cycles: null          # auto: ceil(τ_max / record_length)
    enforce_water_balance: global

reservoirs:
    e_folding_residence_times__days:
        - 200      # Soil (placeholder; calibrate)
        - 30       # Intermediate (placeholder; calibrate)
        - 50000    # Deep GW (placeholder; calibrate)
    exfiltration_fractions:
        - 0.5      # Soil: fraction to stream vs. percolating deeper
        - 0.5      # Intermediate: fraction to stream vs. recharging deep
        - 1.0      # Deep: all exits as baseflow
    maximum_effective_depths__mm:
        - .inf
        - .inf
        - .inf
    recession_exponents:
        - 3.0      # Soil: nonlinear (calibrate; typical 2–6)
        - 2.2      # Intermediate: fix near B–N lower-envelope value
        - 1.0      # Deep: linear (fix)

snowmelt:
    PDD_melt_factor: 2.0          # mm SWE °C⁻¹ day⁻¹ (calibrate)
    snow_insulation_k: 0.0
    fdd_threshold: .inf           # disabled; set a finite value to enable

modules:
    snowpack:          true
    frozen_ground:     false
    rain_on_snow:      true
    direct_runoff:     false
    dtr_fgi_decay:     false
    et_water_stress:   false
    et_reservoir_draw: true

Run the Model

Using the Python API:

import hydroravens

model = hydroravens.Buckets()
model.initialize('config.yml')
model.run()
model.compute_NSE(verbose=True)
model.plot()

Using the command-line interface:

hydroravens -y config.yml

Adjust Parameters

Model performance depends on the reservoir parameters:

Residence times (e_folding_residence_times__days)

Larger values = slower response. Order of magnitude ranges:

  • Soil zone: days to weeks (fast lateral drainage)

  • Intermediate (shallow GW / outwash): weeks to months

  • Deep groundwater: years to centuries

Use suggest_priors() to estimate data-driven starting points from the observed discharge record before manual adjustment.

Exfiltration fractions (exfiltration_fractions)

Fraction of each reservoir’s drainage going directly to the river.

  • Higher = more direct runoff from that reservoir

  • Lower = more infiltration to the next-deeper reservoir

  • Bottom reservoir must be 1.0 for mass conservation

Recession exponents (recession_exponents)

Controls the nonlinearity of storage–discharge in each reservoir. \(b = 1\) is a standard linear reservoir; \(b > 1\) gives a concave (faster-draining-when-full) response. Use BrutsaertNieber to estimate the appropriate exponent from observed streamflow recession.

  • Soil zone: calibrate (typical 2–6; higher values for tile-drained basins)

  • Intermediate: fix at Brutsaert–Nieber lower-envelope estimate (~2.0–2.5)

  • Deep: fix at 1.0 (linear)

Water balance closure (enforce_water_balance)

'global' uses a single ET scaling factor over the full record and is recommended when comparing model structures by AIC. 'water-year' fits a separate multiplier each year, which can overfit interannual ET variability.

Next Steps