timecopilot.models.ensembles

MedianEnsemble

MedianEnsemble(
    models: list[Forecaster], alias: str = "MedianEnsemble"
)

Bases: Forecaster

Initialize a MedianEnsemble forecaster.

This ensemble combines the forecasts of multiple models by taking the median of their predictions for each time step and series. For probabilistic forecasts (quantiles and levels), it uses isotonic regression to ensure monotonicity of the quantile outputs across the ensemble. Optionally, you can set a custom alias for the ensemble.

Parameters:

Name	Type	Description	Default
models	list[Forecaster]	List of instantiated forecaster models to be ensembled. Each model must implement the forecast method and have a unique alias.	required
alias	str	Name to use for the ensemble in output DataFrames and logs. Defaults to "MedianEnsemble".	'MedianEnsemble'

Example

import pandas as pd
from timecopilot.models.benchmarks import SeasonalNaive
from timecopilot.models.ensembles.median import MedianEnsemble
from timecopilot.models.foundational.chronos import Chronos


df = pd.read_csv(
    "https://timecopilot.s3.amazonaws.com/public/data/air_passengers.csv",
    parse_dates=["ds"],
)

models = [
    Chronos(
        repo_id="amazon/chronos-t5-tiny",
        alias="Chronos-T5",
    ),
    Chronos(
        repo_id="amazon/chronos-bolt-tiny",
        alias="Chronos-Bolt",
    ),
    SeasonalNaive(),
]
median_ensemble = MedianEnsemble(models=models)
fcst_df = median_ensemble.forecast(
    df=df,
    h=12,
)
print(fcst_df)

Source code in timecopilot/models/ensembles/median.py

def __init__(self, models: list[Forecaster], alias: str = "MedianEnsemble"):
    # fmt: off
    """
    Initialize a MedianEnsemble forecaster.

    This ensemble combines the forecasts of multiple models by taking the 
    median of their predictions for each time step and series. 
    For probabilistic forecasts (quantiles and levels),
    it uses isotonic regression to ensure monotonicity of the quantile outputs 
    across the ensemble. Optionally, you can set a custom alias 
    for the ensemble.

    Args:
        models (list[Forecaster]):
            List of instantiated forecaster models to be ensembled. Each model must
            implement the forecast method and have a unique alias.
        alias (str, optional):
            Name to use for the ensemble in output DataFrames and logs. Defaults to
            "MedianEnsemble".

    Example:
        ```python
        import pandas as pd
        from timecopilot.models.benchmarks import SeasonalNaive
        from timecopilot.models.ensembles.median import MedianEnsemble
        from timecopilot.models.foundational.chronos import Chronos


        df = pd.read_csv(
            "https://timecopilot.s3.amazonaws.com/public/data/air_passengers.csv",
            parse_dates=["ds"],
        )

        models = [
            Chronos(
                repo_id="amazon/chronos-t5-tiny",
                alias="Chronos-T5",
            ),
            Chronos(
                repo_id="amazon/chronos-bolt-tiny",
                alias="Chronos-Bolt",
            ),
            SeasonalNaive(),
        ]
        median_ensemble = MedianEnsemble(models=models)
        fcst_df = median_ensemble.forecast(
            df=df,
            h=12,
        )
        print(fcst_df)
        ```
    """
    # fmt: on
    self.tcf = TimeCopilotForecaster(models=models, fallback_model=None)
    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/ensembles/median.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.
    """
    qc = QuantileConverter(level=level, quantiles=quantiles)
    _fcst_df = self.tcf._call_models(
        "forecast",
        merge_on=["unique_id", "ds"],
        df=df,
        h=h,
        freq=freq,
        level=None,
        quantiles=qc.quantiles,
    )
    fcst_df = _fcst_df[["unique_id", "ds"]]
    model_cols = [model.alias for model in self.tcf.models]
    fcst_df[self.alias] = _fcst_df[model_cols].median(axis=1)
    if qc.quantiles is not None:
        qs = sorted(qc.quantiles)
        q_cols = []
        for q in qs:
            pct = int(q * 100)
            models_q_cols = [f"{col}-q-{pct}" for col in model_cols]
            q_col = f"{self.alias}-q-{pct}"
            fcst_df[q_col] = _fcst_df[models_q_cols].median(axis=1)
            q_cols.append(q_col)
        # enforce monotonicity
        ir = IsotonicRegression(increasing=True)

        def apply_isotonic(row):
            return ir.fit_transform(qs, row)

        # @Azul: this can be parallelized later
        vals_monotonic = fcst_df[q_cols].apply(
            apply_isotonic,
            axis=1,
            result_type="expand",
        )
        fcst_df[q_cols] = vals_monotonic
        if 0.5 in qc.quantiles:
            fcst_df[self.alias] = fcst_df[f"{self.alias}-q-50"].values
        fcst_df = qc.maybe_convert_quantiles_to_level(
            fcst_df,
            models=[self.alias],
        )
    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,
    )