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
AIR_PRESSURE_AT_MEAN_SEA_LEVEL	air_pressure_at_mean_sea_level	Pa	msl
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_100M	wind_speed_at_height_level_100m	m s⁻¹	100si
WIND_DIRECTION_AT_HEIGHT_LEVEL_100M	wind_direction_at_height_level_100m	°	100wdir
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⁻¹	None
NORTHWARD_WIND_AT_HEIGHT_LEVEL_10M	northward_wind_at_height_level_10m	m s⁻¹	None
EASTWARD_WIND_AT_HEIGHT_LEVEL_100M	eastward_wind_at_height_level_100m	m s⁻¹	None
NORTHWARD_WIND_AT_HEIGHT_LEVEL_100M	northward_wind_at_height_level_100m	m s⁻¹	None
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

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.forecast.get_forecast(
    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