Temperature Data Examples

These examples demonstrate how to retrieve and process temperature data from Jua using Python. This specific example calculates the average 2-meter temperature across Germany using a bounding box approach.

Before running this script, ensure you have:

1. Set up your API credentials by following the instructions in our Getting Started guide. The script expects your Key ID and Secret in environment variables.

2. Installed the necessary Python packages. See the list below. You can find more details on recommended packages here.

Average Temperature for a Country

Dependencies

This script requires the following Python packages:

aiohttp
cartopy
dask
fsspec
requests
xarray >= 2023.6.0 # Ensure version supports decode_timedelta=False with zarr
zarr
pandas
numpy

Setting up Authentication

The script requires your Jua API Key ID and Secret to be available as environment variables.

Python (using os.environ)

import os
from aiohttp import BasicAuth

# Retrieve credentials from environment variables
API_KEY_ID = os.environ["JUA_API_KEY_ID"]
API_SECRET = os.environ["JUA_API_SECRET"]

# Create authentication object for data requests
AUTH = BasicAuth(login=API_KEY_ID, password=API_SECRET)

# NB: It may take up to 5 minutes for new API keys to be deployed.
# In the meantime, you may get unauthorized errors.

Bash (setting environment variables)

export JUA_API_KEY_ID="your_api_key_id"
export JUA_API_SECRET="your_api_secret"

Script

Here's the full script to calculate and print the average temperature:

Python

import xarray as xr
import numpy as np
import time
import pandas as pd
from aiohttp import BasicAuth
import os

# --- Authentication Setup ---
API_KEY_ID = os.environ["JUA_API_KEY_ID"]
API_SECRET = os.environ["JUA_API_SECRET"]
AUTH = BasicAuth(login=API_KEY_ID, password=API_SECRET)

# --- Configuration ---
# Use today's 00Z initialization time
init_time = time.strftime("%Y%m%d00")

# Define lead times: every 6 hours for the next 7 days
lead_times = list(range(0, 7 * 24, 6))

# Define bounding box for Germany: (lat_min, lat_max, lon_min, lon_max)
# Note: This is a simple rectangular box. For precise boundaries, consider using shapefiles.
# See: https://www.naturalearthdata.com/downloads/10m-cultural-vectors/
germany_bbox = (47.3024876979, 54.983104153, 5.98865807458, 15.0169958839) # Corrected order latMin, latMax, lonMin, lonMax common convention differs

# --- Data Loading ---
# Construct URLs for each forecast lead time
forecast_urls = [
    f"https://data.jua.ai/forecasts/ept-1.5/{init_time}/{lead_time}.zarr"
    for lead_time in lead_times
]

# Open multiple Zarr datasets efficiently
# Note: Using decode_timedelta=False as 'prediction_timedelta' is already in hours.
# Check xarray version >= 2023.6.0 for this functionality with Zarr.
ds = xr.open_mfdataset(
    forecast_urls,
    parallel=True,
    engine="zarr",
    consolidated=True,
    decode_timedelta=False, # Keep prediction_timedelta as numeric hours
    storage_options={"auth": AUTH},
)

# --- Data Selection & Processing ---
# Select the '2t' variable (2-meter temperature) for the first initialization time step
# and interpolate spatially to the nearest grid points within the bounding box.
data_array = (
    ds["2t"]
    .sel(latitude=slice(germany_bbox[0], germany_bbox[1]),
         longitude=slice(germany_bbox[2], germany_bbox[3]))
    .compute() # Load data into memory
)

# Calculate the spatial mean temperature for each prediction time
mean_temp_kelvin = data_array.mean(dim=["latitude", "longitude"])

# Convert the result to a Pandas DataFrame for easier handling
mean_temp_df = mean_temp_kelvin.to_dataframe().reset_index()

# --- Time and Unit Conversion ---
# Calculate the valid timestamp for each forecast step
mean_temp_df["Datetime"] = pd.to_datetime(mean_temp_df["time"]) + pd.to_timedelta(
    mean_temp_df["prediction_timedelta"], unit="h"
)

# Convert temperature from Kelvin to Celsius
mean_temp_df["Temp C"] = mean_temp_df["2t"] - 273.15

# --- Final Output ---
# Select and rename columns for clarity
final_output = mean_temp_df[["Datetime", "Temp C"]]

print(f"Mean temperature forecast for Germany (Init: {init_time}):")
print(final_output)

Key Concepts Demonstrated

• Setting up authentication using environment variables.

• Loading multiple remote Zarr datasets efficiently using xarray.open_mfdataset.

• Selecting data based on geographical bounding boxes (.sel with slices).

• Calculating spatial averages using .mean().

• Handling time coordinates and prediction offsets using pandas.to_datetime and pandas.to_timedelta.

• Converting temperature units (Kelvin to Celsius).