Technical Documentation

jua.weather.Model

class jua.weather.Model(client: jua.client.JuaClient, model: jua.weather.models.Models)

Represents a specific weather model with access to its data. A Model provides unified access to both forecast and hindcast data for a specific weather model. Each model has unique characteristics such as spatial resolution, update frequency, and forecast horizon.

Examples

>>> from jua import JuaClient
>>> from jua.weather import Models, Variables
>>> from jua.types.geo import LatLon
>>>
>>> client = JuaClient()
>>> model = client.weather.get_model(Models.EPT2)
>>>
>>> # access a 5-day forecast for all of europe from the model:
>>> data = model.get_forecasts(
...     init_time=datetime(2024, 8, 5, 0),
...     latitude=slice(72, 36),
...     longitude=slice(-15, 35),
...     max_lead_time=5 * 24,
...     variables=[Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M],
... )
>>>
>>> # Get latest forecast for specific points
>>> zurich = LatLon(lat=47.3769, lon=8.5417)
>>> london = LatLon(lat=51.5074, lon=-0.1278)
>>> forecast = model.get_forecasts(
...     init_time="latest",
...     points=[zurich, london],
...     variables=[Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M]
... )

def get_metadata() -> ModelMetadata:

Get metadata for this model including available variables and grid.

This method retrieves comprehensive metadata about the model, including:

• List of all available weather variables

• Spatial grid resolution (number of latitude/longitude points)

• Model identifier

Returns:

• ModelMetadata containing variables list and grid information.

Examples

>>> metadata = model.get_metadata()
>>> print(f"Variables available: {metadata.variables}")
>>> print(f"Variables available: {metadata.grid}")

get_latest_init_time(min_prediction_timedelta: int = 0) → LatestForecastInfo

Get the latest available forecast initialization time for this model.

This method retrieves information about the most recent forecast run, including its initialization time and maximum available forecast horizon.

Parameters:

• min_prediction_timedelta: Minimum required forecast horizon in hours.

Returns:

• LatestForecastInfo containing the init_time and prediction_timedelta in hours.

Examples

>>> latest = model.get_latest_init_time()
>>> print(f"Latest forecast initialized at: {latest.init_time}")
>>> print(f"Max lead time: {latest.prediction_timedelta} hours")

is_ready( forecasted_hours: int, init_time: datetime.datetime | str = 'latest' &#xNAN;) → bool

Check if a forecast is ready up to a specific lead time.

This method is useful for checking if a forecast has been processed up to a certain number of hours into the future. Forecasts may become available incrementally, with longer lead times becoming available as processing completes.

• Parameters:

  • forecasted_hours – The number of forecast hours needed.

  • init_time – The initialization time of the forecast to check. Use “latest” for the most recent forecast, or provide a specific datetime or string in ISO format. Must be an exact match.

• Returns: True if the forecast is available for the specified hours, False otherwise.

Examples

>>> # Check if 10-day forecast is ready
>>> is_ten_day_ready = model.is_ready(240)
>>> if is_ten_day_ready:
>>>     # Now we can safely request 10-day forecast data
>>>     forecast = model.forecast.get_forecast(max_lead_time=240)

get_forecast( init_time: "latest" | datetime | list[datetime] | slice | None = None, variables: list[Variables] | list[str] | None = None, prediction_timedelta: PredictionTimeDelta | None = None, latitude: SpatialSelection | None = None, longitude: SpatialSelection | None = None, points: list[LatLon] | LatLon | None = None, min_lead_time: int | None = None, max_lead_time: int | None = None, statistics: list[str] | list[Statistics] | None = None, method: "nearest" | "bilinear" = "nearest", stream: bool | None = None, print_progress: bool | None = None, &#xNAN;) → jua.weather.JuaDataset

Retrieve forecasts for this model.

This method loads weather data from any model run, allowing to fetch the latest forecast as well as obtaining data for analysis of historical forecasts and verification against actual observations.

There is currently no lazy-loading for this method, meaning that all requested data will be downloaded once a call is made.

You can filter the forecasts by:

• Time period (init_time)

• Geographic area (latitude/longitude or points)

• Lead time (prediction_timedelta or min/max_lead_time)

• Weather variables (variables)

Parameters:

• init_time: Filter by forecast initialization time. Can be:

  • None or 'latest' (default): The latest available forecast

  • A single datetime: Specific initialization time

  • A list of datetime: Multiple specific times

  • A slice(start, end): Range of initialization times

• variables: List of weather variables to include. If None, returns only Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M.

• prediction_timedelta: Filter by forecast lead time. Can be:

  • None: All available lead times (default)

  • A single value (hours or timedelta): Specific lead time

  • A slice(start, stop): Range of lead times

  • A slice(start, stop, step): Lead times at regular intervals

• latitude: Latitude selection. Can be a single value, list of values, or a slice(min_lat, max_lat) for a geographical range.

• longitude: Longitude selection. Can be a single value, list of values, or a slice(min_lon, max_lon) for a geographical range.

• points: Specific geographic points to get forecasts for. Can be a single LatLon object or a list of LatLon objects (alternative to latitude, longitude).

• min_lead_time: Minimum lead time in hours (alternative to prediction_timedelta).

• max_lead_time: Maximum lead time in hours (alternative to prediction_timedelta).

• statistics: For ensemble models, the statistics to return.

• method: Interpolation method for selecting points:

  • "nearest": Use nearest grid point (default).

  • "bilinear": Bilinear interpolation to the selected point.

• stream: Whether to stream the response content. Recommended when querying slices or large amounts of data. Default is set to False for points, and True for grid slices. Streaming does not support method="bilinear" when requesting points.

• print_progress: Whether to display a progress bar during data loading. If None, uses the client's default setting.

Returns:

• JuaDataset containing the forecast data matching your selection criteria.

Raises:

• ValueError – If both points and latitude/longitude are provided, or if other parameter combinations are invalid.

Examples

>>> # Get the latest global forecast for temperature and wind speed
>>> forecast = model.get_forecasts(
...     variables=[
...         Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M,
...         Variables.WIND_SPEED_AT_HEIGHT_LEVEL_10M
...     ]
... )
>>>
>>> # Get forecast for a specific region (Europe)
>>> europe = model.get_forecasts(
...     latitude=slice(71, 36),  # North to South
...     longitude=slice(-15, 50),  # West to East
...     max_lead_time=120  # 5 days
... )
>>>
>>> # Get forecast for specific cities
>>> cities = model.get_forecasts(
...     points=[
...         LatLon(lat=40.7128, lon=-74.0060),  # New York
...         LatLon(lat=51.5074, lon=-0.1278),   # London
...         LatLon(lat=35.6762, lon=139.6503)   # Tokyo
...     ],
...     max_lead_time=72  # 3 days
... )