diff --git a/docs/_docs/trend_changepoints.md b/docs/_docs/trend_changepoints.md index 7817c91f7..75a1dd32c 100644 --- a/docs/_docs/trend_changepoints.md +++ b/docs/_docs/trend_changepoints.md @@ -52,6 +52,9 @@ a = add_changepoints_to_plot(fig.gca(), m, forecast) By default changepoints are only inferred for the first 80% of the time series in order to have plenty of runway for projecting the trend forward and to avoid overfitting fluctuations at the end of the time series. This default works in many situations but not all, and can be changed using the `changepoint_range` argument. For example, `m = Prophet(changepoint_range=0.9)` in Python or `m <- prophet(changepoint.range = 0.9)` in R will place potential changepoints in the first 90% of the time series. +To choose the window by date instead, Python also accepts a `(start, end)` tuple: `m = Prophet(changepoint_range=('2012-01-01', '2014-12-31'))` places potential changepoints among the history dates in that window. This keeps the window fixed as more history is added, where a proportion would shift. + + ### Adjusting trend flexibility diff --git a/notebooks/trend_changepoints.ipynb b/notebooks/trend_changepoints.ipynb index 26db4388b..1e9a9e97b 100644 --- a/notebooks/trend_changepoints.ipynb +++ b/notebooks/trend_changepoints.ipynb @@ -189,7 +189,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "By default changepoints are only inferred for the first 80% of the time series in order to have plenty of runway for projecting the trend forward and to avoid overfitting fluctuations at the end of the time series. This default works in many situations but not all, and can be changed using the `changepoint_range` argument. For example, `m = Prophet(changepoint_range=0.9)` in Python or `m <- prophet(changepoint.range = 0.9)` in R will place potential changepoints in the first 90% of the time series." + "By default changepoints are only inferred for the first 80% of the time series in order to have plenty of runway for projecting the trend forward and to avoid overfitting fluctuations at the end of the time series. This default works in many situations but not all, and can be changed using the `changepoint_range` argument. For example, `m = Prophet(changepoint_range=0.9)` in Python or `m <- prophet(changepoint.range = 0.9)` in R will place potential changepoints in the first 90% of the time series.\n", + "\n", + "To choose the window by date instead, Python also accepts a `(start, end)` tuple: `m = Prophet(changepoint_range=('2012-01-01', '2014-12-31'))` places potential changepoints among the history dates in that window. This keeps the window fixed as more history is added, where a proportion would shift." ] }, { diff --git a/python/prophet/forecaster.py b/python/prophet/forecaster.py index 261776c85..65ebd9717 100644 --- a/python/prophet/forecaster.py +++ b/python/prophet/forecaster.py @@ -46,8 +46,10 @@ class Prophet: then n_changepoints potential changepoints are selected uniformly from the first `changepoint_range` proportion of the history. changepoint_range: Proportion of history in which trend changepoints will - be estimated. Defaults to 0.8 for the first 80%. Not used if - `changepoints` is specified. + be estimated. Defaults to 0.8 for the first 80%. Can also be a + (start, end) tuple of dates, in which case changepoints are placed + uniformly among the history dates between start and end, inclusive. + Not used if `changepoints` is specified. yearly_seasonality: Fit yearly seasonality. Can be 'auto', True, False, or a number of Fourier terms to generate. weekly_seasonality: Fit weekly seasonality. @@ -91,7 +93,7 @@ class Prophet: changepoints: pd.Series[pd.Timestamp] | None n_changepoints: int specified_changepoints: bool - changepoint_range: float + changepoint_range: float | tuple[pd.Timestamp, pd.Timestamp] yearly_seasonality: Literal["auto"] | int weekly_seasonality: Literal["auto"] | int daily_seasonality: Literal["auto"] | int @@ -132,7 +134,7 @@ def __init__( growth: Literal["linear", "logistic", "flat"] = "linear", changepoints: pd.Series | list[pd.Timestamp] | None = None, n_changepoints: int = 25, - changepoint_range: float = 0.8, + changepoint_range: float | tuple[Any, Any] = 0.8, yearly_seasonality: Literal["auto"] | int = "auto", weekly_seasonality: Literal["auto"] | int = "auto", daily_seasonality: Literal["auto"] | int = "auto", @@ -221,14 +223,39 @@ def _load_stan_backend(self, stan_backend: str | None) -> None: logger.debug("Loaded stan backend: %s", self.stan_backend.get_type()) + @staticmethod + def _parse_changepoint_dates( + date_range: tuple[Any, ...], + ) -> tuple[pd.Timestamp, pd.Timestamp]: + """Validate a (start, end) changepoint_range and convert it to Timestamps.""" + if len(date_range) != 2: + raise ValueError("changepoint_range tuple must be (start, end)") + # pd.Timestamp reads a bare number as an epoch offset, so reject those here. + if any(isinstance(date, (int, float)) for date in date_range): + raise ValueError("changepoint_range tuple must contain dates, not numbers") + try: + start, end = pd.Timestamp(date_range[0]), pd.Timestamp(date_range[1]) + except (TypeError, ValueError) as e: + raise ValueError("changepoint_range tuple must contain valid dates") from e + if start is pd.NaT or end is pd.NaT: + raise ValueError("changepoint_range tuple must contain valid dates") + if start.tz is not None or end.tz is not None: + raise ValueError("changepoint_range dates must not have a timezone") + if start >= end: + raise ValueError("changepoint_range start must be before its end") + return start, end + def validate_inputs(self) -> None: """Validates the inputs to Prophet.""" if self.growth not in ('linear', 'logistic', 'flat'): raise ValueError( 'Parameter "growth" should be "linear", "logistic" or "flat".') - if not isinstance(self.changepoint_range, (int, float)): - raise ValueError("changepoint_range must be a number in [0, 1]'") - if ((self.changepoint_range < 0) or (self.changepoint_range > 1)): + if isinstance(self.changepoint_range, tuple): + self.changepoint_range = self._parse_changepoint_dates(self.changepoint_range) + elif not isinstance(self.changepoint_range, (int, float)): + raise ValueError( + "changepoint_range must be a number in [0, 1] or a (start, end) tuple of dates") + elif ((self.changepoint_range < 0) or (self.changepoint_range > 1)): raise ValueError('Parameter "changepoint_range" must be in [0, 1]') if self.holidays is not None: if not ( @@ -492,9 +519,17 @@ def set_changepoints(self) -> None: raise ValueError('Changepoints must fall within training data.') else: # Place potential changepoints evenly through first - # `changepoint_range` proportion of the history + # `changepoint_range` proportion of the history, or through the + # history dates inside it when it is a (start, end) tuple history = cast(pd.DataFrame, self.history) - hist_size = int(np.floor(history.shape[0] * self.changepoint_range)) + if isinstance(self.changepoint_range, tuple): + start, end = self.changepoint_range + history = history[(history['ds'] >= start) & (history['ds'] <= end)] + if history.empty: + raise ValueError('changepoint_range must overlap the training data.') + hist_size = history.shape[0] + else: + hist_size = int(np.floor(history.shape[0] * self.changepoint_range)) if self.n_changepoints + 1 > hist_size: self.n_changepoints = hist_size - 1 logger.info( diff --git a/python/prophet/serialize.py b/python/prophet/serialize.py index d62e44fe9..dbcf6b3db 100644 --- a/python/prophet/serialize.py +++ b/python/prophet/serialize.py @@ -63,6 +63,8 @@ def model_to_dict(model: Prophet) -> dict[str, Any]: model_dict = { attribute: getattr(model, attribute) for attribute in SIMPLE_ATTRIBUTES } + if isinstance(model.changepoint_range, tuple): + model_dict['changepoint_range'] = [str(date) for date in model.changepoint_range] # Handle attributes of non-core types for attribute in PD_SERIES: if getattr(model, attribute) is None: @@ -164,6 +166,9 @@ def model_from_dict(model_dict: dict[str, Any]) -> Prophet: _handle_simple_attributes_backwards_compat(model_dict) for attribute in SIMPLE_ATTRIBUTES: setattr(model, attribute, model_dict[attribute]) + if isinstance(model.changepoint_range, list): + start, end = model.changepoint_range + model.changepoint_range = (pd.Timestamp(start), pd.Timestamp(end)) for attribute in PD_SERIES: if model_dict[attribute] is None: setattr(model, attribute, None) diff --git a/python/prophet/tests/test_prophet.py b/python/prophet/tests/test_prophet.py index 0c5e9d0e2..3c80bd2f9 100644 --- a/python/prophet/tests/test_prophet.py +++ b/python/prophet/tests/test_prophet.py @@ -430,6 +430,53 @@ def test_set_changepoint_range(self, daily_univariate_ts, backend): with pytest.raises(ValueError): m = Prophet(changepoint_range=out_of_range, stan_backend=backend) + def test_set_changepoint_date_range(self, daily_univariate_ts, backend): + train, _ = train_test_split(daily_univariate_ts, daily_univariate_ts.shape[0] // 2) + start, end = train["ds"].iloc[100], train["ds"].iloc[200] + m = Prophet(changepoint_range=(start, str(end)), stan_backend=backend) + assert m.changepoint_range == (start, end) + history = m.setup_dataframe(train, initialize_scales=True) + m.history = history + m.set_changepoints() + assert m.changepoints.shape[0] == m.n_changepoints + assert m.changepoints.min() > start + assert m.changepoints.max() == end + + def test_changepoint_date_range_with_few_dates(self, daily_univariate_ts, backend): + train, _ = train_test_split(daily_univariate_ts, daily_univariate_ts.shape[0] // 2) + m = Prophet( + changepoint_range=(train["ds"].iloc[100], train["ds"].iloc[105]), + stan_backend=backend, + ) + m.history = m.setup_dataframe(train, initialize_scales=True) + m.set_changepoints() + assert m.n_changepoints == 5 + assert m.changepoints.shape[0] == 5 + + def test_changepoint_date_range_outside_history(self, daily_univariate_ts, backend): + train, _ = train_test_split(daily_univariate_ts, daily_univariate_ts.shape[0] // 2) + m = Prophet(changepoint_range=("2100-01-01", "2100-06-01"), stan_backend=backend) + m.history = m.setup_dataframe(train, initialize_scales=True) + with pytest.raises(ValueError, match="overlap"): + m.set_changepoints() + + @pytest.mark.parametrize( + "date_range", + [ + ("2020-01-01",), + ("2020-01-01", "2020-02-01", "2020-03-01"), + ("2020-02-01", "2020-01-01"), + ("2020-01-01", "2020-01-01"), + (0.1, 0.5), + ("not a date", "2020-01-01"), + (None, "2020-01-01"), + ("2020-01-01T00:00:00Z", "2020-02-01T00:00:00Z"), + ], + ) + def test_invalid_changepoint_date_range(self, date_range, backend): + with pytest.raises(ValueError, match="changepoint_range"): + Prophet(changepoint_range=date_range, stan_backend=backend) + def test_get_zero_changepoints(self, daily_univariate_ts, backend): train, _ = train_test_split(daily_univariate_ts, daily_univariate_ts.shape[0] // 2) m = Prophet(n_changepoints=0, stan_backend=backend) diff --git a/python/prophet/tests/test_serialize.py b/python/prophet/tests/test_serialize.py index 3c8bf3d70..de24ff62e 100644 --- a/python/prophet/tests/test_serialize.py +++ b/python/prophet/tests/test_serialize.py @@ -57,6 +57,17 @@ def test_simple_serialize(self, daily_univariate_ts, backend): assert np.array_equal(fcst["yhat"].values, fcst2["yhat"].values) + def test_serialize_changepoint_date_range(self, daily_univariate_ts, backend): + df = daily_univariate_ts.head(daily_univariate_ts.shape[0] - 30) + date_range = (df["ds"].iloc[100], df["ds"].iloc[200]) + m = Prophet(changepoint_range=date_range, stan_backend=backend) + m.fit(df) + + m2 = model_from_json(model_to_json(m)) + + assert m2.changepoint_range == date_range + assert m2.changepoints.equals(m.changepoints) + def test_full_serialize(self, daily_univariate_ts, backend): # Construct a model with all attributes holidays = pd.DataFrame(