prophet.diagnostics

  1# Copyright (c) Facebook, Inc. and its affiliates.
  2
  3# This source code is licensed under the MIT license found in the
  4# LICENSE file in the root directory of this source tree.
  5
  6from __future__ import annotations
  7
  8import logging
  9from tqdm.auto import tqdm
 10from copy import deepcopy
 11import concurrent.futures
 12import multiprocessing
 13import sys
 14from typing import TYPE_CHECKING, Literal, cast
 15
 16import numpy as np
 17import pandas as pd
 18
 19from prophet.metrics import (  # noqa: F401 – re-exported for backward compatibility
 20    PERFORMANCE_METRICS,
 21    coverage,
 22    mae,
 23    mape,
 24    mdape,
 25    mse,
 26    performance_metrics,
 27    register_performance_metric,
 28    rmse,
 29    rolling_mean_by_h,
 30    rolling_median_by_h,
 31    smape,
 32)
 33
 34if TYPE_CHECKING:
 35    from typing import (
 36        Any,
 37        Callable,
 38        Iterable,
 39        Protocol,
 40        TypeVar,
 41        type_check_only,
 42    )
 43
 44    import dask.distributed as dd
 45
 46    from .forecaster import Prophet
 47
 48    _ModelT = TypeVar('_ModelT', bound=Prophet)
 49
 50    _PerformanceMetricT = TypeVar("_PerformanceMetricT", bound=Callable[..., Any])
 51
 52    @type_check_only
 53    class _SupportsMap(Protocol):
 54        def map(self, __f: Callable[..., object], *its: Iterable[object]) -> Any: ...
 55
 56
 57logger: logging.Logger = logging.getLogger('prophet')
 58
 59
 60def generate_cutoffs(
 61    df: pd.DataFrame,
 62    horizon: pd.Timedelta,
 63    initial: pd.Timedelta,
 64    period: pd.Timedelta,
 65) -> list[pd.Timestamp]:
 66    """Generate cutoff dates
 67
 68    Parameters
 69    ----------
 70    df: pd.DataFrame with historical data.
 71    horizon: pd.Timedelta forecast horizon.
 72    initial: pd.Timedelta window of the initial forecast period.
 73    period: pd.Timedelta simulated forecasts are done with this period.
 74
 75    Returns
 76    -------
 77    list of pd.Timestamp
 78    """
 79    # Last cutoff is 'latest date in data - horizon' date
 80    cutoff = df['ds'].max() - horizon
 81    if cutoff < df['ds'].min():
 82        raise ValueError('Less data than horizon.')
 83    result = [cutoff]
 84    while result[-1] >= min(df['ds']) + initial:
 85        cutoff -= period
 86        # If data does not exist in data range (cutoff, cutoff + horizon]
 87        if not (((df['ds'] > cutoff) & (df['ds'] <= cutoff + horizon)).any()):
 88            # Next cutoff point is 'last date before cutoff in data - horizon'
 89            if cutoff > df['ds'].min():
 90                closest_date = df[df['ds'] <= cutoff].max()['ds']
 91                cutoff = closest_date - horizon
 92            # else no data left, leave cutoff as is, it will be dropped.
 93        result.append(cutoff)
 94    result = result[:-1]
 95    if len(result) == 0:
 96        raise ValueError(
 97            'Less data than horizon after initial window. '
 98            'Make horizon or initial shorter.'
 99        )
100    logger.info('Making {} forecasts with cutoffs between {} and {}'.format(
101        len(result), result[-1], result[0]
102    ))
103    return list(reversed(result))
104
105
106def cross_validation(
107    model: Prophet,
108    horizon: str | pd.Timedelta,
109    period: str | pd.Timedelta | None = None,
110    initial: str | pd.Timedelta | None = None,
111    parallel: Literal["processes", "threads", "dask"] | _SupportsMap | None = None,
112    cutoffs: list[pd.Timestamp] | None = None,
113    disable_tqdm: bool = False,
114    extra_output_columns: str | list[str] | None = None,
115) -> pd.DataFrame:
116    """Cross-Validation for time series.
117
118    Computes forecasts from historical cutoff points, which user can input.
119    If not provided, begins from (end - horizon) and works backwards, making
120    cutoffs with a spacing of period until initial is reached.
121
122    When period is equal to the time interval of the data, this is the
123    technique described in https://robjhyndman.com/hyndsight/tscv/ .
124
125    Parameters
126    ----------
127    model: Prophet class object. Fitted Prophet model.
128    horizon: string with pd.Timedelta compatible style, e.g., '5 days',
129        '3 hours', '10 seconds'.
130    period: string with pd.Timedelta compatible style. Simulated forecast will
131        be done at every this period. If not provided, 0.5 * horizon is used.
132    initial: string with pd.Timedelta compatible style. The first training
133        period will include at least this much data. If not provided,
134        3 * horizon is used.
135    cutoffs: list of pd.Timestamp specifying cutoffs to be used during
136        cross validation. If not provided, they are generated as described
137        above.
138    parallel: {None, 'processes', 'threads', 'dask', object}
139        How to parallelize the forecast computation. By default no parallelism
140        is used.
141
142        * None: No parallelism.
143        * 'processes': Parallelize with concurrent.futures.ProcessPoolExecutor.
144        * 'threads': Parallelize with concurrent.futures.ThreadPoolExecutor.
145            Note that some operations currently hold Python's Global Interpreter
146            Lock, so parallelizing with threads may be slower than training
147            sequentially.
148        * 'dask': Parallelize with Dask.
149           This requires that a dask.distributed Client be created.
150        * object: Any instance with a `.map` method. This method will
151          be called with :func:`single_cutoff_forecast` and a sequence of
152          iterables where each element is the tuple of arguments to pass to
153          :func:`single_cutoff_forecast`
154
155          .. code-block::
156
157             class MyBackend:
158                 def map(self, func, *iterables):
159                     results = [
160                        func(*args)
161                        for args in zip(*iterables)
162                     ]
163                     return results
164
165    disable_tqdm: if True it disables the progress bar that would otherwise show up when parallel=None
166    extra_output_columns: A String or List of Strings e.g. 'trend' or ['trend'].
167         Additional columns to 'yhat' and 'ds' to be returned in output.
168
169    Returns
170    -------
171    A pd.DataFrame with the forecast, actual value and cutoff.
172    """
173
174    if model.history is None:
175        raise Exception('Model has not been fit. Fitting the model provides contextual parameters for cross validation.')
176
177    df = model.history.copy().reset_index(drop=True)
178    horizon = pd.Timedelta(horizon)
179    predict_columns = ['ds', 'yhat']
180
181    if model.uncertainty_samples:
182        predict_columns.extend(['yhat_lower', 'yhat_upper'])
183
184    if extra_output_columns is not None:
185        if isinstance(extra_output_columns, str):
186            extra_output_columns = [extra_output_columns]
187        predict_columns.extend([c for c in extra_output_columns if c not in predict_columns])
188
189    # Identify the largest seasonality period
190    period_max = 0.
191    for s in model.seasonalities.values():
192        period_max = max(period_max, s['period'])
193    seasonality_dt = pd.Timedelta(str(period_max) + ' days')
194
195    if cutoffs is None:
196        # Set period
197        period = 0.5 * horizon if period is None else pd.Timedelta(period)
198
199        # Set initial
200        initial = (
201            max(3 * horizon, seasonality_dt) if initial is None
202            else pd.Timedelta(initial)
203        )
204
205        # Compute Cutoffs
206        cutoffs = generate_cutoffs(df, horizon, initial, period)
207    else:
208        # add validation of the cutoff to make sure that the min cutoff is strictly greater than the min date in the history
209        if min(cutoffs) <= df['ds'].min():
210            raise ValueError("Minimum cutoff value is not strictly greater than min date in history")
211        # max value of cutoffs is <= (end date minus horizon)
212        end_date_minus_horizon = df['ds'].max() - horizon
213        if max(cutoffs) > end_date_minus_horizon:
214            raise ValueError("Maximum cutoff value is greater than end date minus horizon, no value for cross-validation remaining")
215        initial = cutoffs[0] - df['ds'].min()
216
217    # Check if the initial window
218    # (that is, the amount of time between the start of the history and the first cutoff)
219    # is less than the maximum seasonality period
220    if initial < seasonality_dt:
221            msg = 'Seasonality has period of {} days '.format(period_max)
222            msg += 'which is larger than initial window. '
223            msg += 'Consider increasing initial.'
224            logger.warning(msg)
225
226    if parallel:
227        valid = {"threads", "processes", "dask"}
228
229        if parallel == "threads":
230            pool = concurrent.futures.ThreadPoolExecutor()
231        elif parallel == "processes":
232            if sys.platform.startswith("win") or sys.platform == "darwin":
233                ctx = multiprocessing.get_context("spawn")
234            else:
235                ctx = multiprocessing.get_context("forkserver")
236            pool = concurrent.futures.ProcessPoolExecutor(mp_context=ctx)
237        elif parallel == "dask":
238            try:
239                from dask.distributed import get_client
240            except ImportError as e:
241                raise ImportError("parallel='dask' requires the optional "
242                                  "dependency dask.") from e
243            pool = get_client()
244            # get_client() returns a client managed by the caller.
245            # delay df and model to avoid large objects in task graph.
246            df, model = pool.scatter([df, model])
247        elif hasattr(parallel, "map"):
248            pool = parallel
249        else:
250            msg = ("'parallel' should be one of {} for an instance with a "
251                   "'map' method".format(', '.join(valid)))
252            raise ValueError(msg)
253
254        iterables = ((df, model, cutoff, horizon, predict_columns)
255                     for cutoff in cutoffs)
256        iterables = zip(*iterables)
257
258        logger.info("Applying in parallel with %s", pool)
259        try:
260            predicts = pool.map(single_cutoff_forecast, *iterables)
261            if parallel == "dask":
262                # convert Futures to DataFrames
263                predicts = cast("dd.Client", pool).gather(predicts)
264        finally:
265            if (
266                parallel in ("threads", "processes")
267                and isinstance(pool, concurrent.futures.Executor)
268            ):
269                pool.shutdown(wait=True)
270
271    else:
272        predicts = [
273            single_cutoff_forecast(df, model, cutoff, horizon, predict_columns)
274            for cutoff in (tqdm(cutoffs) if not disable_tqdm else cutoffs)
275        ]
276
277    # Combine all predicted pd.DataFrame into one pd.DataFrame
278    return pd.concat(cast("Iterable[Any]", predicts), axis=0).reset_index(drop=True)
279
280
281def single_cutoff_forecast(
282    df: pd.DataFrame,
283    model: Prophet,
284    cutoff: pd.Timestamp,
285    horizon: pd.Timedelta,
286    predict_columns: list[str],
287) -> pd.DataFrame:
288    """Forecast for single cutoff. Used in cross validation function
289    when evaluating for multiple cutoffs either sequentially or in parallel.
290
291    Parameters
292    ----------
293    df: pd.DataFrame.
294        DataFrame with history to be used for single
295        cutoff forecast.
296    model: Prophet model object.
297    cutoff: pd.Timestamp cutoff date.
298        Simulated Forecast will start from this date.
299    horizon: pd.Timedelta forecast horizon.
300    predict_columns: List of strings e.g. ['ds', 'yhat'].
301        Columns with date and forecast to be returned in output.
302
303    Returns
304    -------
305    A pd.DataFrame with the forecast, actual value and cutoff.
306
307    """
308
309    # Generate new object with copying fitting options
310    m = prophet_copy(model, cutoff)
311    # Train model
312    history_c = df[df['ds'] <= cutoff]
313    if history_c.shape[0] < 2:
314        raise Exception(
315            'Less than two datapoints before cutoff. '
316            'Increase initial window.'
317        )
318    m.fit(history_c, **model.fit_kwargs)
319    # Calculate yhat
320    index_predicted = (df['ds'] > cutoff) & (df['ds'] <= cutoff + horizon)
321    # Get the columns for the future dataframe
322    columns = ['ds']
323    if m.growth == 'logistic':
324        columns.append('cap')
325        if m.logistic_floor:
326            columns.append('floor')
327    columns.extend(m.extra_regressors.keys())
328    columns.extend([
329        props['condition_name']
330        for props in m.seasonalities.values()
331        if props['condition_name'] is not None])
332    # Multiple seasonalities can share the same condition column.
333    columns = list(dict.fromkeys(columns))
334    yhat = m.predict(df[index_predicted][columns])
335    # Merge yhat(predicts), y(df, original data) and cutoff
336
337    assert m.stan_backend
338    m.stan_backend.cleanup()
339
340    return pd.concat([
341        yhat[predict_columns],
342        df[index_predicted][['y']].reset_index(drop=True),
343        pd.DataFrame({'cutoff': [cutoff] * len(yhat)})
344    ], axis=1)
345
346
347def prophet_copy(m: _ModelT, cutoff: pd.Timestamp | None = None) -> _ModelT:
348    """Copy Prophet object
349
350    Parameters
351    ----------
352    m: Prophet model.
353    cutoff: pd.Timestamp or None, default None.
354        cutoff Timestamp for changepoints member variable.
355        changepoints are only retained if 'changepoints <= cutoff'
356
357    Returns
358    -------
359    Prophet class object with the same parameter with model variable
360    """
361    if m.history is None:
362        raise Exception('This is for copying a fitted Prophet object.')
363
364    if m.specified_changepoints:
365        changepoints = m.changepoints
366        if cutoff is not None:
367            # Filter change points '< cutoff'
368            last_history_date = max(m.history['ds'][m.history['ds'] <= cutoff])
369            assert changepoints is not None
370            changepoints = changepoints[changepoints < last_history_date]
371    else:
372        changepoints = None
373
374    # Auto seasonalities are set to False because they are already set in
375    # m.seasonalities.
376    m2 = m.__class__(
377        growth=m.growth,
378        n_changepoints=m.n_changepoints,
379        changepoint_range=m.changepoint_range,
380        changepoints=changepoints,
381        yearly_seasonality=False,
382        weekly_seasonality=False,
383        daily_seasonality=False,
384        holidays=m.holidays,
385        holidays_mode=m.holidays_mode,
386        seasonality_mode=m.seasonality_mode,
387        seasonality_prior_scale=m.seasonality_prior_scale,
388        changepoint_prior_scale=m.changepoint_prior_scale,
389        holidays_prior_scale=m.holidays_prior_scale,
390        mcmc_samples=m.mcmc_samples,
391        interval_width=m.interval_width,
392        uncertainty_samples=m.uncertainty_samples,
393        stan_backend=(
394            m.stan_backend.get_type() if m.stan_backend is not None
395            else None
396        ),
397    )
398    m2.extra_regressors = deepcopy(m.extra_regressors)
399    m2.seasonalities = deepcopy(m.seasonalities)
400    m2.country_holidays = deepcopy(m.country_holidays)
401    return m2
logger: logging.Logger = <Logger prophet (INFO)>
def generate_cutoffs( df: pandas.DataFrame, horizon: pandas.Timedelta, initial: pandas.Timedelta, period: pandas.Timedelta) -> list[pandas.Timestamp]:
 61def generate_cutoffs(
 62    df: pd.DataFrame,
 63    horizon: pd.Timedelta,
 64    initial: pd.Timedelta,
 65    period: pd.Timedelta,
 66) -> list[pd.Timestamp]:
 67    """Generate cutoff dates
 68
 69    Parameters
 70    ----------
 71    df: pd.DataFrame with historical data.
 72    horizon: pd.Timedelta forecast horizon.
 73    initial: pd.Timedelta window of the initial forecast period.
 74    period: pd.Timedelta simulated forecasts are done with this period.
 75
 76    Returns
 77    -------
 78    list of pd.Timestamp
 79    """
 80    # Last cutoff is 'latest date in data - horizon' date
 81    cutoff = df['ds'].max() - horizon
 82    if cutoff < df['ds'].min():
 83        raise ValueError('Less data than horizon.')
 84    result = [cutoff]
 85    while result[-1] >= min(df['ds']) + initial:
 86        cutoff -= period
 87        # If data does not exist in data range (cutoff, cutoff + horizon]
 88        if not (((df['ds'] > cutoff) & (df['ds'] <= cutoff + horizon)).any()):
 89            # Next cutoff point is 'last date before cutoff in data - horizon'
 90            if cutoff > df['ds'].min():
 91                closest_date = df[df['ds'] <= cutoff].max()['ds']
 92                cutoff = closest_date - horizon
 93            # else no data left, leave cutoff as is, it will be dropped.
 94        result.append(cutoff)
 95    result = result[:-1]
 96    if len(result) == 0:
 97        raise ValueError(
 98            'Less data than horizon after initial window. '
 99            'Make horizon or initial shorter.'
100        )
101    logger.info('Making {} forecasts with cutoffs between {} and {}'.format(
102        len(result), result[-1], result[0]
103    ))
104    return list(reversed(result))

Generate cutoff dates

Parameters
  • df (pd.DataFrame with historical data.):

  • horizon (pd.Timedelta forecast horizon.):

  • initial (pd.Timedelta window of the initial forecast period.):

  • period (pd.Timedelta simulated forecasts are done with this period.):

Returns
  • list of pd.Timestamp
def cross_validation( model: 'Prophet', horizon: str | pandas.Timedelta, period: str | pandas.Timedelta | None = None, initial: str | pandas.Timedelta | None = None, parallel: "Literal['processes', 'threads', 'dask'] | _SupportsMap | None" = None, cutoffs: list[pandas.Timestamp] | None = None, disable_tqdm: bool = False, extra_output_columns: str | list[str] | None = None) -> pandas.DataFrame:
107def cross_validation(
108    model: Prophet,
109    horizon: str | pd.Timedelta,
110    period: str | pd.Timedelta | None = None,
111    initial: str | pd.Timedelta | None = None,
112    parallel: Literal["processes", "threads", "dask"] | _SupportsMap | None = None,
113    cutoffs: list[pd.Timestamp] | None = None,
114    disable_tqdm: bool = False,
115    extra_output_columns: str | list[str] | None = None,
116) -> pd.DataFrame:
117    """Cross-Validation for time series.
118
119    Computes forecasts from historical cutoff points, which user can input.
120    If not provided, begins from (end - horizon) and works backwards, making
121    cutoffs with a spacing of period until initial is reached.
122
123    When period is equal to the time interval of the data, this is the
124    technique described in https://robjhyndman.com/hyndsight/tscv/ .
125
126    Parameters
127    ----------
128    model: Prophet class object. Fitted Prophet model.
129    horizon: string with pd.Timedelta compatible style, e.g., '5 days',
130        '3 hours', '10 seconds'.
131    period: string with pd.Timedelta compatible style. Simulated forecast will
132        be done at every this period. If not provided, 0.5 * horizon is used.
133    initial: string with pd.Timedelta compatible style. The first training
134        period will include at least this much data. If not provided,
135        3 * horizon is used.
136    cutoffs: list of pd.Timestamp specifying cutoffs to be used during
137        cross validation. If not provided, they are generated as described
138        above.
139    parallel: {None, 'processes', 'threads', 'dask', object}
140        How to parallelize the forecast computation. By default no parallelism
141        is used.
142
143        * None: No parallelism.
144        * 'processes': Parallelize with concurrent.futures.ProcessPoolExecutor.
145        * 'threads': Parallelize with concurrent.futures.ThreadPoolExecutor.
146            Note that some operations currently hold Python's Global Interpreter
147            Lock, so parallelizing with threads may be slower than training
148            sequentially.
149        * 'dask': Parallelize with Dask.
150           This requires that a dask.distributed Client be created.
151        * object: Any instance with a `.map` method. This method will
152          be called with :func:`single_cutoff_forecast` and a sequence of
153          iterables where each element is the tuple of arguments to pass to
154          :func:`single_cutoff_forecast`
155
156          .. code-block::
157
158             class MyBackend:
159                 def map(self, func, *iterables):
160                     results = [
161                        func(*args)
162                        for args in zip(*iterables)
163                     ]
164                     return results
165
166    disable_tqdm: if True it disables the progress bar that would otherwise show up when parallel=None
167    extra_output_columns: A String or List of Strings e.g. 'trend' or ['trend'].
168         Additional columns to 'yhat' and 'ds' to be returned in output.
169
170    Returns
171    -------
172    A pd.DataFrame with the forecast, actual value and cutoff.
173    """
174
175    if model.history is None:
176        raise Exception('Model has not been fit. Fitting the model provides contextual parameters for cross validation.')
177
178    df = model.history.copy().reset_index(drop=True)
179    horizon = pd.Timedelta(horizon)
180    predict_columns = ['ds', 'yhat']
181
182    if model.uncertainty_samples:
183        predict_columns.extend(['yhat_lower', 'yhat_upper'])
184
185    if extra_output_columns is not None:
186        if isinstance(extra_output_columns, str):
187            extra_output_columns = [extra_output_columns]
188        predict_columns.extend([c for c in extra_output_columns if c not in predict_columns])
189
190    # Identify the largest seasonality period
191    period_max = 0.
192    for s in model.seasonalities.values():
193        period_max = max(period_max, s['period'])
194    seasonality_dt = pd.Timedelta(str(period_max) + ' days')
195
196    if cutoffs is None:
197        # Set period
198        period = 0.5 * horizon if period is None else pd.Timedelta(period)
199
200        # Set initial
201        initial = (
202            max(3 * horizon, seasonality_dt) if initial is None
203            else pd.Timedelta(initial)
204        )
205
206        # Compute Cutoffs
207        cutoffs = generate_cutoffs(df, horizon, initial, period)
208    else:
209        # add validation of the cutoff to make sure that the min cutoff is strictly greater than the min date in the history
210        if min(cutoffs) <= df['ds'].min():
211            raise ValueError("Minimum cutoff value is not strictly greater than min date in history")
212        # max value of cutoffs is <= (end date minus horizon)
213        end_date_minus_horizon = df['ds'].max() - horizon
214        if max(cutoffs) > end_date_minus_horizon:
215            raise ValueError("Maximum cutoff value is greater than end date minus horizon, no value for cross-validation remaining")
216        initial = cutoffs[0] - df['ds'].min()
217
218    # Check if the initial window
219    # (that is, the amount of time between the start of the history and the first cutoff)
220    # is less than the maximum seasonality period
221    if initial < seasonality_dt:
222            msg = 'Seasonality has period of {} days '.format(period_max)
223            msg += 'which is larger than initial window. '
224            msg += 'Consider increasing initial.'
225            logger.warning(msg)
226
227    if parallel:
228        valid = {"threads", "processes", "dask"}
229
230        if parallel == "threads":
231            pool = concurrent.futures.ThreadPoolExecutor()
232        elif parallel == "processes":
233            if sys.platform.startswith("win") or sys.platform == "darwin":
234                ctx = multiprocessing.get_context("spawn")
235            else:
236                ctx = multiprocessing.get_context("forkserver")
237            pool = concurrent.futures.ProcessPoolExecutor(mp_context=ctx)
238        elif parallel == "dask":
239            try:
240                from dask.distributed import get_client
241            except ImportError as e:
242                raise ImportError("parallel='dask' requires the optional "
243                                  "dependency dask.") from e
244            pool = get_client()
245            # get_client() returns a client managed by the caller.
246            # delay df and model to avoid large objects in task graph.
247            df, model = pool.scatter([df, model])
248        elif hasattr(parallel, "map"):
249            pool = parallel
250        else:
251            msg = ("'parallel' should be one of {} for an instance with a "
252                   "'map' method".format(', '.join(valid)))
253            raise ValueError(msg)
254
255        iterables = ((df, model, cutoff, horizon, predict_columns)
256                     for cutoff in cutoffs)
257        iterables = zip(*iterables)
258
259        logger.info("Applying in parallel with %s", pool)
260        try:
261            predicts = pool.map(single_cutoff_forecast, *iterables)
262            if parallel == "dask":
263                # convert Futures to DataFrames
264                predicts = cast("dd.Client", pool).gather(predicts)
265        finally:
266            if (
267                parallel in ("threads", "processes")
268                and isinstance(pool, concurrent.futures.Executor)
269            ):
270                pool.shutdown(wait=True)
271
272    else:
273        predicts = [
274            single_cutoff_forecast(df, model, cutoff, horizon, predict_columns)
275            for cutoff in (tqdm(cutoffs) if not disable_tqdm else cutoffs)
276        ]
277
278    # Combine all predicted pd.DataFrame into one pd.DataFrame
279    return pd.concat(cast("Iterable[Any]", predicts), axis=0).reset_index(drop=True)

Cross-Validation for time series.

Computes forecasts from historical cutoff points, which user can input. If not provided, begins from (end - horizon) and works backwards, making cutoffs with a spacing of period until initial is reached.

When period is equal to the time interval of the data, this is the technique described in https://robjhyndman.com/hyndsight/tscv/ .

Parameters
  • model (Prophet class object. Fitted Prophet model.):

  • horizon (string with pd.Timedelta compatible style, e.g., '5 days',): '3 hours', '10 seconds'.

  • period (string with pd.Timedelta compatible style. Simulated forecast will): be done at every this period. If not provided, 0.5 * horizon is used.
  • initial (string with pd.Timedelta compatible style. The first training): period will include at least this much data. If not provided, 3 * horizon is used.
  • cutoffs (list of pd.Timestamp specifying cutoffs to be used during): cross validation. If not provided, they are generated as described above.
  • parallel ({None, 'processes', 'threads', 'dask', object}): How to parallelize the forecast computation. By default no parallelism is used.

    • None: No parallelism.
    • 'processes': Parallelize with concurrent.futures.ProcessPoolExecutor.
    • 'threads': Parallelize with concurrent.futures.ThreadPoolExecutor. Note that some operations currently hold Python's Global Interpreter Lock, so parallelizing with threads may be slower than training sequentially.
    • 'dask': Parallelize with Dask. This requires that a dask.distributed Client be created.
    • object: Any instance with a .map method. This method will be called with single_cutoff_forecast() and a sequence of iterables where each element is the tuple of arguments to pass to single_cutoff_forecast()

      ```

  • class MyBackend:: def map(self, func, *iterables): results = [ func(*args) for args in zip(*iterables) ] return results
  • ```
  • disable_tqdm (if True it disables the progress bar that would otherwise show up when parallel=None):

  • extra_output_columns (A String or List of Strings e.g. 'trend' or ['trend'].): Additional columns to 'yhat' and 'ds' to be returned in output.

Returns
  • A pd.DataFrame with the forecast, actual value and cutoff.
def single_cutoff_forecast( df: pandas.DataFrame, model: 'Prophet', cutoff: pandas.Timestamp, horizon: pandas.Timedelta, predict_columns: list[str]) -> pandas.DataFrame:
282def single_cutoff_forecast(
283    df: pd.DataFrame,
284    model: Prophet,
285    cutoff: pd.Timestamp,
286    horizon: pd.Timedelta,
287    predict_columns: list[str],
288) -> pd.DataFrame:
289    """Forecast for single cutoff. Used in cross validation function
290    when evaluating for multiple cutoffs either sequentially or in parallel.
291
292    Parameters
293    ----------
294    df: pd.DataFrame.
295        DataFrame with history to be used for single
296        cutoff forecast.
297    model: Prophet model object.
298    cutoff: pd.Timestamp cutoff date.
299        Simulated Forecast will start from this date.
300    horizon: pd.Timedelta forecast horizon.
301    predict_columns: List of strings e.g. ['ds', 'yhat'].
302        Columns with date and forecast to be returned in output.
303
304    Returns
305    -------
306    A pd.DataFrame with the forecast, actual value and cutoff.
307
308    """
309
310    # Generate new object with copying fitting options
311    m = prophet_copy(model, cutoff)
312    # Train model
313    history_c = df[df['ds'] <= cutoff]
314    if history_c.shape[0] < 2:
315        raise Exception(
316            'Less than two datapoints before cutoff. '
317            'Increase initial window.'
318        )
319    m.fit(history_c, **model.fit_kwargs)
320    # Calculate yhat
321    index_predicted = (df['ds'] > cutoff) & (df['ds'] <= cutoff + horizon)
322    # Get the columns for the future dataframe
323    columns = ['ds']
324    if m.growth == 'logistic':
325        columns.append('cap')
326        if m.logistic_floor:
327            columns.append('floor')
328    columns.extend(m.extra_regressors.keys())
329    columns.extend([
330        props['condition_name']
331        for props in m.seasonalities.values()
332        if props['condition_name'] is not None])
333    # Multiple seasonalities can share the same condition column.
334    columns = list(dict.fromkeys(columns))
335    yhat = m.predict(df[index_predicted][columns])
336    # Merge yhat(predicts), y(df, original data) and cutoff
337
338    assert m.stan_backend
339    m.stan_backend.cleanup()
340
341    return pd.concat([
342        yhat[predict_columns],
343        df[index_predicted][['y']].reset_index(drop=True),
344        pd.DataFrame({'cutoff': [cutoff] * len(yhat)})
345    ], axis=1)

Forecast for single cutoff. Used in cross validation function when evaluating for multiple cutoffs either sequentially or in parallel.

Parameters
  • df (pd.DataFrame.): DataFrame with history to be used for single cutoff forecast.
  • model (Prophet model object.):

  • cutoff (pd.Timestamp cutoff date.): Simulated Forecast will start from this date.

  • horizon (pd.Timedelta forecast horizon.):

  • predict_columns (List of strings e.g. ['ds', 'yhat'].): Columns with date and forecast to be returned in output.

Returns
  • A pd.DataFrame with the forecast, actual value and cutoff.
def prophet_copy(m: '_ModelT', cutoff: pandas.Timestamp | None = None) -> '_ModelT':
348def prophet_copy(m: _ModelT, cutoff: pd.Timestamp | None = None) -> _ModelT:
349    """Copy Prophet object
350
351    Parameters
352    ----------
353    m: Prophet model.
354    cutoff: pd.Timestamp or None, default None.
355        cutoff Timestamp for changepoints member variable.
356        changepoints are only retained if 'changepoints <= cutoff'
357
358    Returns
359    -------
360    Prophet class object with the same parameter with model variable
361    """
362    if m.history is None:
363        raise Exception('This is for copying a fitted Prophet object.')
364
365    if m.specified_changepoints:
366        changepoints = m.changepoints
367        if cutoff is not None:
368            # Filter change points '< cutoff'
369            last_history_date = max(m.history['ds'][m.history['ds'] <= cutoff])
370            assert changepoints is not None
371            changepoints = changepoints[changepoints < last_history_date]
372    else:
373        changepoints = None
374
375    # Auto seasonalities are set to False because they are already set in
376    # m.seasonalities.
377    m2 = m.__class__(
378        growth=m.growth,
379        n_changepoints=m.n_changepoints,
380        changepoint_range=m.changepoint_range,
381        changepoints=changepoints,
382        yearly_seasonality=False,
383        weekly_seasonality=False,
384        daily_seasonality=False,
385        holidays=m.holidays,
386        holidays_mode=m.holidays_mode,
387        seasonality_mode=m.seasonality_mode,
388        seasonality_prior_scale=m.seasonality_prior_scale,
389        changepoint_prior_scale=m.changepoint_prior_scale,
390        holidays_prior_scale=m.holidays_prior_scale,
391        mcmc_samples=m.mcmc_samples,
392        interval_width=m.interval_width,
393        uncertainty_samples=m.uncertainty_samples,
394        stan_backend=(
395            m.stan_backend.get_type() if m.stan_backend is not None
396            else None
397        ),
398    )
399    m2.extra_regressors = deepcopy(m.extra_regressors)
400    m2.seasonalities = deepcopy(m.seasonalities)
401    m2.country_holidays = deepcopy(m.country_holidays)
402    return m2

Copy Prophet object

Parameters
  • m (Prophet model.):

  • cutoff (pd.Timestamp or None, default None.): cutoff Timestamp for changepoints member variable. changepoints are only retained if 'changepoints <= cutoff'

Returns
  • Prophet class object with the same parameter with model variable