Docs /Templates/ sinapsis-darts-forecasting

autcTimeSeriesWrapper

sinapsis-darts-forecastingDartsdartsdynamictime_seriesmetrics

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.

autc — inherited documentation

Area Under Tolerance Curve (AUTC).

AUTC measures the overall alignment between actual and predicted series across a range of tolerance levels. For each tolerance level, it computes the fraction of points where the prediction is within ±X% of the actual value. The AUTC is the normalized area under this curve, providing a single score in [0, 1] where higher is better.

For the true series :math:`y` and predicted series :math:`\hat{y}` of length :math:`T`, tolerance levels :math:`\tau \in [0, 1]`, and half-range :math:`H = (\max(y) - \min(y)) / 2`:

.. math::

\text{Coverage}(\tau) = \frac{1}{T} \sum_{t=1}^{T} \mathbb{1}\left[\frac{|y_t - \hat{y}_t|}{H} \leq \tau\right]

\text{AUTC} = \int_0^1 \text{Coverage}(\tau) \, d\tau

At tolerance :math:`\tau`, a prediction is within tolerance if the error is within :math:`\pm\tau` of the actual value (as a fraction of half the range). For example, at 10% tolerance, the prediction must be within ±10% of the half-range, i.e., within ±5% of the full range.

If :math:`\hat{y}_t` are stochastic (contains several samples) or quantile predictions, use parameter `q` to specify on which quantile(s) to compute the metric on. By default, it uses the median 0.5 quantile (over all samples, or, if given, the quantile prediction itself).

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). min_tolerance The minimum tolerance level as a fraction of the series half-range. Default is 0.0 (0%). max_tolerance The maximum tolerance level as a fraction of the series half-range. Default is 1.0 (100%). step The step size between tolerance levels. Default is 0.01 (1%). For example, with defaults, tolerances are [0.0, 0.01, 0.02, ..., 1.0]. q Optionally, the quantile (float [0, 1]) or list of quantiles of interest to compute the metric on. 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. 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.

Raises ------ ValueError If :math:`\max_t{y_t} = \min_t{y_t}` (constant series with zero range).

Returns ------- float A single metric score in [0, 1] (when `len(q) <= 1`) for:

- a single univariate series. - a single multivariate series with `component_reduction`. - a sequence (list) of uni/multivariate series with `series_reduction` and `component_reduction`. np.ndarray A numpy array of metric scores. The array has shape (n components * n quantiles,) without component reduction, and shape (n quantiles,) with component reduction and `len(q) > 1`. For:

- the same input arguments that result in the `float` return case from above but with `len(q) > 1`. - a single multivariate series and at least `component_reduction=None`. - a sequence of uni/multivariate series including `series_reduction` and `component_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.

See Also -------- :func:`~darts.utils.statistics.plot_tolerance_curve` : Plot the tolerance curve for visual inspection.

Capabilities

Capabilities: not set

Installation

Install the published package using pip or uv.

Terminalbash
pip install sinapsis-darts-forecasting==1.0.0
uv pip install sinapsis-darts-forecasting==1.0.0
uv add sinapsis-darts-forecasting==1.0.0

Configuration

Effective fields from the inspector schema, including nested Pydantic model fields.

autcRequired
autcAttributes
Required
Default: null
q
typing.Union[float, list[float], tuple[numpy.ndarray, pandas.Index], NoneType]
Optional
Default: null
step
float
Optional
Default: 0.01
n_jobs
int
Optional
Default: 1
verbose
bool
Optional
Default: false
intersect
bool
Optional
Default: true
max_tolerance
float
Optional
Default: 1
min_tolerance
float
Optional
Default: 0
metadata
Field used to set the template instance name and agent name. Defaults to None. autc intersect <class 'bool'>: default: True min_tolerance <class 'float'>: default: 0.0 max_tolerance <class 'float'>: default: 1.0 step… Read full field description

Field used to set the template instance name and agent name. Defaults to None. autc intersect <class 'bool'>: default: True min_tolerance <class 'float'>: default: 0.0 max_tolerance <class 'float'>: default: 1.0 step <class 'float'>: default: 0.01 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

sinapsis_core.template_base.base_models.TemplateMetadata | None
Optional
Default: null

Configuration example

Generated from documented defaults. Replace any placeholders and complete required nested settings before running.

yaml
templates:
  - template_name: "autcTimeSeriesWrapper"
    class_name: "autcTimeSeriesWrapper"
    attributes:
      autc:
        q: null
        step: 0.01
        n_jobs: 1
        verbose: false
        intersect: true
        max_tolerance: 1
        min_tolerance: 0

Inheritance

Immediate parent: sinapsis_darts_forecasting.templates.time_series_metrics.TimeSeriesMetrics

Environment variables

Environment definitions belong to their canonical Python modules.

SINAPSIS_BUILD_DOCS · defined elsewhere