Technical Documentation
jua.weather.forecast.Forecast
class jua.weather.forecast.Forecast(client: jua.client.JuaClient, model: jua.weather.models.Models)
Access to weather forecast data for a specific model.
This class provides methods to retrieve and query weather forecast data from Jua’s forecasting models. It supports both point-based queries and spatial area selection.
The class is typically accessed via a Model instance.
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)
>>>
>>> # Get latest global forecast
>>> forecast = model.forecast.get_forecast()
>>>
>>> # Get forecast for specific points
>>> zurich = LatLon(lat=47.3769, lon=8.5417)
>>> london = LatLon(lat=51.5074, lon=-0.1278)
>>> forecast = model.forecast.get_forecast(
... points=[zurich, london],
... variables=[Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M]
... )property zarr_version : int | None
Get the Zarr version of the original data.
This is the Zarr format that was used to store the original data.
Returns: The Zarr format version number or None if not applicable.
is_global_data_available() → bool
Check if global data access is available for this model.
Some models only support point forecasts while others allow access to global forecast data.
Returns: True if global data can be accessed, False otherwise.
get_metadata( init_time: datetime.datetime | str = 'latest' ) → jua.weather._types.api_response_types.ForecastMetadataResponse | None
Get metadata about a forecast.
Retrieves information about a specific forecast, including initialization time, available forecasted hours, and other model-specific metadata.
This metadata is useful for checking availability and planning data retrieval operations.
Parameters:init_time – The initialization time of the forecast. Use “latest” for the most recent forecast, or provide a specific datetime or string in ISO format (e.g., “2023-01-15T12:00:00”). Must be an exact match.
Returns: Metadata about the forecast or None if not available.
Examples
>>> metadata = model.forecast.get_metadata()
>>> print(f"Latest forecast from: {metadata.init_time}")
>>> print(f"Hours available: {metadata.available_forecasted_hours}")get_available_init_times() → list[datetime.datetime]
Get a list of available forecast initialization times.
Retrieves the list of initialization times for which forecasts are available for the current model.
NOTE
For non-Jua models, only the latest forecast is typically available. For EPT1.5 and EPT1.5 Early models, this returns initialization times that are currently cached. For EPT2, this returns all initialization times available in the database.
Returns: A list of datetime objects representing available forecast init times, sorted from most recent to oldest.
Examples
>>> init_times = model.forecast.get_available_init_times()
>>> print(f"Most recent forecast: {init_times[0]}")
>>> print(f"Total forecasts available: {len(init_times)}")is_ready( forecasted_hours: int, init_time: datetime.datetime | str = 'latest' ) → 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.forecast.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: datetime.datetime | str = 'latest', variables: list[jua.weather.variables.Variables] | list[str] | None = None, prediction_timedelta: jua.types.geo.PredictionTimeDelta | None = None, latitude: jua.types.geo.SpatialSelection | None = None, longitude: jua.types.geo.SpatialSelection | None = None, points: list[jua.types.geo.LatLon] | jua.types.geo.LatLon | None = None, min_lead_time: int | None = None, max_lead_time: int | None = None, method: str | None = 'nearest', print_progress: bool | None = None ) → jua.weather.JuaDataset
Retrieve forecast data for the model.
This is the primary method for accessing weather forecast data. It supports multiple ways to specify both spatial selection (points, list or slice of latitude/longitude) and forecast time periods (prediction_timedelta or min/max lead times).
The method automatically chooses the most efficient way to retrieve the data based on the query parameters.
Parameters:
init_time – Forecast initialization time. Use “latest” for the most recent forecast, or provide a specific datetime or ISO-format string.
variables – List of weather variables to retrieve. If None, all available variables are included.
prediction_timedelta – Time period to include in the forecast. Can be:
A single value (hours or timedelta) for a specific lead time
A slice(start, stop) for a range of lead times
A slice(start, stop, step) for 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 range.
longitude – Longitude selection. Can be a single value, list of values, or a slice(min_lon, max_lon) for a range.
points – Specific geographic points to get forecasts for. Can be a single LatLon object or a list of LatLon objects.
min_lead_time – Minimum lead time in hours (alternative to prediction_timedelta).
max_lead_time – Maximum lead time in hours (alternative to prediction_timedelta).
method – Interpolation method for selecting points:
“nearest” (default): Use nearest grid point
All other methods supported by xarray
print_progress – Whether to display a progress bar during data loading. If None, uses the client’s default setting.
Returns: JuaDataset containing the requested forecast data.
Raises:ValueError – If both points and latitude/longitude are provided, or if other parameter combinations are invalid.
Examples
>>> # Get global forecast for temperature and wind speed
>>> forecast = model.forecast.get_forecast(
... variables=[
... Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M,
... Variables.WIND_SPEED_AT_HEIGHT_LEVEL_10M
... ]
... )
>>>
>>> # Get forecast for a specific region (Europe)
>>> europe = model.forecast.get_forecast(
... 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.forecast.get_forecast(
... 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
... )Last updated