multi-ets 0.1.0__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. {multi_ets-0.1.0/src/multi_ets.egg-info → multi_ets-0.2.0}/PKG-INFO +71 -6
  2. {multi_ets-0.1.0 → multi_ets-0.2.0}/README.md +68 -5
  3. {multi_ets-0.1.0 → multi_ets-0.2.0}/pyproject.toml +11 -1
  4. {multi_ets-0.1.0 → multi_ets-0.2.0}/src/multi_ets/_holt_hot.pyx +25 -9
  5. {multi_ets-0.1.0 → multi_ets-0.2.0}/src/multi_ets/holt.py +195 -71
  6. multi_ets-0.2.0/src/multi_ets/integrations/__init__.py +1 -0
  7. multi_ets-0.2.0/src/multi_ets/integrations/sktime.py +269 -0
  8. {multi_ets-0.1.0 → multi_ets-0.2.0}/src/multi_ets/selection.py +32 -11
  9. {multi_ets-0.1.0 → multi_ets-0.2.0/src/multi_ets.egg-info}/PKG-INFO +71 -6
  10. {multi_ets-0.1.0 → multi_ets-0.2.0}/src/multi_ets.egg-info/SOURCES.txt +4 -1
  11. {multi_ets-0.1.0 → multi_ets-0.2.0}/src/multi_ets.egg-info/requires.txt +3 -0
  12. {multi_ets-0.1.0 → multi_ets-0.2.0}/tests/test_holt.py +229 -20
  13. {multi_ets-0.1.0 → multi_ets-0.2.0}/tests/test_holt_hot.py +45 -7
  14. {multi_ets-0.1.0 → multi_ets-0.2.0}/tests/test_seasonal_hot.py +46 -7
  15. {multi_ets-0.1.0 → multi_ets-0.2.0}/tests/test_selection.py +29 -0
  16. multi_ets-0.2.0/tests/test_sktime.py +84 -0
  17. {multi_ets-0.1.0 → multi_ets-0.2.0}/LICENSE +0 -0
  18. {multi_ets-0.1.0 → multi_ets-0.2.0}/MANIFEST.in +0 -0
  19. {multi_ets-0.1.0 → multi_ets-0.2.0}/setup.cfg +0 -0
  20. {multi_ets-0.1.0 → multi_ets-0.2.0}/setup.py +0 -0
  21. {multi_ets-0.1.0 → multi_ets-0.2.0}/src/multi_ets/__init__.py +0 -0
  22. {multi_ets-0.1.0 → multi_ets-0.2.0}/src/multi_ets/py.typed +0 -0
  23. {multi_ets-0.1.0 → multi_ets-0.2.0}/src/multi_ets.egg-info/dependency_links.txt +0 -0
  24. {multi_ets-0.1.0 → multi_ets-0.2.0}/src/multi_ets.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: multi-ets
3
- Version: 0.1.0
3
+ Version: 0.2.0
4
4
  Summary: Exponential smoothing (SES, Holt, Holt-Winters) fit by joint multi-step-ahead loss instead of one-step-ahead residuals.
5
5
  Author-email: Robert Kübler <xgarve@gmail.com>
6
6
  License-Expression: MIT-0
@@ -24,6 +24,8 @@ Description-Content-Type: text/markdown
24
24
  License-File: LICENSE
25
25
  Requires-Dist: scipy>=1.11
26
26
  Requires-Dist: numpy>=1.26
27
+ Provides-Extra: sktime
28
+ Requires-Dist: sktime>=0.39; extra == "sktime"
27
29
  Dynamic: license-file
28
30
 
29
31
  # multi-ets
@@ -100,6 +102,10 @@ forecasts = (
100
102
  .fit(y)
101
103
  .predict()
102
104
  )
105
+
106
+ # Only some horizon steps matter, e.g. days 1-3 and 7-9: trains on horizon 9, but only the
107
+ # listed steps count in the loss; predict() returns those 6 values.
108
+ forecasts = ExponentialSmoothing(h=[1, 2, 3, 7, 8, 9], trend="add").fit(y).predict()
103
109
  ```
104
110
 
105
111
  `trend` is `None` (default, no trend), `"add"`, or `"damped"`; `seasonal_period` (default `None`)
@@ -109,14 +115,26 @@ fitted parameters are in `.params_` after `fit()`.
109
115
 
110
116
  ### Prediction intervals
111
117
 
112
- Every model exposes `.predict_interval(coverage=0.9)` after fitting, returning an empirical
113
- per-horizon-step Gaussian interval built from residuals of the fitted joint loss:
118
+ Every model exposes `.predict_interval(coverage=0.9)` after fitting. Each horizon step `k` gets
119
+ the point forecast plus empirical quantiles of the step-`k` in-sample residuals (actual - forecast
120
+ over every training origin), so a biased or skewed fit gives an asymmetric interval. With fewer
121
+ than 30 residuals for a step it warns and falls back to a Gaussian with the residuals' mean and
122
+ std (see `docs/adr/0006`). In-sample residuals are optimistic; for calibrated coverage wrap the
123
+ model in sktime's `ConformalIntervals`.
114
124
 
115
125
  ```python
116
- lower, upper = ExponentialSmoothing(h=5, trend="add").fit(y).predict_interval(coverage=0.9)
126
+ model = ExponentialSmoothing(h=5, trend="add").fit(y)
127
+ lower, upper = model.predict_interval(coverage=0.9)
117
128
 
118
129
  # A list of coverages returns a {coverage: (lower, upper)} dict instead.
119
- intervals = ExponentialSmoothing(h=5, trend="add").fit(y).predict_interval(coverage=[0.5, 0.9])
130
+ intervals = model.predict_interval(coverage=[0.5, 0.9])
131
+
132
+ # Arbitrary quantiles, shape (n_steps, n_alphas).
133
+ quantiles = model.predict_quantiles([0.1, 0.5, 0.9])
134
+
135
+ # In-sample k-step-ahead predictions (first k - 1 values NaN), optionally with quantiles.
136
+ fitted = model.predict_in_sample(step=1)
137
+ fitted, quantiles = model.predict_in_sample(step=2, alphas=[0.1, 0.9])
120
138
  ```
121
139
 
122
140
  ### Model selection
@@ -155,10 +173,57 @@ an *innovations*-based (MLE) auto-selector -- a structurally different fitting p
155
173
  CONTEXT.md's "Innovations ETS" glossary entry) -- and this repo's own benchmarks compare against
156
174
  it directly.
157
175
 
176
+ ### sktime integration
177
+
178
+ ```bash
179
+ pip install "multi-ets[sktime]"
180
+ ```
181
+
182
+ `MultiETSForecaster` and `AutoMultiETSForecaster` wrap the two models as sktime forecasters, with
183
+ the same hyperparameters minus `h` (`seasonal_period` is sktime's `sp`). The `fh` passed to
184
+ `fit` sets the training horizon: its positive steps are the list `h`, so `fh=[1, 2, 3, 7, 8, 9]`
185
+ trains on just those steps. In-sample `fh` points (step <= 0) are `insample_step`-ahead
186
+ predictions (default 1). Multivariate or hierarchical `y` is fit one series at a time by sktime.
187
+
188
+ ```python
189
+ from sktime.datasets import load_airline
190
+ from sktime.forecasting.model_evaluation import evaluate
191
+ from sktime.split import ExpandingWindowSplitter
192
+
193
+ from multi_ets.integrations.sktime import MultiETSForecaster
194
+
195
+ y = load_airline() # monthly airline passengers, PeriodIndex
196
+
197
+ # Train on, and forecast, the next quarter plus months 7-9 only.
198
+ forecaster = MultiETSForecaster(
199
+ trend="damped", seasonal_period=12, seasonal_type="multiplicative"
200
+ )
201
+ forecaster.fit(y, fh=[1, 2, 3, 7, 8, 9])
202
+ y_pred = forecaster.predict()
203
+ intervals = forecaster.predict_interval(coverage=0.9)
204
+
205
+ # Rolling-origin backtest, like any other sktime forecaster.
206
+ cv = ExpandingWindowSplitter(initial_window=96, step_length=12, fh=[1, 2, 3, 7, 8, 9])
207
+ results = evaluate(forecaster, cv=cv, y=y)
208
+ print(results[["test_MeanAbsolutePercentageError", "fit_time"]].mean())
209
+ ```
210
+
211
+ For calibrated intervals, wrap it in `ConformalIntervals`. Its refits forecast every point after
212
+ the training window, so pick an `initial_window` above half the series, and give `y` a
213
+ `PeriodIndex` or `DatetimeIndex` (with a plain integer index sktime reads those points as relative
214
+ steps):
215
+
216
+ ```python
217
+ from sktime.forecasting.conformal import ConformalIntervals
218
+
219
+ conformal = ConformalIntervals(MultiETSForecaster(trend="add"), initial_window=len(y) * 2 // 3)
220
+ intervals = conformal.fit(y, fh=[1, 2, 3]).predict_interval(coverage=0.9)
221
+ ```
222
+
158
223
  ### Loss
159
224
 
160
225
  All models accept a `loss` kwarg: `"mse"` (default), `"mae"`, `"huber"` (+ `delta`), `"pinball"` (+
161
- `tau`), `"expectile"` (+ `tau`), `"logcosh"`, `"poisson"`, `"negbinom"` (+ `alpha` dispersion), or
226
+ `tau`), `"expectile"` (+ `tau`), `"logcosh"`, `"poisson"`, `"negbinom"` (+ `dispersion`), or
162
227
  `"tweedie"` (+ `p` power, `1 < p < 2`), or any callable `(y_true, y_pred) -> scalar` written in
163
228
  plain NumPy. `poisson`/`negbinom`/`tweedie` require a non-negative `y`.
164
229
 
@@ -72,6 +72,10 @@ forecasts = (
72
72
  .fit(y)
73
73
  .predict()
74
74
  )
75
+
76
+ # Only some horizon steps matter, e.g. days 1-3 and 7-9: trains on horizon 9, but only the
77
+ # listed steps count in the loss; predict() returns those 6 values.
78
+ forecasts = ExponentialSmoothing(h=[1, 2, 3, 7, 8, 9], trend="add").fit(y).predict()
75
79
  ```
76
80
 
77
81
  `trend` is `None` (default, no trend), `"add"`, or `"damped"`; `seasonal_period` (default `None`)
@@ -81,14 +85,26 @@ fitted parameters are in `.params_` after `fit()`.
81
85
 
82
86
  ### Prediction intervals
83
87
 
84
- Every model exposes `.predict_interval(coverage=0.9)` after fitting, returning an empirical
85
- per-horizon-step Gaussian interval built from residuals of the fitted joint loss:
88
+ Every model exposes `.predict_interval(coverage=0.9)` after fitting. Each horizon step `k` gets
89
+ the point forecast plus empirical quantiles of the step-`k` in-sample residuals (actual - forecast
90
+ over every training origin), so a biased or skewed fit gives an asymmetric interval. With fewer
91
+ than 30 residuals for a step it warns and falls back to a Gaussian with the residuals' mean and
92
+ std (see `docs/adr/0006`). In-sample residuals are optimistic; for calibrated coverage wrap the
93
+ model in sktime's `ConformalIntervals`.
86
94
 
87
95
  ```python
88
- lower, upper = ExponentialSmoothing(h=5, trend="add").fit(y).predict_interval(coverage=0.9)
96
+ model = ExponentialSmoothing(h=5, trend="add").fit(y)
97
+ lower, upper = model.predict_interval(coverage=0.9)
89
98
 
90
99
  # A list of coverages returns a {coverage: (lower, upper)} dict instead.
91
- intervals = ExponentialSmoothing(h=5, trend="add").fit(y).predict_interval(coverage=[0.5, 0.9])
100
+ intervals = model.predict_interval(coverage=[0.5, 0.9])
101
+
102
+ # Arbitrary quantiles, shape (n_steps, n_alphas).
103
+ quantiles = model.predict_quantiles([0.1, 0.5, 0.9])
104
+
105
+ # In-sample k-step-ahead predictions (first k - 1 values NaN), optionally with quantiles.
106
+ fitted = model.predict_in_sample(step=1)
107
+ fitted, quantiles = model.predict_in_sample(step=2, alphas=[0.1, 0.9])
92
108
  ```
93
109
 
94
110
  ### Model selection
@@ -127,10 +143,57 @@ an *innovations*-based (MLE) auto-selector -- a structurally different fitting p
127
143
  CONTEXT.md's "Innovations ETS" glossary entry) -- and this repo's own benchmarks compare against
128
144
  it directly.
129
145
 
146
+ ### sktime integration
147
+
148
+ ```bash
149
+ pip install "multi-ets[sktime]"
150
+ ```
151
+
152
+ `MultiETSForecaster` and `AutoMultiETSForecaster` wrap the two models as sktime forecasters, with
153
+ the same hyperparameters minus `h` (`seasonal_period` is sktime's `sp`). The `fh` passed to
154
+ `fit` sets the training horizon: its positive steps are the list `h`, so `fh=[1, 2, 3, 7, 8, 9]`
155
+ trains on just those steps. In-sample `fh` points (step <= 0) are `insample_step`-ahead
156
+ predictions (default 1). Multivariate or hierarchical `y` is fit one series at a time by sktime.
157
+
158
+ ```python
159
+ from sktime.datasets import load_airline
160
+ from sktime.forecasting.model_evaluation import evaluate
161
+ from sktime.split import ExpandingWindowSplitter
162
+
163
+ from multi_ets.integrations.sktime import MultiETSForecaster
164
+
165
+ y = load_airline() # monthly airline passengers, PeriodIndex
166
+
167
+ # Train on, and forecast, the next quarter plus months 7-9 only.
168
+ forecaster = MultiETSForecaster(
169
+ trend="damped", seasonal_period=12, seasonal_type="multiplicative"
170
+ )
171
+ forecaster.fit(y, fh=[1, 2, 3, 7, 8, 9])
172
+ y_pred = forecaster.predict()
173
+ intervals = forecaster.predict_interval(coverage=0.9)
174
+
175
+ # Rolling-origin backtest, like any other sktime forecaster.
176
+ cv = ExpandingWindowSplitter(initial_window=96, step_length=12, fh=[1, 2, 3, 7, 8, 9])
177
+ results = evaluate(forecaster, cv=cv, y=y)
178
+ print(results[["test_MeanAbsolutePercentageError", "fit_time"]].mean())
179
+ ```
180
+
181
+ For calibrated intervals, wrap it in `ConformalIntervals`. Its refits forecast every point after
182
+ the training window, so pick an `initial_window` above half the series, and give `y` a
183
+ `PeriodIndex` or `DatetimeIndex` (with a plain integer index sktime reads those points as relative
184
+ steps):
185
+
186
+ ```python
187
+ from sktime.forecasting.conformal import ConformalIntervals
188
+
189
+ conformal = ConformalIntervals(MultiETSForecaster(trend="add"), initial_window=len(y) * 2 // 3)
190
+ intervals = conformal.fit(y, fh=[1, 2, 3]).predict_interval(coverage=0.9)
191
+ ```
192
+
130
193
  ### Loss
131
194
 
132
195
  All models accept a `loss` kwarg: `"mse"` (default), `"mae"`, `"huber"` (+ `delta`), `"pinball"` (+
133
- `tau`), `"expectile"` (+ `tau`), `"logcosh"`, `"poisson"`, `"negbinom"` (+ `alpha` dispersion), or
196
+ `tau`), `"expectile"` (+ `tau`), `"logcosh"`, `"poisson"`, `"negbinom"` (+ `dispersion`), or
134
197
  `"tweedie"` (+ `p` power, `1 < p < 2`), or any callable `(y_true, y_pred) -> scalar` written in
135
198
  plain NumPy. `poisson`/`negbinom`/`tweedie` require a non-negative `y`.
136
199
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "multi-ets"
3
- version = "0.1.0"
3
+ version = "0.2.0"
4
4
  description = "Exponential smoothing (SES, Holt, Holt-Winters) fit by joint multi-step-ahead loss instead of one-step-ahead residuals."
5
5
  readme = "README.md"
6
6
  authors = [
@@ -29,6 +29,10 @@ dependencies = [
29
29
  "numpy>=1.26",
30
30
  ]
31
31
 
32
+ [project.optional-dependencies]
33
+ # 0.39 is the first sktime with the capability:exogenous tag the adapter sets.
34
+ sktime = ["sktime>=0.39"]
35
+
32
36
  [project.urls]
33
37
  Repository = "https://github.com/RobKuebler/multi-ets"
34
38
  Issues = "https://github.com/RobKuebler/multi-ets/issues"
@@ -47,6 +51,11 @@ benchmark = [
47
51
  "matplotlib>=3.8",
48
52
  "pandas>=2.0",
49
53
  ]
54
+ # Own group (not dev) so the core CI matrix runs without sktime; default-groups
55
+ # below still installs it locally. Mirrors the `sktime` extra.
56
+ sktime = [
57
+ "sktime>=0.39",
58
+ ]
50
59
 
51
60
  [build-system]
52
61
  # setuptools + Cython compile the `_holt_hot` extension on every install
@@ -66,6 +75,7 @@ multi_ets = ["py.typed"]
66
75
  multi_ets = ["*.pyx", "*.c"]
67
76
 
68
77
  [tool.uv]
78
+ default-groups = ["dev", "sktime"]
69
79
  # Rebuild the editable install when the Cython source or build script changes.
70
80
  cache-keys = [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "src/**/*.pyx" }]
71
81
 
@@ -28,8 +28,12 @@ Shared conventions between the two cores:
28
28
  _loss_value_np/_loss_grad_np's per-name branches:
29
29
  0 = mse, 1 = mae, 2 = huber, 3 = pinball,
30
30
  4 = poisson, 5 = negbinom, 6 = tweedie, 7 = expectile, 8 = logcosh
31
- delta/tau are only read by huber/pinball/expectile; nb_alpha/tw_p are only
32
- read by negbinom/tweedie respectively (#32). Both cores dispatch through
31
+ delta/tau are only read by huber/pinball/expectile; dispersion/tw_p are only
32
+ read by negbinom/tweedie respectively (#32).
33
+
34
+ step_weight (optional, length h): per-horizon-step weight for a list h (see
35
+ holt.py's _resolve_steps); a zero-weight step is skipped exactly like a NaN
36
+ actual, so it contributes neither loss nor gradient. Both cores dispatch through
33
37
  the same _loss_and_grad helper below.
34
38
 
35
39
  Custom callable losses are out of scope here (they stay on the NumPy path,
@@ -72,7 +76,7 @@ cdef inline double _xlogy(double x, double y):
72
76
 
73
77
  cdef inline double _loss_and_grad(
74
78
  double forecast, double true, int loss_id, double delta, double tau,
75
- double nb_alpha, double tw_p, double *g
79
+ double dispersion, double tw_p, double *g
76
80
  ):
77
81
  """loss(forecast, true) and d(loss)/d(forecast), for one (t, k) pair.
78
82
 
@@ -105,9 +109,9 @@ cdef inline double _loss_and_grad(
105
109
  mu = fmax(forecast, _BOUND_EPS)
106
110
  loss = 2.0 * (
107
111
  _xlogy(true, true / mu)
108
- - (true + 1.0 / nb_alpha) * log((1.0 + nb_alpha * true) / (1.0 + nb_alpha * mu))
112
+ - (true + 1.0 / dispersion) * log((1.0 + dispersion * true) / (1.0 + dispersion * mu))
109
113
  )
110
- g[0] = 2.0 * (mu - true) / (mu * (1.0 + nb_alpha * mu)) if forecast > _BOUND_EPS else 0.0
114
+ g[0] = 2.0 * (mu - true) / (mu * (1.0 + dispersion * mu)) if forecast > _BOUND_EPS else 0.0
111
115
  elif loss_id == 6: # tweedie deviance
112
116
  mu = fmax(forecast, _BOUND_EPS)
113
117
  loss = 2.0 * (
@@ -155,11 +159,13 @@ def objective_and_grad(
155
159
  int loss_id,
156
160
  double delta,
157
161
  double tau,
158
- double nb_alpha=1.0,
162
+ double dispersion=1.0,
159
163
  double tw_p=1.5,
160
164
  np.ndarray[np.float64_t, ndim=1] sample_weight=None,
165
+ np.ndarray[np.float64_t, ndim=1] step_weight=None,
161
166
  ):
162
167
  cdef bint has_weight = sample_weight is not None
168
+ cdef bint has_step = step_weight is not None
163
169
  cdef double alpha = params[0]
164
170
  cdef double beta = params[1]
165
171
  cdef double phi = params[2]
@@ -201,9 +207,13 @@ def objective_and_grad(
201
207
  true = y[t + k]
202
208
  if isnan(true): # zero-weight this cell (#35): mirrors _nan_actual_mask
203
209
  continue
210
+ # ponytail: 0/1 mask only (all _resolve_steps emits), multiply w by
211
+ # step_weight[k] if fractional per-step weights are ever needed.
212
+ if has_step and step_weight[k] == 0: # unrequested horizon step (list h)
213
+ continue
204
214
  w = sample_weight[t + k] if has_weight else 1.0
205
215
  forecast = levels[t] + multiplier[k] * trends[t]
206
- loss += w * _loss_and_grad(forecast, true, loss_id, delta, tau, nb_alpha, tw_p, &g)
216
+ loss += w * _loss_and_grad(forecast, true, loss_id, delta, tau, dispersion, tw_p, &g)
207
217
  d_forecast[t, k] = w * g
208
218
  weight_sum += w
209
219
  if weight_sum <= 0: # #25/#35/#39: sample_weight/NaN combo zeroed every valid cell
@@ -277,9 +287,10 @@ def seasonal_objective_and_grad(
277
287
  int loss_id,
278
288
  double delta,
279
289
  double tau,
280
- double nb_alpha=1.0,
290
+ double dispersion=1.0,
281
291
  double tw_p=1.5,
282
292
  np.ndarray[np.float64_t, ndim=1] sample_weight=None,
293
+ np.ndarray[np.float64_t, ndim=1] step_weight=None,
283
294
  ):
284
295
  """Mirrors _seasonal_states_np + _seasonal_states_bptt_grad_np +
285
296
  _seasonal_objective_and_grad.
@@ -289,6 +300,7 @@ def seasonal_objective_and_grad(
289
300
  multiplicative is a runtime flag (0/1), not a compile-time specialization.
290
301
  """
291
302
  cdef bint has_weight = sample_weight is not None
303
+ cdef bint has_step = step_weight is not None
292
304
  cdef double alpha = params[0]
293
305
  cdef double beta = params[1]
294
306
  cdef double phi = params[2]
@@ -353,6 +365,10 @@ def seasonal_objective_and_grad(
353
365
  true = y[t + k]
354
366
  if isnan(true): # zero-weight this cell (#36): mirrors _nan_actual_mask
355
367
  continue
368
+ # ponytail: 0/1 mask only (all _resolve_steps emits), multiply w by
369
+ # step_weight[k] if fractional per-step weights are ever needed.
370
+ if has_step and step_weight[k] == 0: # unrequested horizon step (list h)
371
+ continue
356
372
  w = sample_weight[t + k] if has_weight else 1.0
357
373
  trend_part_val = levels[t] + multiplier[k] * trends[t]
358
374
  j = k % m
@@ -361,7 +377,7 @@ def seasonal_objective_and_grad(
361
377
  forecast = trend_part_val * seasonal_part_val
362
378
  else:
363
379
  forecast = trend_part_val + seasonal_part_val
364
- loss += w * _loss_and_grad(forecast, true, loss_id, delta, tau, nb_alpha, tw_p, &g)
380
+ loss += w * _loss_and_grad(forecast, true, loss_id, delta, tau, dispersion, tw_p, &g)
365
381
  g *= w
366
382
  weight_sum += w
367
383