iwsTimeSeriesWrapper
Python template · sinapsis_darts_forecasting.templates.time_series_metrics
Overview
Dynamic Template for Darts metrics computation.
This template wraps any metric from the `darts.metrics` module and makes it available as a Sinapsis template. The wrapped metric is applied to the predictions and ground truth of each time series packet in the input container, and the result is stored in the `generic_data` field of the time series packet.
IMPORTANT NOTE: Validation mode should be enabled during model fitting and prediction (e.g., in the `TimeSeriesModel` template), to ensure that the metric is computed on the correct portion of the time series (i.e., the forecast horizon). If validation mode is not enabled, forecasted values and ground truth values may not be properly aligned, which can lead to incorrect metric calculations.
iws — inherited documentation
Interval Winkler Score (IWS) [1]_.
IWS gives the length / width of the quantile intervals plus a penalty if the observation is outside the interval.
For the true series :math:`y` and predicted stochastic or quantile series :math:`\hat{y}` of length :math:`T`, it is computed per component/column, quantile interval :math:`(q_l,q_h)`, and time step :math:`t` as:
.. math:: \begin{equation} \begin{cases} (U_t - L_t) + \frac{1}{q_l} (L_t - y_t) & \text{if } y_t < L_t \\ (U_t - L_t) & \text{if } L_t \leq y_t \leq U_t \\ (U_t - L_t) + \frac{1}{1 - q_h} (y_t - U_t) & \text{if } y_t > U_t \end{cases} \end{equation}
where :math:`U_t` are the predicted upper bound quantile values :math:`\hat{y}_{q_h,t}` (of all predicted quantiles or samples) at time :math:`t`, and :math:`L_t` are the predicted lower bound quantile values :math:`\hat{y}_{q_l,t}`.
Parameters ---------- actual_series The (sequence of) actual series. pred_series The (sequence of) predicted series. intersect For time series that are overlapping in time without having the same time index, setting `True` will consider the values only over their common time interval (intersection in time). q_interval The quantile interval(s) to compute the metric on. Must be a tuple (single interval) or sequence of tuples (multiple intervals) with elements (low quantile, high quantile). q Quantiles `q` not supported by this metric; use `q_interval` instead. component_reduction Optionally, a function to aggregate the metrics over the component/column axis. It must reduce a `np.ndarray` of shape `(t, c)` to a `np.ndarray` of shape `(t,)`. The function takes as input a ``np.ndarray`` and a parameter named `axis`, and returns the reduced array. The `axis` receives value `1` corresponding to the component axis. If `None`, will return a metric per component. time_reduction Optionally, a function to aggregate the metrics over the time axis. It must reduce a `np.ndarray` of shape `(t, c)` to a `np.ndarray` of shape `(c,)`. The function takes as input a ``np.ndarray`` and a parameter named `axis`, and returns the reduced array. The `axis` receives value `0` corresponding to the time axis. If `None`, will return a metric per time step. series_reduction Optionally, a function to aggregate the metrics over multiple series. It must reduce a `np.ndarray` of shape `(s, t, c)` to a `np.ndarray` of shape `(t, c)` The function takes as input a ``np.ndarray`` and a parameter named `axis`, and returns the reduced array. The `axis` receives value `0` corresponding to the series axis. For example with `np.nanmean`, will return the average over all series metrics. If `None`, will return a metric per component. n_jobs The number of jobs to run in parallel. Parallel jobs are created only when a ``Sequence[TimeSeries]`` is passed as input, parallelising operations regarding different ``TimeSeries``. Defaults to `1` (sequential). Setting the parameter to `-1` means using all the available processors. verbose Optionally, whether to print operations progress.
Returns ------- float A single metric score for (with `len(q_interval) <= 1`):
- a single univariate series. - a single multivariate series with `component_reduction`. - a sequence (list) of uni/multivariate series with `series_reduction`, `component_reduction` and `time_reduction`. np.ndarray A numpy array of metric scores. The array has shape (n time steps, n components * n q intervals) without time- and component reductions, and shape (n time steps, n q intervals) without time- but with component reduction and `len(q_interval) > 1`. For:
- the input from the `float` return case above but with `len(q_interval) > 1`. - a single multivariate series and at least `component_reduction=None`. - a single uni/multivariate series and at least `time_reduction=None`. - a sequence of uni/multivariate series including `series_reduction` and at least one of `component_reduction=None` or `time_reduction=None`. list[float] Same as for type `float` but for a sequence of series. list[np.ndarray] Same as for type `np.ndarray` but for a sequence of series.
References ---------- .. [1] https://otexts.com/fpp3/distaccuracy.html
Capabilities
Capabilities: not setInstallation
Install the published package using pip or uv.
pip install sinapsis-darts-forecasting==1.0.0uv pip install sinapsis-darts-forecasting==1.0.0uv add sinapsis-darts-forecasting==1.0.0Configuration
Effective fields from the inspector schema, including nested Pydantic model fields.
Required
Default: null
Optional
Default: null
Optional
Default: 1
Optional
Default: false
Optional
Default: true
Optional
Default: null
Field used to set the template instance name and agent name. Defaults to None. iws intersect <class 'bool'>: default: True q_interval typing.Union[tuple[float, float], collections.abc.Sequence[tuple[float, float]]]:… Read full field description
Field used to set the template instance name and agent name. Defaults to None. iws intersect <class 'bool'>: default: True q_interval typing.Union[tuple[float, float], collections.abc.Sequence[tuple[float, float]]]: default: None q typing.Union[float, list[float], tuple[numpy.ndarray, pandas.Index], NoneType]: default: None n_jobs <class 'int'>: default: 1 verbose <class 'bool'>: default: False
Optional
Default: null
Configuration example
Generated from documented defaults. Replace any placeholders and complete required nested settings before running.
templates:
- template_name: "iwsTimeSeriesWrapper"
class_name: "iwsTimeSeriesWrapper"
attributes:
iws:
q: null
n_jobs: 1
verbose: false
intersect: true
q_interval: null
Inheritance
sinapsis_darts_forecasting.templates.time_series_metrics.TimeSeriesMetricsEnvironment variables
Environment definitions belong to their canonical Python modules.