Forecasting¶
Forecasts returned by predict() begin at the next time step (t+1). A
forecaster can expose the observation at the fitted current time step (t0)
separately through get_current_value(). Forecasters without a current
observation raise NotImplementedError from that method.
Bases: ABC
flowchart TD
nrgise.forecasters.ForecasterABC[ForecasterABC]
click nrgise.forecasters.ForecasterABC href "" "nrgise.forecasters.ForecasterABC"
Minimal forecasting contract used by built-in NRGISE controllers.
This interface is intentionally small and only captures the behavior required by forecasters currently used inside NRGISE controller implementations.
It is not intended to be a universal abstraction for all forecasting workflows. If a forecaster or controller requires richer inputs, outputs, or interaction patterns, define a dedicated forecaster class and build your controller so it feeds the right inputs for your forecaster. However, if your own forecaster inherits this base class, it will work out-of-the-box with the built in nrgise controllers.
Implementations are responsible for extracting relevant features from State
in fit.
abstractmethod
property
¶
time_delta_seconds: int
Specifies the length of a time step in seconds.
Returns:
| Type | Description |
|---|---|
int
|
The time step length in seconds. |
abstractmethod
¶
fit(state: State) -> None
Fits/updates the model based on the current system state.
This method exists to support built-in NRGISE controllers that operate on
State. Custom forecaster-controller pairs may choose a different input
contract and do not need to implement ForecasterABC.
Implementations are responsible for extracting relevant features from State.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
state
|
State
|
|
required |
abstractmethod
¶
get_current_value() -> float
Return the observed value at the current fitted time step (t0). If not possible with impelemting forecast
method, create a Component and pass the current observation to the Controller through the State.
Returns:
| Type | Description |
|---|---|
float
|
The current observed value. |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
If the forecaster has no current observation. |
abstractmethod
¶
predict(forecast_length: int) -> GenericSequence
Creates a prediction of length forecast_length.
By convention, forecasts in NRGISE start at the next time step
(t+1) and therefore do not include a value for the current time step (t0).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
forecast_length
|
int
|
How many time steps to forecast. Each time step has a length of |
required |
Returns:
| Type | Description |
|---|---|
GenericSequence
|
The forecast of length |
DataProfileForecaster(
forecast_data: UnivariateSequence,
standard_deviation: float = 0,
time_delta_seconds: int = 0,
)
Bases: ForecasterABC
flowchart TD
nrgise.forecasters.DataProfileForecaster[DataProfileForecaster]
nrgise.forecasters.forecaster_abc.ForecasterABC[ForecasterABC]
nrgise.forecasters.forecaster_abc.ForecasterABC --> nrgise.forecasters.DataProfileForecaster
click nrgise.forecasters.DataProfileForecaster href "" "nrgise.forecasters.DataProfileForecaster"
click nrgise.forecasters.forecaster_abc.ForecasterABC href "" "nrgise.forecasters.forecaster_abc.ForecasterABC"
Forecaster based on a predefined univariate data profile.
It returns forecasts by looking ahead in a predefined sequence of values. As the simulation progresses, the current simulation time step is used as a moving pointer into the data profile.
This is useful when the future profile is assumed to be known in advance, for example when modeling a perfect forecast or when adding a simple noise model to an otherwise perfect forecast.
Returned forecasts start at the next time step (t+1). The current observed
profile value is available separately through get_current_value().
If the requested forecast extends beyond the available data profile, the missing values are padded with zeros.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
forecast_data
|
UnivariateSequence
|
Predefined univariate data profile from which forecasts are constructed. |
required |
standard_deviation
|
float
|
Standard deviation of zero-mean Gaussian noise added to the forecast. |
0
|
time_delta_seconds
|
int
|
Time interval represented by one step in |
0
|
fit(state: State) -> None
The fit of this forecaster can be seen as a "pseudo-fit" as we have perfect foresight. We just update the internal time step as pointer from where on the true forecast data should be returned.
get_current_value() -> float
Return the profile value at the current fitted time step.
predict(forecast_length: int) -> GenericSequence
Return a forecast of forecast_length values from the current simulation
position.
If standard_deviation is non-zero, zero-mean Gaussian noise is added
independently to each returned value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
forecast_length
|
int
|
Number of values to return. |
required |
Returns:
| Type | Description |
|---|---|
GenericSequence
|
Forecast sequence with exactly |
ForecastReplayForecaster(
forecast_data: Union[DataFrame, ndarray],
standard_deviation: float = 0,
time_delta_seconds: int = 0,
)
Bases: ForecasterABC
flowchart TD
nrgise.forecasters.ForecastReplayForecaster[ForecastReplayForecaster]
nrgise.forecasters.forecaster_abc.ForecasterABC[ForecasterABC]
nrgise.forecasters.forecaster_abc.ForecasterABC --> nrgise.forecasters.ForecastReplayForecaster
click nrgise.forecasters.ForecastReplayForecaster href "" "nrgise.forecasters.ForecastReplayForecaster"
click nrgise.forecasters.forecaster_abc.ForecasterABC href "" "nrgise.forecasters.forecaster_abc.ForecasterABC"
Forecaster that replays predefined rolling-horizon forecasts.
It returns forecasts that were computed or recorded in advance instead of generating them during the simulation. A typical use case is to run a computationally expensive forecasting model ahead of the simulation, store its rolling-horizon forecasts in this format, and replay those forecasts during one or more simulation runs.
Forecasts are provided as a two-dimensional matrix. Each row contains the
forecast that is available at one simulation time step, while the columns
represent the forecast horizons t+1, t+2, t+3, and so on.
Conceptually, the expected input has the following structure:
forecast forecast horizon
issued at t+1 t+2 t+3 t+4
------------------------------------------
10:00 12.1 12.8 13.4 14.0
10:15 12.5 13.1 13.8 14.2
10:30 12.9 13.5 14.0 14.4
10:45 13.2 13.8 14.3 14.7
11:00 13.6 14.1 14.5 14.9
For example, if the current simulation time corresponds to 10:15,
calling predict(3) returns:
[12.5, 13.1, 13.8]
These values correspond to the t+1, t+2, and t+3 forecasts that
were available at 10:15.
This representation allows forecasts for the same target time to change depending on when they were issued. It can therefore reproduce realistic forecasting behavior, such as forecast errors decreasing as the target time approaches.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
forecast_data
|
Union[DataFrame, ndarray]
|
Two-dimensional array or |
required |
standard_deviation
|
float
|
Standard deviation of zero-mean Gaussian noise added to the forecast. |
0
|
time_delta_seconds
|
int
|
Time interval represented by one step in |
0
|
fit(state: State) -> None
The fit of this forecaster can be seen as a "pseudo-fit" as we have perfect foresight. We just update the internal time step as pointer from where on the true forecast data should be returned.
get_current_value() -> float
Raise because replay data contains only future forecast horizons.
predict(forecast_length: int) -> GenericSequence
Return the stored forecast for the current simulation time step.
The row corresponding to the current simulation time step is selected
from forecast_data. The first forecast_length values of that row are
returned, corresponding to the horizons:
[t+1, t+2, ..., t+forecast_length]
For example, given the row:
t+1 t+2 t+3 t+4
12.5 13.1 13.8 14.2
predict(3) returns:
[12.5, 13.1, 13.8]
If forecast_length exceeds the number of forecast horizons available
in the stored data, a ValueError is raised.
If standard_deviation is non-zero, zero-mean Gaussian noise is added
independently to each returned forecast value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
forecast_length
|
int
|
Number of values to return from precomputed forecast of that time step. |
required |
Returns:
Forecast sequence containing forecast_length values.