timecopilot.models.benchmarks.stats

ADIDA

ADIDA(
    alias: str = "ADIDA",
    prediction_intervals: ConformalIntervals | None = None,
)

Bases: Forecaster

ADIDA (Aggregate-Disaggregate Intermittent Demand Approach) model for intermittent demand forecasting. Useful for series with many zero values.

Parameters:

Name	Type	Description	Default
alias	str	Custom name of the model.	'ADIDA'
prediction_intervals	ConformalIntervals	Information to compute conformal prediction intervals.	None

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    alias: str = "ADIDA",
    prediction_intervals: ConformalIntervals | None = None,
):
    """
    Args:
        alias (str): Custom name of the model.
        prediction_intervals (ConformalIntervals, optional): Information to
            compute conformal prediction intervals.
    """
    self.alias = alias
    self.prediction_intervals = prediction_intervals

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    fcst_df = run_statsforecast_model(
        model=_ADIDA(alias=self.alias),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )

AutoARIMA

AutoARIMA(
    d: int | None = None,
    D: int | None = None,
    max_p: int = 5,
    max_q: int = 5,
    max_P: int = 2,
    max_Q: int = 2,
    max_order: int = 5,
    max_d: int = 2,
    max_D: int = 1,
    start_p: int = 2,
    start_q: int = 2,
    start_P: int = 1,
    start_Q: int = 1,
    stationary: bool = False,
    seasonal: bool = True,
    ic: str = "aicc",
    stepwise: bool = True,
    nmodels: int = 94,
    trace: bool = False,
    approximation: bool | None = False,
    method: str | None = None,
    truncate: bool | None = None,
    test: str = "kpss",
    test_kwargs: str | None = None,
    seasonal_test: str = "seas",
    seasonal_test_kwargs: dict | None = None,
    allowdrift: bool = True,
    allowmean: bool = True,
    blambda: float | None = None,
    biasadj: bool = False,
    season_length: int | None = None,
    alias: str = "AutoARIMA",
    prediction_intervals: ConformalIntervals | None = None,
)

Bases: Forecaster

AutoARIMA automatically selects the best ARIMA (AutoRegressive Integrated Moving Average) model using an information criterion (default: AICc). Suitable for univariate time series with trend and seasonality.

Parameters:

Name	Type	Description	Default
d	int	Order of first-differencing.	None
D	int	Order of seasonal-differencing.	None
max_p	int	Max autoregressives p.	5
max_q	int	Max moving averages q.	5
max_P	int	Max seasonal autoregressives P.	2
max_Q	int	Max seasonal moving averages Q.	2
max_order	int	Max p+q+P+Q value if not stepwise selection.	5
max_d	int	Max non-seasonal differences.	2
max_D	int	Max seasonal differences.	1
start_p	int	Starting value of p in stepwise procedure.	2
start_q	int	Starting value of q in stepwise procedure.	2
start_P	int	Starting value of P in stepwise procedure.	1
start_Q	int	Starting value of Q in stepwise procedure.	1
stationary	bool	If True, restricts search to stationary models.	False
seasonal	bool	If False, restricts search to non-seasonal models.	True
ic	str	Information criterion to be used in model selection.	'aicc'
stepwise	bool	If True, will do stepwise selection (faster).	True
nmodels	int	Number of models considered in stepwise search.	94
trace	bool	If True, the searched ARIMA models is reported.	False
approximation	bool	If True, conditional sums-of-squares estimation, final MLE.	False
method	str	Fitting method between maximum likelihood or sums-of-squares.	None
truncate	bool	Observations truncated series used in model selection.	None
test	str	Unit root test to use. See ndiffs for details.	'kpss'
test_kwargs	str	Unit root test additional arguments.	None
seasonal_test	str	Selection method for seasonal differences.	'seas'
seasonal_test_kwargs	dict	Seasonal unit root test arguments.	None
allowdrift	bool	If True, drift models terms considered.	True
allowmean	bool	If True, non-zero mean models considered.	True
blambda	float	Box-Cox transformation parameter.	None
biasadj	bool	Use adjusted back-transformed mean Box-Cox.	False
season_length	int	Number of observations per unit of time. If None, it will be inferred automatically using get_seasonality.	None
alias	str	Custom name of the model.	'AutoARIMA'
prediction_intervals	ConformalIntervals	Information to compute conformal prediction intervals.	None

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    d: int | None = None,
    D: int | None = None,
    max_p: int = 5,
    max_q: int = 5,
    max_P: int = 2,
    max_Q: int = 2,
    max_order: int = 5,
    max_d: int = 2,
    max_D: int = 1,
    start_p: int = 2,
    start_q: int = 2,
    start_P: int = 1,
    start_Q: int = 1,
    stationary: bool = False,
    seasonal: bool = True,
    ic: str = "aicc",
    stepwise: bool = True,
    nmodels: int = 94,
    trace: bool = False,
    approximation: bool | None = False,
    method: str | None = None,
    truncate: bool | None = None,
    test: str = "kpss",
    test_kwargs: str | None = None,
    seasonal_test: str = "seas",
    seasonal_test_kwargs: dict | None = None,
    allowdrift: bool = True,
    allowmean: bool = True,
    blambda: float | None = None,
    biasadj: bool = False,
    season_length: int | None = None,
    alias: str = "AutoARIMA",
    prediction_intervals: ConformalIntervals | None = None,
):
    """
    Args:
        d (int, optional): Order of first-differencing.
        D (int, optional): Order of seasonal-differencing.
        max_p (int): Max autoregressives p.
        max_q (int): Max moving averages q.
        max_P (int): Max seasonal autoregressives P.
        max_Q (int): Max seasonal moving averages Q.
        max_order (int): Max p+q+P+Q value if not stepwise selection.
        max_d (int): Max non-seasonal differences.
        max_D (int): Max seasonal differences.
        start_p (int): Starting value of p in stepwise procedure.
        start_q (int): Starting value of q in stepwise procedure.
        start_P (int): Starting value of P in stepwise procedure.
        start_Q (int): Starting value of Q in stepwise procedure.
        stationary (bool): If True, restricts search to stationary models.
        seasonal (bool): If False, restricts search to non-seasonal models.
        ic (str): Information criterion to be used in model selection.
        stepwise (bool): If True, will do stepwise selection (faster).
        nmodels (int): Number of models considered in stepwise search.
        trace (bool): If True, the searched ARIMA models is reported.
        approximation (bool, optional): If True, conditional sums-of-squares
            estimation, final MLE.
        method (str, optional): Fitting method between maximum likelihood or
            sums-of-squares.
        truncate (bool, optional): Observations truncated series used in model
            selection.
        test (str): Unit root test to use. See `ndiffs` for details.
        test_kwargs (str, optional): Unit root test additional arguments.
        seasonal_test (str): Selection method for seasonal differences.
        seasonal_test_kwargs (dict, optional): Seasonal unit root test arguments.
        allowdrift (bool): If True, drift models terms considered.
        allowmean (bool): If True, non-zero mean models considered.
        blambda (float, optional): Box-Cox transformation parameter.
        biasadj (bool): Use adjusted back-transformed mean Box-Cox.
        season_length (int, optional): Number of observations per unit of time.
            If None, it will be inferred automatically using
            [`get_seasonality`][timecopilot.models.utils.forecaster.get_seasonality].
        alias (str): Custom name of the model.
        prediction_intervals (ConformalIntervals, optional): Information to
            compute conformal prediction intervals.
    """
    self.d = d
    self.D = D
    self.max_p = max_p
    self.max_q = max_q
    self.max_P = max_P
    self.max_Q = max_Q
    self.max_order = max_order
    self.max_d = max_d
    self.max_D = max_D
    self.start_p = start_p
    self.start_q = start_q
    self.start_P = start_P
    self.start_Q = start_Q
    self.stationary = stationary
    self.seasonal = seasonal
    self.ic = ic
    self.stepwise = stepwise
    self.nmodels = nmodels
    self.trace = trace
    self.approximation = approximation
    self.method = method
    self.truncate = truncate
    self.test = test
    self.test_kwargs = test_kwargs
    self.seasonal_test = seasonal_test
    self.seasonal_test_kwargs = seasonal_test_kwargs
    self.allowdrift = allowdrift
    self.allowmean = allowmean
    self.blambda = blambda
    self.biasadj = biasadj
    self.season_length = season_length
    self.alias = alias
    self.prediction_intervals = prediction_intervals

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    season_length = self._maybe_get_seasonality(freq)
    fcst_df = run_statsforecast_model(
        model=_AutoARIMA(
            d=self.d,
            D=self.D,
            max_p=self.max_p,
            max_q=self.max_q,
            max_P=self.max_P,
            max_Q=self.max_Q,
            max_order=self.max_order,
            max_d=self.max_d,
            max_D=self.max_D,
            start_p=self.start_p,
            start_q=self.start_q,
            start_P=self.start_P,
            start_Q=self.start_Q,
            stationary=self.stationary,
            seasonal=self.seasonal,
            ic=self.ic,
            stepwise=self.stepwise,
            nmodels=self.nmodels,
            trace=self.trace,
            approximation=self.approximation,
            method=self.method,
            truncate=self.truncate,
            test=self.test,
            test_kwargs=self.test_kwargs,
            seasonal_test=self.seasonal_test,
            seasonal_test_kwargs=self.seasonal_test_kwargs,
            allowdrift=self.allowdrift,
            allowmean=self.allowmean,
            blambda=self.blambda,
            biasadj=self.biasadj,
            season_length=season_length,
            alias=self.alias,
        ),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )

AutoCES

AutoCES(
    season_length: int | None = None,
    model: str = "Z",
    alias: str = "AutoCES",
    prediction_intervals: ConformalIntervals | None = None,
)

Bases: Forecaster

AutoCES automatically selects the best Complex Exponential Smoothing (CES) model using an information criterion (default: AICc). Suitable for univariate time series with trend and seasonality.

Parameters:

Name	Type	Description	Default
season_length	int	Number of observations per unit of time. If None, it will be inferred automatically using get_seasonality.	None
model	str	CES model string (e.g., "Z").	'Z'
alias	str	Custom name of the model.	'AutoCES'
prediction_intervals	ConformalIntervals	Information to compute conformal prediction intervals.	None

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    season_length: int | None = None,
    model: str = "Z",
    alias: str = "AutoCES",
    prediction_intervals: ConformalIntervals | None = None,
):
    """
    Args:
        season_length (int, optional): Number of observations per unit of time.
            If None, it will be inferred automatically using
            [`get_seasonality`][timecopilot.models.utils.forecaster.get_seasonality].
        model (str): CES model string (e.g., "Z").
        alias (str): Custom name of the model.
        prediction_intervals (ConformalIntervals, optional): Information to
            compute conformal prediction intervals.
    """
    self.season_length = season_length
    self.model = model
    self.alias = alias
    self.prediction_intervals = prediction_intervals

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    season_length = self._maybe_get_seasonality(freq)
    fcst_df = run_statsforecast_model(
        model=_AutoCES(
            season_length=season_length,
            model=self.model,
            alias=self.alias,
        ),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )

AutoETS

AutoETS(
    season_length: int | None = None,
    model: str = "ZZZ",
    damped: bool | None = None,
    phi: float | None = None,
    alias: str = "AutoETS",
    prediction_intervals: ConformalIntervals | None = None,
)

Bases: Forecaster

AutoETS automatically selects the best Error, Trend, Seasonality (ETS) model using an information criterion (default: AICc). Suitable for univariate time series with trend and seasonality.

Parameters:

Name	Type	Description	Default
season_length	int	Number of observations per unit of time. If None, it will be inferred automatically using get_seasonality.	None
model	str	ETS model string (e.g., "ZZZ").	'ZZZ'
damped	bool	Whether to use a damped trend.	None
phi	float	Damping parameter.	None
alias	str	Custom name of the model.	'AutoETS'
prediction_intervals	ConformalIntervals	Information to compute conformal prediction intervals.	None

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    season_length: int | None = None,
    model: str = "ZZZ",
    damped: bool | None = None,
    phi: float | None = None,
    alias: str = "AutoETS",
    prediction_intervals: ConformalIntervals | None = None,
):
    """
    Args:
        season_length (int, optional): Number of observations per unit of time.
            If None, it will be inferred automatically using
            [`get_seasonality`][timecopilot.models.utils.forecaster.get_seasonality].
        model (str): ETS model string (e.g., "ZZZ").
        damped (bool, optional): Whether to use a damped trend.
        phi (float, optional): Damping parameter.
        alias (str): Custom name of the model.
        prediction_intervals (ConformalIntervals, optional): Information to
            compute conformal prediction intervals.
    """
    self.season_length = season_length
    self.model = model
    self.damped = damped
    self.phi = phi
    self.alias = alias
    self.prediction_intervals = prediction_intervals

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    season_length = self._maybe_get_seasonality(freq)
    fcst_df = run_statsforecast_model(
        model=_AutoETS(
            season_length=season_length,
            model=self.model,
            damped=self.damped,
            phi=self.phi,
            alias=self.alias,
        ),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )

CrostonClassic

CrostonClassic(
    alias: str = "CrostonClassic",
    prediction_intervals: ConformalIntervals | None = None,
)

Bases: Forecaster

CrostonClassic model for intermittent demand forecasting.

Parameters:

Name	Type	Description	Default
alias	str	Custom name of the model.	'CrostonClassic'
prediction_intervals	ConformalIntervals	Information to compute conformal prediction intervals.	None

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    alias: str = "CrostonClassic",
    prediction_intervals: ConformalIntervals | None = None,
):
    """
    Args:
        alias (str): Custom name of the model.
        prediction_intervals (ConformalIntervals, optional): Information to
            compute conformal prediction intervals.
    """
    self.alias = alias
    self.prediction_intervals = prediction_intervals

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    fcst_df = run_statsforecast_model(
        model=_CrostonClassic(
            alias=self.alias,
        ),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )

DynamicOptimizedTheta

DynamicOptimizedTheta(
    season_length: int | None = None,
    alias: str = "DynamicOptimizedTheta",
)

Bases: Forecaster

Dynamic Optimized Theta model for univariate time series forecasting.

Parameters:

Name	Type	Description	Default
season_length	int	Number of observations per unit of time. If None, it will be inferred automatically using get_seasonality.	None
alias	str	Custom name of the model.	'DynamicOptimizedTheta'

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    season_length: int | None = None,
    alias: str = "DynamicOptimizedTheta",
):
    """
    Args:
        season_length (int, optional): Number of observations per unit of time.
            If None, it will be inferred automatically using
            [`get_seasonality`][timecopilot.models.utils.forecaster.get_seasonality].
        alias (str): Custom name of the model.
    """
    self.season_length = season_length
    self.alias = alias

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    season_length = self._maybe_get_seasonality(freq)
    fcst_df = run_statsforecast_model(
        model=_DynamicOptimizedTheta(
            season_length=season_length,
            alias=self.alias,
        ),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )

HistoricAverage

HistoricAverage(
    alias: str = "HistoricAverage",
    prediction_intervals: ConformalIntervals | None = None,
)

Bases: Forecaster

HistoricAverage model for univariate time series forecasting.

Parameters:

Name	Type	Description	Default
alias	str	Custom name of the model.	'HistoricAverage'
prediction_intervals	ConformalIntervals	Information to compute conformal prediction intervals.	None

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    alias: str = "HistoricAverage",
    prediction_intervals: ConformalIntervals | None = None,
):
    """
    Args:
        alias (str): Custom name of the model.
        prediction_intervals (ConformalIntervals, optional): Information to
            compute conformal prediction intervals.
    """
    self.alias = alias
    self.prediction_intervals = prediction_intervals

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    fcst_df = run_statsforecast_model(
        model=_HistoricAverage(
            alias=self.alias,
        ),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )

IMAPA

IMAPA(
    alias: str = "IMAPA",
    prediction_intervals: ConformalIntervals | None = None,
)

Bases: Forecaster

IMAPA (Intermittent Demand Aggregated Moving Average) model for intermittent demand forecasting. Useful for series with many zero values.

Parameters:

Name	Type	Description	Default
alias	str	Custom name of the model.	'IMAPA'
prediction_intervals	ConformalIntervals	Information to compute conformal prediction intervals.	None

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    alias: str = "IMAPA",
    prediction_intervals: ConformalIntervals | None = None,
):
    """
    Args:
        alias (str): Custom name of the model.
        prediction_intervals (ConformalIntervals, optional): Information to
            compute conformal prediction intervals.
    """
    self.alias = alias
    self.prediction_intervals = prediction_intervals

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    fcst_df = run_statsforecast_model(
        model=_IMAPA(
            alias=self.alias,
        ),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )

SeasonalNaive

SeasonalNaive(
    season_length: int | None = None,
    alias: str = "SeasonalNaive",
)

Bases: Forecaster

SeasonalNaive model for univariate time series forecasting.

Parameters:

Name	Type	Description	Default
season_length	int	Number of observations per unit of time. If None, it will be inferred automatically using get_seasonality.	None
alias	str	Custom name of the model.	'SeasonalNaive'

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    season_length: int | None = None,
    alias: str = "SeasonalNaive",
):
    """
    Args:
        season_length (int, optional): Number of observations per unit of time.
            If None, it will be inferred automatically using
            [`get_seasonality`][timecopilot.models.utils.forecaster.get_seasonality].
        alias (str): Custom name of the model.
    """
    self.season_length = season_length
    self.alias = alias

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    season_length = self._maybe_get_seasonality(freq)
    fcst_df = run_statsforecast_model(
        model=_SeasonalNaive(
            season_length=season_length,
            alias=self.alias,
        ),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )

Theta

Theta(
    season_length: int | None = None, alias: str = "Theta"
)

Bases: Forecaster

Theta model for univariate time series forecasting.

Parameters:

Name	Type	Description	Default
season_length	int	Number of observations per unit of time. If None, it will be inferred automatically using get_seasonality.	None
alias	str	Custom name of the model.	'Theta'

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    season_length: int | None = None,
    alias: str = "Theta",
):
    """
    Args:
        season_length (int, optional): Number of observations per unit of time.
            If None, it will be inferred automatically using
            [`get_seasonality`][timecopilot.models.utils.forecaster.get_seasonality].
        alias (str): Custom name of the model.
    """
    self.season_length = season_length
    self.alias = alias

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    season_length = self._maybe_get_seasonality(freq)
    fcst_df = run_statsforecast_model(
        model=_Theta(
            season_length=season_length,
            alias=self.alias,
        ),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )

ZeroModel

ZeroModel(
    alias: str = "ZeroModel",
    prediction_intervals: ConformalIntervals | None = None,
)

Bases: Forecaster

ZeroModel model for univariate time series forecasting.

Parameters:

Name	Type	Description	Default
alias	str	Custom name of the model.	'ZeroModel'
prediction_intervals	ConformalIntervals	Information to compute conformal prediction intervals.	None

Source code in timecopilot/models/benchmarks/stats.py

def __init__(
    self,
    alias: str = "ZeroModel",
    prediction_intervals: ConformalIntervals | None = None,
):
    """
    Args:
        alias (str): Custom name of the model.
        prediction_intervals (ConformalIntervals, optional): Information to
            compute conformal prediction intervals.
    """
    self.alias = alias
    self.prediction_intervals = prediction_intervals

forecast

forecast(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Generate forecasts for time series data using the model.

This method produces point forecasts and, optionally, prediction intervals or quantile forecasts. The input DataFrame can contain one or multiple time series in stacked (long) format.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). If provided, the returned DataFrame will include lower and upper interval columns for each specified level.	None
quantiles	list[float]	List of quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. When provided, the output DataFrame will contain additional columns named in the format "model-q-{percentile}", where {percentile} = 100 × quantile value.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing forecast results. Includes: - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified. For multi-series data, the output retains the same unique identifiers as the input DataFrame.

Source code in timecopilot/models/benchmarks/stats.py

def forecast(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """Generate forecasts for time series data using the model.

    This method produces point forecasts and, optionally, prediction
    intervals or quantile forecasts. The input DataFrame can contain one
    or multiple time series in stacked (long) format.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.org/
            pandas-docs/stable/user_guide/timeseries.html#offset-aliases) for
            valid values. If not provided, the frequency will be inferred
            from the data.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). If provided, the returned
            DataFrame will include lower and upper interval columns for
            each specified level.
        quantiles (list[float], optional):
            List of quantiles to forecast, expressed as floats between 0
            and 1. Should not be used simultaneously with `level`. When
            provided, the output DataFrame will contain additional columns
            named in the format "model-q-{percentile}", where {percentile}
            = 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing forecast results. Includes:

                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.

            For multi-series data, the output retains the same unique
            identifiers as the input DataFrame.
    """
    freq = self._maybe_infer_freq(df, freq)
    fcst_df = run_statsforecast_model(
        model=_ZeroModel(
            alias=self.alias,
        ),
        df=df,
        h=h,
        freq=freq,
        level=level,
        quantiles=quantiles,
    )
    return fcst_df

cross_validation

cross_validation(
    df: DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> DataFrame

Perform cross-validation on time series data.

This method splits the time series into multiple training and testing windows and generates forecasts for each window. It enables evaluating forecast accuracy over different historical periods. Supports point forecasts and, optionally, prediction intervals or quantile forecasts.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing the time series to forecast. It must include as columns: - "unique_id": an ID column to distinguish multiple series. - "ds": a time column indicating timestamps or periods. - "y": a target column with the observed values.	required
h	int	Forecast horizon specifying how many future steps to predict in each window.	required
freq	str	Frequency of the time series (e.g. "D" for daily, "M" for monthly). See Pandas frequency aliases for valid values. If not provided, the frequency will be inferred from the data.	None
n_windows	int	Number of cross-validation windows to generate. Defaults to 1.	1
step_size	int	Step size between the start of consecutive windows. If None, it defaults to h.	None
level	list[int | float]	Confidence levels for prediction intervals, expressed as percentages (e.g. [80, 95]). When specified, the output DataFrame includes lower and upper interval columns for each level.	None
quantiles	list[float]	Quantiles to forecast, expressed as floats between 0 and 1. Should not be used simultaneously with level. If provided, additional columns named "model-q-{percentile}" will appear in the output, where {percentile} is 100 × quantile value.	None

Returns:

Type

Description

DataFrame

pd.DataFrame: DataFrame containing the forecasts for each cross-validation window. The output includes: - "unique_id" column to indicate the series. - "ds" column to indicate the timestamp. - "y" column to indicate the target. - "cutoff" column to indicate which window each forecast belongs to. - point forecasts for each timestamp and series. - prediction intervals if `level` is specified. - quantile forecasts if `quantiles` is specified.

Source code in timecopilot/models/utils/forecaster.py

def cross_validation(
    self,
    df: pd.DataFrame,
    h: int,
    freq: str | None = None,
    n_windows: int = 1,
    step_size: int | None = None,
    level: list[int | float] | None = None,
    quantiles: list[float] | None = None,
) -> pd.DataFrame:
    """
    Perform cross-validation on time series data.

    This method splits the time series into multiple training and testing
    windows and generates forecasts for each window. It enables evaluating
    forecast accuracy over different historical periods. Supports point
    forecasts and, optionally, prediction intervals or quantile forecasts.

    Args:
        df (pd.DataFrame):
            DataFrame containing the time series to forecast. It must
            include as columns:

                - "unique_id": an ID column to distinguish multiple series.
                - "ds": a time column indicating timestamps or periods.
                - "y": a target column with the observed values.

        h (int):
            Forecast horizon specifying how many future steps to predict in
            each window.
        freq (str, optional):
            Frequency of the time series (e.g. "D" for daily, "M" for
            monthly). See [Pandas frequency aliases](https://pandas.pydata.
            org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases)
            for valid values. If not provided, the frequency will be inferred
            from the data.
        n_windows (int, optional):
            Number of cross-validation windows to generate. Defaults to 1.
        step_size (int, optional):
            Step size between the start of consecutive windows. If None, it
            defaults to `h`.
        level (list[int | float], optional):
            Confidence levels for prediction intervals, expressed as
            percentages (e.g. [80, 95]). When specified, the output
            DataFrame includes lower and upper interval columns for each
            level.
        quantiles (list[float], optional):
            Quantiles to forecast, expressed as floats between 0 and 1.
            Should not be used simultaneously with `level`. If provided,
            additional columns named "model-q-{percentile}" will appear in
            the output, where {percentile} is 100 × quantile value.

    Returns:
        pd.DataFrame:
            DataFrame containing the forecasts for each cross-validation
            window. The output includes:

                - "unique_id" column to indicate the series.
                - "ds" column to indicate the timestamp.
                - "y" column to indicate the target.
                - "cutoff" column to indicate which window each forecast
                  belongs to.
                - point forecasts for each timestamp and series.
                - prediction intervals if `level` is specified.
                - quantile forecasts if `quantiles` is specified.
    """
    freq = self._maybe_infer_freq(df, freq)
    df = maybe_convert_col_to_datetime(df, "ds")
    # mlforecast cv code
    results = []
    sort_idxs = maybe_compute_sort_indices(df, "unique_id", "ds")
    if sort_idxs is not None:
        df = take_rows(df, sort_idxs)
    splits = backtest_splits(
        df,
        n_windows=n_windows,
        h=h,
        id_col="unique_id",
        time_col="ds",
        freq=pd.tseries.frequencies.to_offset(freq),
        step_size=h if step_size is None else step_size,
    )
    for _, (cutoffs, train, valid) in tqdm(enumerate(splits)):
        if len(valid.columns) > 3:
            raise NotImplementedError(
                "Cross validation with exogenous variables is not yet supported."
            )
        y_pred = self.forecast(
            df=train,
            h=h,
            freq=freq,
            level=level,
            quantiles=quantiles,
        )
        y_pred = join(y_pred, cutoffs, on="unique_id", how="left")
        result = join(
            valid[["unique_id", "ds", "y"]],
            y_pred,
            on=["unique_id", "ds"],
        )
        if result.shape[0] < valid.shape[0]:
            raise ValueError(
                "Cross validation result produced less results than expected. "
                "Please verify that the frequency parameter (freq) "
                "matches your series' "
                "and that there aren't any missing periods."
            )
        results.append(result)
    out = vertical_concat(results)
    out = drop_index_if_pandas(out)
    first_out_cols = ["unique_id", "ds", "cutoff", "y"]
    remaining_cols = [c for c in out.columns if c not in first_out_cols]
    fcst_cv_df = out[first_out_cols + remaining_cols]
    return fcst_cv_df

plot staticmethod

plot(
    df: DataFrame | None = None,
    forecasts_df: DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: Axes | ndarray | Figure | None = None,
)

Plot forecasts and insample values.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with columns [unique_id, ds, y]. Defaults to None.	None
forecasts_df	DataFrame	DataFrame with columns [unique_id, ds] and models. Defaults to None.	None
ids	list[str]	Time Series to plot. If None, time series are selected randomly. Defaults to None.	None
plot_random	bool	Select time series to plot randomly. Defaults to True.	True
max_ids	int	Maximum number of ids to plot. Defaults to 8.	8
models	list[str]	Models to plot. Defaults to None.	None
level	list[float]	Prediction intervals to plot. Defaults to None.	None
max_insample_length	int	Maximum number of train/insample observations to be plotted. Defaults to None.	None
plot_anomalies	bool	Plot anomalies for each prediction interval. Defaults to False.	False
engine	str	Library used to plot. 'plotly', 'plotly-resampler' or 'matplotlib'. Defaults to 'matplotlib'.	'matplotlib'
palette	str	Name of the matplotlib colormap to use for the plots. If None, uses the current style. Defaults to None.	None
seed	int	Seed used for the random number generator. Only used if plot_random is True. Defaults to 0.	None
resampler_kwargs	dict	Keyword arguments to be passed to plotly-resampler constructor. For further custumization ("show_dash") call the method, store the plotting object and add the extra arguments to its show_dash method. Defaults to None.	None
ax	matplotlib axes, array of matplotlib axes or plotly Figure	Object where plots will be added. Defaults to None.	None

Source code in timecopilot/models/utils/forecaster.py

@staticmethod
def plot(
    df: pd.DataFrame | None = None,
    forecasts_df: pd.DataFrame | None = None,
    ids: list[str] | None = None,
    plot_random: bool = True,
    max_ids: int | None = 8,
    models: list[str] | None = None,
    level: list[float] | None = None,
    max_insample_length: int | None = None,
    plot_anomalies: bool = False,
    engine: str = "matplotlib",
    palette: str | None = None,
    seed: int | None = None,
    resampler_kwargs: dict | None = None,
    ax: plt.Axes | np.ndarray | plotly.graph_objects.Figure | None = None,
):
    """Plot forecasts and insample values.

    Args:
        df (pd.DataFrame, optional): DataFrame with columns
            [`unique_id`, `ds`, `y`]. Defaults to None.
        forecasts_df (pd.DataFrame, optional): DataFrame with
            columns [`unique_id`, `ds`] and models. Defaults to None.
        ids (list[str], optional): Time Series to plot. If None, time series
            are selected randomly. Defaults to None.
        plot_random (bool, optional): Select time series to plot randomly.
            Defaults to True.
        max_ids (int, optional): Maximum number of ids to plot. Defaults to 8.
        models (list[str], optional): Models to plot. Defaults to None.
        level (list[float], optional): Prediction intervals to plot.
            Defaults to None.
        max_insample_length (int, optional): Maximum number of train/insample
            observations to be plotted. Defaults to None.
        plot_anomalies (bool, optional): Plot anomalies for each prediction
            interval. Defaults to False.
        engine (str, optional): Library used to plot. 'plotly', 'plotly-resampler'
            or 'matplotlib'. Defaults to 'matplotlib'.
        palette (str, optional): Name of the matplotlib colormap to use for the
            plots. If None, uses the current style. Defaults to None.
        seed (int, optional): Seed used for the random number generator. Only
            used if plot_random is True. Defaults to 0.
        resampler_kwargs (dict, optional): Keyword arguments to be passed to
            plotly-resampler constructor. For further custumization ("show_dash")
            call the method, store the plotting object and add the extra arguments
            to its `show_dash` method. Defaults to None.
        ax (matplotlib axes, array of matplotlib axes or plotly Figure, optional):
            Object where plots will be added. Defaults to None.
    """
    df = ensure_time_dtype(df, time_col="ds")
    if forecasts_df is not None:
        forecasts_df = ensure_time_dtype(forecasts_df, time_col="ds")
    return plot_series(
        df=df,
        forecasts_df=forecasts_df,
        ids=ids,
        plot_random=plot_random,
        max_ids=max_ids,
        models=models,
        level=level,
        max_insample_length=max_insample_length,
        plot_anomalies=plot_anomalies,
        engine=engine,
        resampler_kwargs=resampler_kwargs,
        palette=palette,
        seed=seed,
        id_col="unique_id",
        time_col="ds",
        target_col="y",
        ax=ax,
    )