# 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](https://cfconventions.org/) 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

```python
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:

```python
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:

```python
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:

```python
# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.jua.ai/python-sdk/weather/naming.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.