Variables

Weather Variables

The Jua Python SDK provides a comprehensive set of standardized weather variables through the Variables enum. These variables can be used to access specific weather data across different models with consistent naming.

Overview

The Variables enum serves as a centralized registry of all available weather variables in Jua, offering:

• Type-safe access to weather variables

• Standardized naming across different models

• Unit information

• Display names for visualization

• Model-specific name mappings (ECMWF codes)

Standardized Naming

We use the CFConvention's standard name and extend athmospheric variables with their reference surface and accumulated variables with their accumulation to create distinct and clear names for climate and weather variables.

{parameter_name}[_at_{ref_type}_{ref_value}{ref_unit}][_{agg_type}_{agg_duration}{agg_unit}]

Where:

• {parameter_name}: physical quantity based on the CF convention's standard name (e.g., air_temperature)

• _at_: connecting phrase

• {ref_type}: reference surface type (e.g., pressure_level, height_level, surface)

• {ref_value}: numerical value of the reference surface level (e.g., 2, 100000)

• {ref_unit}: unit of the level measurement (e.g., m for meters, Pa for Pascals)

• {agg_type}: aggregation type of accumulated variable (e.g., mean or sum)

• {agg_duration}: duration of the aggregation (e.g., 6, 3, 1)

• {agg_unit}: unit of the aggregation (e.g., h, min)

The suffix groups [_at_{ref_type}_{ref_value}{ref_unit}] and [_{agg_type}_{agg_duration}{agg_unit}] are only applied for atmospheric and accumulated variables respectively.

Using Variables

from jua.weather import Variables

# Access a variable in a JuaDataset
temperature = forecast_data[Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M]

# Get variable metadata
print(f"Unit: {Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M.unit}")
print(f"ECMWF code: {Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M.emcwf_code}")
print(f"Display name: {Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M.display_name}")

Available Variables

Variable Enum	Standardized Name	Unit	ECMWF Code
AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M	air_temperature_at_height_level_2m	K	2t
DEW_POINT_TEMPERATURE_AT_HEIGHT_LEVEL_2M	dew_point_temperature_at_height_level_2m	K	2d
RELATIVE_HUMIDITY_AT_HEIGHT_LEVEL_2M	relative_humidity_at_height_level_2m	%	r
AIR_DENSITY_AT_HEIGHT_LEVEL_2M	air_density_at_height_level_2m	kg/m³	—
AIR_PRESSURE_AT_MEAN_SEA_LEVEL	air_pressure_at_mean_sea_level	Pa	msl
SURFACE_AIR_PRESSURE	surface_air_pressure	Pa	—
SURFACE_TEMPERATURE	surface_temperature	K	—
WIND_SPEED_AT_HEIGHT_LEVEL_10M	wind_speed_at_height_level_10m	m/s	10si
WIND_DIRECTION_AT_HEIGHT_LEVEL_10M	wind_direction_at_height_level_10m	°	10wdir
WIND_SPEED_AT_HEIGHT_LEVEL_20M	wind_speed_at_height_level_20m	m/s	—
WIND_SPEED_AT_HEIGHT_LEVEL_40M	wind_speed_at_height_level_40m	m/s	—
WIND_SPEED_AT_HEIGHT_LEVEL_60M	wind_speed_at_height_level_60m	m/s	—
WIND_SPEED_AT_HEIGHT_LEVEL_80M	wind_speed_at_height_level_80m	m/s	—
WIND_SPEED_AT_HEIGHT_LEVEL_100M	wind_speed_at_height_level_100m	m/s	100si
WIND_DIRECTION_AT_HEIGHT_LEVEL_100M	wind_direction_at_height_level_100m	°	100wdir
WIND_SPEED_AT_HEIGHT_LEVEL_120M	wind_speed_at_height_level_120m	m/s	—
WIND_SPEED_AT_HEIGHT_LEVEL_140M	wind_speed_at_height_level_140m	m/s	—
WIND_SPEED_AT_HEIGHT_LEVEL_160M	wind_speed_at_height_level_160m	m/s	—
WIND_SPEED_AT_HEIGHT_LEVEL_180M	wind_speed_at_height_level_180m	m/s	—
WIND_SPEED_AT_HEIGHT_LEVEL_200M	wind_speed_at_height_level_200m	m/s	—
WIND_DIRECTION_AT_HEIGHT_LEVEL_200M	wind_direction_at_height_level_200m	°	—
GEOPOTENTIAL_AT_PRESSURE_LEVEL_50000PA	geopotential_at_pressure_level_50000Pa	m² s⁻²	z_500
EASTWARD_WIND_AT_HEIGHT_LEVEL_10M	eastward_wind_at_height_level_10m	m/s	—
NORTHWARD_WIND_AT_HEIGHT_LEVEL_10M	northward_wind_at_height_level_10m	m/s	—
EASTWARD_WIND_AT_HEIGHT_LEVEL_100M	eastward_wind_at_height_level_100m	m/s	—
NORTHWARD_WIND_AT_HEIGHT_LEVEL_100M	northward_wind_at_height_level_100m	m/s	—
PRECIPITATION_AMOUNT_SUM_1H	precipitation_amount_sum_1h	mm/m²	tp
CLOUD_AREA_FRACTION_AT_ENTIRE_ATMOSPHERE	cloud_area_fraction_at_entire_atmosphere	[0,1]	tcc
CLOUD_AREA_FRACTION_AT_ENTIRE_ATMOSPHERE_HIGH_TYPE	cloud_area_fraction_at_entire_atmosphere_high_type	[0,1]	hcc
CLOUD_AREA_FRACTION_AT_ENTIRE_ATMOSPHERE_MEDIUM_TYPE	cloud_area_fraction_at_entire_atmosphere_medium_type	[0,1]	mcc
CLOUD_AREA_FRACTION_AT_ENTIRE_ATMOSPHERE_LOW_TYPE	cloud_area_fraction_at_entire_atmosphere_low_type	[0,1]	lcc
SURFACE_DOWNWELLING_SHORTWAVE_FLUX_SUM_1H	surface_downwelling_shortwave_flux_sum_1h	J/m²	ssrd
SURFACE_DIRECT_DOWNWELLING_SHORTWAVE_FLUX_SUM_1H	surface_direct_downwelling_shortwave_flux_sum_1h	J/m²	fdir
SURFACE_NET_DOWNWARD_SHORTWAVE_FLUX_SUM_1H	surface_net_downward_shortwave_flux_sum_1h	J/m²	ssr
SURFACE_DOWNWELLING_SHORTWAVE_FLUX_SUM_6H	surface_downwelling_shortwave_flux_sum_6h	J/m²	ssrd_6hr

Correspondence of radiation variables

• Direct normal irradiance (DNI or beam radiation) ≙ surface_direct_downwelling_shortwave_flux (fdir).

• Global horizontal irradiance (GHI) ≙ surface_downwelling_shortwave_flux_1h (ssrd).

• Diffuse horizontal irradiance (DHI) can be computed upon request.

Accessing Variable Properties

Each variable in the enum provides access to several properties:

variable = Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M

# Get the standardized name
name = variable.name  # "air_temperature_at_height_level_2m"

# Get the unit
unit = variable.unit  # "K"

# Get the ECMWF code
ecmwf_code = variable.emcwf_code  # "2t"

# Get a formatted display name
display = variable.display_name  # "Air Temperature At Height Level 2m"

# Get display name with unit
display_with_unit = variable.display_name_with_unit  # "Air Temperature At Height Level 2m (K)"

Variable Conversion

The SDK provides utility functions to convert between different variable naming conventions:

from jua.weather.variables import rename_variable

# Convert from ECMWF code to standardized name
std_name = rename_variable("2t")  # Returns "air_temperature_at_height_level_2m"

Using Variables in Data Selection

You can use the Variables enum to select specific variables when requesting forecast or hindcast data:

# Request only specific variables in a forecast
forecast = model.get_forecasts(
    variables=[
        Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M,
        Variables.WIND_SPEED_AT_HEIGHT_LEVEL_10M,
        Variables.PRECIPITATION_AMOUNT_1HOUR
    ]
)

Best Practices

1. Always use the Variables enum instead of string literals for type safety and code clarity

2. Access variable metadata through the enum properties when needed