Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/_docs/trend_changepoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.


<a id="adjusting-trend-flexibility"> </a>

### Adjusting trend flexibility
Expand Down
4 changes: 3 additions & 1 deletion notebooks/trend_changepoints.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -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."
]
},
{
Expand Down
53 changes: 44 additions & 9 deletions python/prophet/forecaster.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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 (
Expand Down Expand Up @@ -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(
Expand Down
5 changes: 5 additions & 0 deletions python/prophet/serialize.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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)
Expand Down
47 changes: 47 additions & 0 deletions python/prophet/tests/test_prophet.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
11 changes: 11 additions & 0 deletions python/prophet/tests/test_serialize.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down