Skip to content

Standard Variables

Overview

The StandardVariable class defines standardized variable names used across all datasets in hydrodataset. This ensures consistency when accessing data from different hydrological datasets, even when the underlying dataset uses different naming conventions.

Purpose

Different hydrological datasets use various naming conventions for the same variables: - CAMELS-US might use "dayl" for daylight duration - CAMELS-AUS might use "solarrad_AWAP" for solar radiation - CARAVAN might use "temperature_2m_mean" for mean temperature

StandardVariable provides a unified naming system so users can request StandardVariable.TEMPERATURE_MEAN regardless of the underlying dataset.

Variable Categories

Streamflow

  • STREAMFLOW: River discharge/streamflow

Precipitation

  • PRECIPITATION: Precipitation/rainfall

Temperature

  • TEMPERATURE_MAX: Maximum air temperature
  • TEMPERATURE_MIN: Minimum air temperature
  • TEMPERATURE_MEAN: Mean air temperature

Evapotranspiration

  • POTENTIAL_EVAPOTRANSPIRATION: Potential evapotranspiration (PET)
  • EVAPOTRANSPIRATION: Actual evapotranspiration (ET/AET)
  • EVAPORATION: Evaporation from water surfaces

Radiation

  • SOLAR_RADIATION: Solar/shortwave radiation
  • SOLAR_RADIATION_MIN: Minimum solar radiation
  • SOLAR_RADIATION_MAX: Maximum solar radiation
  • THERMAL_RADIATION: Thermal/longwave radiation
  • THERMAL_RADIATION_MIN: Minimum thermal radiation
  • THERMAL_RADIATION_MAX: Maximum thermal radiation

Snow

  • SNOW_WATER_EQUIVALENT: Snow water equivalent
  • SNOW_WATER_EQUIVALENT_MIN: Minimum snow water equivalent
  • SNOW_WATER_EQUIVALENT_MAX: Maximum snow water equivalent
  • SNOW_DEPTH: Snow depth

Wind

  • WIND_SPEED: Wind speed
  • U_WIND_SPEED: U-component of wind speed
  • U_WIND_SPEED_MIN: Minimum U-component wind speed
  • U_WIND_SPEED_MAX: Maximum U-component wind speed
  • V_WIND_SPEED: V-component of wind speed
  • V_WIND_SPEED_MIN: Minimum V-component wind speed
  • V_WIND_SPEED_MAX: Maximum V-component wind speed

Atmospheric

  • VAPOR_PRESSURE: Vapor pressure
  • SPECIFIC_HUMIDITY: Specific humidity
  • RELATIVE_HUMIDITY: Relative humidity
  • SURFACE_PRESSURE: Surface atmospheric pressure
  • SURFACE_PRESSURE_MIN: Minimum surface pressure
  • SURFACE_PRESSURE_MAX: Maximum surface pressure

Soil

  • SOIL_MOISTURE: Soil moisture (general)
  • VOLUMETRIC_SOIL_WATER_LAYER1: Volumetric soil water content, layer 1
  • VOLUMETRIC_SOIL_WATER_LAYER1_MIN: Minimum soil water, layer 1
  • VOLUMETRIC_SOIL_WATER_LAYER1_MAX: Maximum soil water, layer 1
  • VOLUMETRIC_SOIL_WATER_LAYER2: Volumetric soil water content, layer 2
  • VOLUMETRIC_SOIL_WATER_LAYER2_MIN: Minimum soil water, layer 2
  • VOLUMETRIC_SOIL_WATER_LAYER2_MAX: Maximum soil water, layer 2
  • VOLUMETRIC_SOIL_WATER_LAYER3: Volumetric soil water content, layer 3
  • VOLUMETRIC_SOIL_WATER_LAYER3_MIN: Minimum soil water, layer 3
  • VOLUMETRIC_SOIL_WATER_LAYER3_MAX: Maximum soil water, layer 3
  • VOLUMETRIC_SOIL_WATER_LAYER4: Volumetric soil water content, layer 4
  • VOLUMETRIC_SOIL_WATER_LAYER4_MIN: Minimum soil water, layer 4
  • VOLUMETRIC_SOIL_WATER_LAYER4_MAX: Maximum soil water, layer 4

Daylight

  • DAYLIGHT_DURATION: Hours of daylight

Usage

Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
from hydrodataset import StandardVariable
from hydrodataset.camels_us import CamelsUs

ds = CamelsUs(data_path)

# Request data using standard variable names
timeseries = ds.read_ts_xrdataset(
    gage_id_lst=basin_ids,
    t_range=["1990-01-01", "1995-12-31"],
    var_lst=[
        StandardVariable.STREAMFLOW,
        StandardVariable.PRECIPITATION,
        StandardVariable.TEMPERATURE_MEAN
    ]
)

Using String Names

You can also use lowercase string versions of the standard variable names:

1
2
3
4
5
6
# These are equivalent
timeseries = ds.read_ts_xrdataset(
    gage_id_lst=basin_ids,
    t_range=["1990-01-01", "1995-12-31"],
    var_lst=["streamflow", "precipitation", "temperature_mean"]
)

Multiple Data Sources

Some datasets provide the same variable from multiple sources. You can specify the source:

1
2
3
4
5
6
7
8
9
# Request precipitation from ERA5-Land source instead of default
timeseries = ds.read_ts_xrdataset(
    gage_id_lst=basin_ids,
    t_range=["1990-01-01", "1995-12-31"],
    var_lst=[
        ("precipitation", "era5land"),  # Specify source
        "streamflow"  # Use default source
    ]
)

Checking Available Variables

1
2
3
# List all available standard variables for a dataset
print(ds.available_dynamic_features)
print(ds.available_static_features)

Variable Mapping Implementation

When implementing a new dataset, map StandardVariable constants to dataset-specific names:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
_dynamic_variable_mapping = {
    StandardVariable.STREAMFLOW: {
        "default_source": "observations",
        "sources": {
            "observations": {"specific_name": "q_cms", "unit": "m^3/s"},
            "simulated": {"specific_name": "q_sim", "unit": "m^3/s"},
        },
    },
    StandardVariable.PRECIPITATION: {
        "default_source": "gauge",
        "sources": {
            "gauge": {"specific_name": "precip_mm", "unit": "mm/day"},
            "era5": {"specific_name": "tp_era5", "unit": "mm/day"},
            "chirps": {"specific_name": "precip_chirps", "unit": "mm/day"},
        },
    },
}

API Reference

hydrodataset.hydro_dataset.StandardVariable

A class to hold standardized variable names as constants.

Source code in hydrodataset/hydro_dataset.py 
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
class StandardVariable:
    """A class to hold standardized variable names as constants."""

    STREAMFLOW = "streamflow"
    WATER_LEVEL = "water_level"

    PRECIPITATION = "precipitation"
    CRAINF_FRAC = "crainf_frac"  # Fraction of total precipitation that is convective
    PRECIPITATION_MIN = "precipitation_min"
    PRECIPITATION_MAX = "precipitation_max"
    PRECIPITATION_MEDIAN = "precipitation_median"

    TEMPERATURE_MAX = "temperature_max"
    TEMPERATURE_MIN = "temperature_min"
    TEMPERATURE_MEAN = "temperature_mean"

    DAYLIGHT_DURATION = "daylight_duration"
    RELATIVE_DAYLIGHT_DURATION = "relative_daylight_duration"

    SOLAR_RADIATION = "solar_radiation"
    SOLAR_RADIATION_MIN = "solar_radiation_min"
    SOLAR_RADIATION_MAX = "solar_radiation_max"
    SOLAR_RADIATION_MEDIAN = "solar_radiation_median"
    THERMAL_RADIATION = "thermal_radiation"
    THERMAL_RADIATION_MIN = "thermal_radiation_min"
    THERMAL_RADIATION_MAX = "thermal_radiation_max"
    LONGWAVE_SOLAR_RADIATION = "longwave_solar_radiation"

    SNOW_WATER_EQUIVALENT = "snow_water_equivalent"
    SNOW_WATER_EQUIVALENT_MIN = "snow_water_equivalent_min"
    SNOW_WATER_EQUIVALENT_MAX = "snow_water_equivalent_max"
    SNOW_DEPTH = "snow_depth"
    SNOW_COVER = "snow_cover"
    SNOW_SUBLIMATION = "snow_sublimation"
    SNOW_DENSITY = "snow_density"

    VAPOR_PRESSURE = "vapor_pressure"

    SURFACE_PRESSURE = "surface_pressure"
    SURFACE_PRESSURE_MIN = "surface_pressure_min"
    SURFACE_PRESSURE_MAX = "surface_pressure_max"

    WIND_SPEED = "wind_speed"
    U_WIND_SPEED = "u_wind_speed"
    U_WIND_SPEED_MIN = "u_wind_speed_min"
    U_WIND_SPEED_MAX = "u_wind_speed_max"
    V_WIND_SPEED = "v_wind_speed"
    V_WIND_SPEED_MIN = "v_wind_speed_min"
    V_WIND_SPEED_MAX = "v_wind_speed_max"
    WIND_DIR = "wind_dir"
    LOW_LEVEL_WIND_SHEAR = "low_level_wind_shear"
    DEEP_LEVEL_WIND_SHEAR = "deep_level_wind_shear"

    RELATIVE_HUMIDITY = "relative_humidity"
    SPECIFIC_HUMIDITY = "specific_humidity"
    RELATIVE_HUMIDITY_MIN = "relative_humidity_min"
    RELATIVE_HUMIDITY_MAX = "relative_humidity_max"
    RELATIVE_HUMIDITY_MEDIAN = "relative_humidity_median"
    TOTAL_COLUMN_WATER_VAPOUR = "total_column_water_vapour"

    CAPE = "cape"  # Convective available potential energy
    CIN = "cin"  # Convective inhibition

    POTENTIAL_EVAPOTRANSPIRATION = "potential_evapotranspiration"
    EVAPORATION = "evaporation"
    EVAPOTRANSPIRATION = "evapotranspiration"

    SOIL_MOISTURE = "soil_moisture"
    VOLUMETRIC_SOIL_WATER_LAYER1 = "volumetric_soil_water_layer1"  # 0-7cm
    VOLUMETRIC_SOIL_WATER_LAYER1_MIN = "volumetric_soil_water_layer1_min"
    VOLUMETRIC_SOIL_WATER_LAYER1_MAX = "volumetric_soil_water_layer1_max"
    VOLUMETRIC_SOIL_WATER_LAYER2 = "volumetric_soil_water_layer2"  # 7-28cm
    VOLUMETRIC_SOIL_WATER_LAYER2_MIN = "volumetric_soil_water_layer2_min"
    VOLUMETRIC_SOIL_WATER_LAYER2_MAX = "volumetric_soil_water_layer2_max"
    VOLUMETRIC_SOIL_WATER_LAYER3 = "volumetric_soil_water_layer3"  # 28-100cm
    VOLUMETRIC_SOIL_WATER_LAYER3_MIN = "volumetric_soil_water_layer3_min"
    VOLUMETRIC_SOIL_WATER_LAYER3_MAX = "volumetric_soil_water_layer3_max"
    VOLUMETRIC_SOIL_WATER_LAYER4 = "volumetric_soil_water_layer4"  # 100-289cm
    VOLUMETRIC_SOIL_WATER_LAYER4_MIN = "volumetric_soil_water_layer4_min"
    VOLUMETRIC_SOIL_WATER_LAYER4_MAX = "volumetric_soil_water_layer4_max"

    MIN_RAIN_RATE = "min_rain_rate"
    MAX_RAIN_RATE = "max_rain_rate"

    GROUND_HEAT_FLUX = "ground_heat_flux"