Market Aggregates

Market aggregates, especially used with weighting such as capacity weighting, are useful proxies to estimate how differences in forecasts - either between models or between different forecasts of the same model - impact energy production & consumption. For more information about market aggregates, see the Market Aggregates page.

Market aggregates can be queried directly through the Jua Python SDK, using the MarketAggregates class.

Example

As an introduction to market aggregates in the SDK, see this simple example. For more examples, please see our GitHub repository.

from datetime import datetime

import matplotlib.pyplot as plt
from jua import JuaClient
from jua.market_aggregates import AggregateVariables, ModelRuns
from jua.types import MarketZones
from jua.weather import Models

client = JuaClient()

# Create an energy market for specific zones
germany = client.market_aggregates.get_market(market_zone=MarketZones.DE)

# Select two EPT-2 forecasts and two ECMWF IFS forecasts to compare
model_runs = [
    ModelRuns(
        Models.EPT2, 
        [
            datetime(2025, 9, 29, 0),
            datetime(2025, 9, 29, 6),
        ]
    ),
    ModelRuns(
        Models.ECMWF_IFS_SINGLE, 
        [
            datetime(2025, 9, 29, 0),
            datetime(2025, 9, 29, 6),
        ]
    ),
]

# Retrieve the 2-day 10m wind market aggregates for Germany
# An xarray.Dataset is returned, containing the market aggregates
# for each model run
wind_data = germany.compare_runs(
    agg_variable=AggregateVariables.WIND_SPEED_AT_HEIGHT_LEVEL_10M,
    model_runs=model_runs,
    max_lead_time=48,
)

# Plot the 4 market aggregates using matplotlib
fig, ax = plt.subplots(figsize=(15, 5))
wind_data["wind_speed_at_height_level_10m"].plot(ax=ax, x="time", hue="model_run")
ax.set_title("10m Wind Market Aggregates: Germany")
plt.show()

This will plot the following:

Documentation

Aggregate Variables

The AggregateVariables enum provides the following variables:

• AggregateVariables.WIND_SPEED_AT_HEIGHT_LEVEL_10M

• AggregateVariables.WIND_SPEED_AT_HEIGHT_LEVEL_100M

• AggregateVariables.SURFACE_DOWNWELLING_SHORTWAVE_FLUX_SUM_1H

• AggregateVariables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M

Aggregate variables automatically uses the appropriate weighting from the Weighting enum:

• Wind variables use Weighting.WIND_CAPACITY

• Solar variables use Weighting.SOLAR_CAPACITY

• Temperature uses Weighting.POPULATION

Example:

Accessing all available AggregateVariables

# Listing all available AggregateVariables
print("Available AggregateVariables:")
for var in AggregateVariables:
    print(f"  - variable: {var}")

Output

Energy Market

An EnergyMarket provides access to spatially aggregated forecast data for specific market zones. Data is weighted by the appropriate factor (wind capacity, solar capacity, or population) depending on the variable requested. This is useful for energy market analysis where you need regionally aggregated forecasts.

Attributes:
    client: JuaClient
        The JuaClient instance for API communication.
    market_zone: MarketZones | str | list[MarketZones | str]
        The market zones or list of market zones to aggregate data for.

Methods:
    compare_runs():
        Attributes:
            agg_variable: AggregateVariable | AggregateVariables
                The AggregateVariable specifying which variable to query.
        
            model_runs: list[ModelRuns]
                List of ModelRuns instances specifying which model forecasts to
                query. Each ModelRuns contains a model and one or more init_times
                (datetimes or non-negative integers).

            min_lead_time: int
                Minimum forecast lead time in hours (default: 0).
            
            max_lead_time: int | None
                Maximum forecast lead time in hours. If None, returns
                all available lead times.

        Returns:
            xarray.Dataset containing `model_run` and `time` dimensions, with
            `prediction_timedelta` and the queried variable as data_vars.

Examples:

from datetime import datetime

from jua import JuaClient
from jua.market_aggregates import AggregateVariables, ModelRuns
from jua.types import MarketZones
from jua.weather import Models

client = JuaClient()

# Create an energy market for specific zones
germany = client.market_aggregates.get_market(market_zone=MarketZones.DE)

# Select two EPT-2 forecasts and two ECMWF IFS forecasts to compare
model_runs = [ModelRuns(Models.EPT2, [0, 1])]

# Retrieve the 2-day 10m wind market aggregates for Germany
wind_data = germany.compare_runs(
    agg_variable=AggregateVariables.SURFACE_DOWNWELLING_SHORTWAVE_FLUX_SUM_1H,
    model_runs=model_runs,
    max_lead_time=48,
)

Market Zones

The MarketZones is a simple helper Enum containing the available market zones for market aggregate queries.

Example:

List Available MarketZones

from jua.types import MarketZones

print("Available MarketZones:")
for market_zone in MarketZones:
    print(f"  - {market_zone.name} (country: {market_zone.country})")

Output

Model Runs

ModelRuns is a simple data container that combines a weather model with one or more initialization times. The initialization times can be specified as datetime objects or as integer indices to select from recent runs. Integers from 0 to 12 can be used to select any of the 12 most recent initialization times:

• 0: latest run

• 1: second latest run

• 2: third latest run, etc.

Attributes:
    model: The weather model (from Models enum).
    init_times: The initialization times. Can be:
        - A single datetime or a non-negative integer (0 to 12).
        - A list of datetimes.
        - A list of non-negative integers (0 to 12)

Example:

from datetime import datetime
from jua.market_aggregates import ModelRuns
from jua.weather import Models

# the latest EPT2 forecast
run = ModelRuns(Models.EPT2, 0)

# the 3 most recent EPT2 forecasts
run = ModelRuns(Models.EPT2, [0, 1, 2])

# a specific EPT2 forecast from the 5th of August 2024
run = ModelRuns(Models.EPT2, datetime(2024, 8, 5, 0))

# all EPT2 forecasts from the 5th of August 2024
run = ModelRuns(
    Models.EPT2,
    [
        datetime(2024, 8, 5, 0),
        datetime(2024, 8, 5, 6),
        datetime(2024, 8, 5, 12),
        datetime(2024, 8, 5, 18),
    ]
)