forecastscope 0.1.0__tar.gz → 0.1.1__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 (56) hide show
  1. forecastscope-0.1.1/CHANGELOG.md +14 -0
  2. {forecastscope-0.1.0/src/forecastscope.egg-info → forecastscope-0.1.1}/PKG-INFO +1 -1
  3. forecastscope-0.1.1/docs/publication-0.1.0.json +19 -0
  4. {forecastscope-0.1.0 → forecastscope-0.1.1}/docs/validation.json +4 -3
  5. {forecastscope-0.1.0 → forecastscope-0.1.1}/pyproject.toml +1 -1
  6. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/__init__.py +1 -1
  7. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/volatility.py +20 -9
  8. {forecastscope-0.1.0 → forecastscope-0.1.1/src/forecastscope.egg-info}/PKG-INFO +1 -1
  9. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope.egg-info/SOURCES.txt +1 -0
  10. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_analysis_volatility.py +26 -0
  11. forecastscope-0.1.0/CHANGELOG.md +0 -8
  12. {forecastscope-0.1.0 → forecastscope-0.1.1}/LICENSE +0 -0
  13. {forecastscope-0.1.0 → forecastscope-0.1.1}/MANIFEST.in +0 -0
  14. {forecastscope-0.1.0 → forecastscope-0.1.1}/README.md +0 -0
  15. {forecastscope-0.1.0 → forecastscope-0.1.1}/VERSION +0 -0
  16. {forecastscope-0.1.0 → forecastscope-0.1.1}/docs/boundary.md +0 -0
  17. {forecastscope-0.1.0 → forecastscope-0.1.1}/docs/extraction-source.json +0 -0
  18. {forecastscope-0.1.0 → forecastscope-0.1.1}/docs/product-parity.json +0 -0
  19. {forecastscope-0.1.0 → forecastscope-0.1.1}/docs/test-environment.json +0 -0
  20. {forecastscope-0.1.0 → forecastscope-0.1.1}/requirements-test.txt +0 -0
  21. {forecastscope-0.1.0 → forecastscope-0.1.1}/setup.cfg +0 -0
  22. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/api.py +0 -0
  23. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/combinations/__init__.py +0 -0
  24. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/combinations/context_memory.py +0 -0
  25. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/combinations/validated.py +0 -0
  26. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/__init__.py +0 -0
  27. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/autocorrelation.py +0 -0
  28. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/causality.py +0 -0
  29. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/changepoints.py +0 -0
  30. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/distribution.py +0 -0
  31. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/filters.py +0 -0
  32. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/fractal.py +0 -0
  33. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/nonlinear.py +0 -0
  34. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/seasonality.py +0 -0
  35. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/sequence.py +0 -0
  36. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/diagnostics/stationarity.py +0 -0
  37. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/forecasting.py +0 -0
  38. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope/types.py +0 -0
  39. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope.egg-info/dependency_links.txt +0 -0
  40. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope.egg-info/requires.txt +0 -0
  41. {forecastscope-0.1.0 → forecastscope-0.1.1}/src/forecastscope.egg-info/top_level.txt +0 -0
  42. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_analysis_autocorrelation.py +0 -0
  43. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_analysis_causality.py +0 -0
  44. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_analysis_changepoints.py +1 -1
  45. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_analysis_distribution.py +0 -0
  46. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_analysis_filters.py +0 -0
  47. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_analysis_fractal.py +0 -0
  48. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_analysis_nonlinear.py +0 -0
  49. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_analysis_seasonality.py +0 -0
  50. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_analysis_stationarity.py +0 -0
  51. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_diagnostic_availability.py +0 -0
  52. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_forecasters.py +0 -0
  53. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_public_api.py +0 -0
  54. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_sequence_diagnostics.py +0 -0
  55. {forecastscope-0.1.0 → forecastscope-0.1.1}/tests/test_validated_combination.py +0 -0
  56. {forecastscope-0.1.0 → forecastscope-0.1.1}/tools/check_product_parity.py +0 -0
@@ -0,0 +1,14 @@
1
+ # Changelog
2
+
3
+ ## 0.01.001 - 2026-11-11
4
+
5
+ - Return GARCH conditional volatility in source units after internal rescaling.
6
+ Fit results and volatility reports expose the estimation scale for parameters and log-likelihood.
7
+ - Derive the Box-Cox positivity shift from the observed series. An all-zero series has no positive scale and raises a clear error.
8
+
9
+ ## 0.01.000 - unreleased
10
+
11
+ - Extract finite-prefix forecasting, five-expert combinations and sequence
12
+ diagnostics with explicit originating source bindings.
13
+ - Add strict public request and forecast-output boundaries.
14
+ - Preserve numerical adversarial controls; product adoption remains pending.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: forecastscope
3
- Version: 0.1.0
3
+ Version: 0.1.1
4
4
  Summary: Finite-prefix forecasting, temporal forecast combinations and sequence diagnostics.
5
5
  Author: Felipe Santibáñez-Leal
6
6
  License-Expression: MIT
@@ -0,0 +1,19 @@
1
+ {
2
+ "state": "published registry files verified",
3
+ "version": "0.1.0",
4
+ "source_commit": "e0a65f987fbce1ee93d76f883c17d8cc6b8409da",
5
+ "workflow": 42121401755,
6
+ "verified_module_count": 19,
7
+ "distributions": [
8
+ {
9
+ "filename": "forecastscope-0.1.0-py3-none-any.whl",
10
+ "sha256": "1ad7ccd3c63edaa94c3ffb95f4c2ae06b682560cc65222b7ed76622c93b979b8",
11
+ "upload_time": "2026-11-05T22:26:12.869208Z"
12
+ },
13
+ {
14
+ "filename": "forecastscope-0.1.0.tar.gz",
15
+ "sha256": "c7fd0ddc5e6f4b441bff2d649c9122589d133220c4cd95d9a63cbfac98dfdd66",
16
+ "upload_time": "2026-11-05T22:26:14.213426Z"
17
+ }
18
+ ]
19
+ }
@@ -1,5 +1,5 @@
1
1
  {
2
- "state": "validated-local-candidate; PyPI publication and product adoption pending",
2
+ "state": "published 0.1.0; app adoption pending",
3
3
  "version": "0.1.0",
4
4
  "checks": [
5
5
  {
@@ -52,6 +52,7 @@
52
52
  ],
53
53
  "limits": [
54
54
  "These are numerical and packaging controls, not a new forecasting accuracy trial",
55
- "Linux CI, PyPI publication, app migration and its own release gates are separate"
56
- ]
55
+ "PyPI publication and Linux CI are verified separately in the publication receipt; app migration and its own release gates remain pending"
56
+ ],
57
+ "publication_receipt": "docs/publication-0.1.0.json"
57
58
  }
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "forecastscope"
7
- version = "0.1.0"
7
+ version = "0.1.1"
8
8
  description = "Finite-prefix forecasting, temporal forecast combinations and sequence diagnostics."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -1,5 +1,5 @@
1
1
  """Finite-prefix forecasts and causal historical forecast combinations."""
2
2
  from .api import METHOD_NAMES, combine, forecast
3
3
 
4
- __version__ = "0.1.0"
4
+ __version__ = "0.1.1"
5
5
  __all__ = ["METHOD_NAMES", "combine", "forecast"]
@@ -71,24 +71,30 @@ class GarchFit:
71
71
  persistence: float # sum(alpha)+sum(beta): near 1 => shocks persist (IGARCH-like)
72
72
  loglikelihood: float
73
73
  reference: str
74
+ fit_scale: float = 1.0
74
75
 
75
76
 
76
77
  def garch(x, p: int = 1, q: int = 1, vol: str = "GARCH", dist: str = "normal",
77
78
  rescale: bool = True) -> GarchFit:
78
- """Fit a GARCH(p,q) (or EGARCH/FIGARCH) conditional-variance model to the series' mean residuals."""
79
+ """Fit a GARCH-family model and return conditional volatility in the input units.
80
+
81
+ Parameters and log-likelihood use the estimation scale. The fitted input
82
+ is the original input multiplied by ``fit_scale``.
83
+ """
79
84
  from arch import arch_model
80
85
 
81
86
  a = _clean(x)
82
87
  # arch prefers series scaled to roughly unit range; rescale=True lets it handle that internally.
83
88
  model = arch_model(a, mean="Constant", vol=vol, p=p, q=q, dist=dist, rescale=rescale)
84
89
  res = model.fit(disp="off")
90
+ scale = float(res.scale)
85
91
  params = {k: float(v) for k, v in res.params.items()}
86
92
  # persistence: sum of the alpha[*] and beta[*] parameters (standard GARCH stationarity read-out)
87
93
  persistence = float(sum(v for k, v in params.items() if k.startswith(("alpha", "beta"))))
88
94
  return GarchFit(
89
95
  vol=vol, p=p, q=q, params=params,
90
- conditional_volatility=np.asarray(res.conditional_volatility, dtype=float),
91
- persistence=persistence, loglikelihood=float(res.loglikelihood),
96
+ conditional_volatility=np.asarray(res.conditional_volatility, dtype=float) / scale,
97
+ persistence=persistence, loglikelihood=float(res.loglikelihood), fit_scale=scale,
92
98
  reference="Bollerslev 1986, J. Econometrics 31(3):307-327, DOI 10.1016/0304-4076(86)90063-1",
93
99
  )
94
100
 
@@ -105,12 +111,16 @@ class BoxCoxResult:
105
111
 
106
112
 
107
113
  def _positive_shift(a: np.ndarray) -> tuple[np.ndarray, float]:
108
- """Box-Cox needs y > 0; shift by (1 - min) when non-positive values are present. Record the shift."""
109
- m = float(np.min(a))
110
- if m <= 0:
111
- shift = 1.0 - m
112
- return a + shift, shift
113
- return a, 0.0
114
+ """Make the smallest nonpositive input equal to a scale from the series."""
115
+ minimum = float(np.min(a))
116
+ if minimum > 0:
117
+ return a, 0.0
118
+ maximum = float(np.max(a))
119
+ reference = (maximum - minimum) or abs(minimum)
120
+ shift = reference - minimum
121
+ if not np.isfinite(shift) or shift <= 0 or maximum > np.finfo(float).max - shift:
122
+ raise ValueError("Box-Cox needs a representable positive scale for nonpositive inputs")
123
+ return a + shift, shift
114
124
 
115
125
 
116
126
  def box_cox(x, method: str = "mle", season_length: int | None = None) -> BoxCoxResult:
@@ -179,6 +189,7 @@ def volatility_report(x, arch_lags: int = 12, season_length: int | None = None,
179
189
  g = garch(a, p=garch_pq[0], q=garch_pq[1])
180
190
  out["garch"] = {"vol": g.vol, "p": g.p, "q": g.q, "params": g.params,
181
191
  "persistence": g.persistence, "loglikelihood": g.loglikelihood,
192
+ "fit_scale": g.fit_scale,
182
193
  "reference": g.reference}
183
194
  except Exception as exc: # noqa: BLE001
184
195
  out["garch"] = {"error": f"{type(exc).__name__}: {exc}"}
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: forecastscope
3
- Version: 0.1.0
3
+ Version: 0.1.1
4
4
  Summary: Finite-prefix forecasting, temporal forecast combinations and sequence diagnostics.
5
5
  Author: Felipe Santibáñez-Leal
6
6
  License-Expression: MIT
@@ -8,6 +8,7 @@ requirements-test.txt
8
8
  docs/boundary.md
9
9
  docs/extraction-source.json
10
10
  docs/product-parity.json
11
+ docs/publication-0.1.0.json
11
12
  docs/test-environment.json
12
13
  docs/validation.json
13
14
  src/forecastscope/__init__.py
@@ -1,5 +1,6 @@
1
1
  """Volatility toolkit tests: ARCH detection, GARCH persistence, Box-Cox variance stabilization, Guerrero."""
2
2
  import numpy as np
3
+ import pytest
3
4
 
4
5
  from forecastscope.diagnostics import volatility as vo
5
6
 
@@ -42,6 +43,17 @@ def test_garch_recovers_high_persistence():
42
43
  assert np.all(g.conditional_volatility > 0)
43
44
 
44
45
 
46
+ def test_rescaled_garch_returns_volatility_in_source_units():
47
+ from arch import arch_model
48
+
49
+ y = _garch_series() * 1e-4
50
+ native = arch_model(y, mean="Constant", p=1, q=1, rescale=True).fit(disp="off")
51
+ result = vo.garch(y)
52
+ assert native.scale != 1 and result.fit_scale == native.scale
53
+ np.testing.assert_allclose(result.conditional_volatility * native.scale, native.conditional_volatility)
54
+ assert result.params == native.params.to_dict()
55
+
56
+
45
57
  def test_boxcox_mle_stabilizes_variance():
46
58
  y = _multiplicative_growth()
47
59
  bc = vo.box_cox(y, method="mle")
@@ -67,6 +79,20 @@ def test_boxcox_handles_nonpositive_with_a_recorded_shift():
67
79
  assert np.all(np.isfinite(bc.transformed))
68
80
 
69
81
 
82
+ def test_boxcox_shift_tracks_positive_changes_in_source_unit():
83
+ y = np.array([-2., 0., 1., 3., 5., 2., 4., 6.])
84
+ original = vo.box_cox(y, method="log")
85
+ factor = 1e-5
86
+ converted = vo.box_cox(y * factor, method="log")
87
+ assert converted.shift == pytest.approx(original.shift * factor)
88
+ np.testing.assert_allclose(converted.transformed, original.transformed + np.log(factor))
89
+
90
+
91
+ def test_boxcox_rejects_zero_series_without_positive_scale():
92
+ with pytest.raises(ValueError, match="positive scale"):
93
+ vo.box_cox(np.zeros(8), method="log")
94
+
95
+
70
96
  def test_report_skips_garch_when_no_arch():
71
97
  rep = vo.volatility_report(_homoscedastic())
72
98
  assert rep["arch_lm"]["has_arch"] is False
@@ -1,8 +0,0 @@
1
- # Changelog
2
-
3
- ## 0.01.000 - unreleased
4
-
5
- - Extract finite-prefix forecasting, five-expert combinations and sequence
6
- diagnostics with explicit originating source bindings.
7
- - Add strict public request and forecast-output boundaries.
8
- - Preserve numerical adversarial controls; product adoption remains pending.
File without changes
File without changes
File without changes
File without changes
File without changes
@@ -1,6 +1,6 @@
1
+ """Change-point toolkit tests: ground truth = a series with KNOWN break locations and regimes."""
1
2
  from itertools import pairwise
2
3
 
3
- """Change-point toolkit tests: ground truth = a series with KNOWN break locations and regimes."""
4
4
  import numpy as np
5
5
 
6
6
  from forecastscope.diagnostics import changepoints as cp