drvec 0.1.0__py3-none-any.whl

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.
drvec/data.py ADDED
@@ -0,0 +1,295 @@
1
+ """The `.pre` route: one fue model per series, read and cast by FUE.
2
+
3
+ C: `read_pre_inputs` (drvec.c:6777-6965) and `build_y2_levels` (696-765).
4
+
5
+ The reader and the univariate cast are fue's, as in drtran-python: `fue.load()`
6
+ reads each file and `fue.cast_us.cast_us_py` builds its series, at the .pre's
7
+ own parameters. drvec differs from drtran only in how it EMBEDS the model:
8
+ drtran takes fue's stationary w (step [7] of the cast, the non-stationary
9
+ operator applied); drvec works in LEVELS (it differences the nabla-Y2 block
10
+ itself, rank by rank), so it takes fue's cast of the same model with the
11
+ non-stationary operator emptied (`levels_cast`): step [6]'s
12
+
13
+ z = refactor * BoxCox(y) - det, det = sum of nu(B) I_t
14
+
15
+ (fue's regressor: `_build_indicator` on the file's own calendar and
16
+ `calcnu_py`'s impulse response), and nothing of step [7].
17
+
18
+ What is taken from each file: the series, its calendar, lambda, the rescaling
19
+ factor, the mean's value and flag (-case pre) and z. What is NOT: the
20
+ univariate ARMA (on this route drvec re-estimates the diagonal rung itself,
21
+ docs/PORT.md §4).
22
+
23
+ The component follows fue's rule, the suite's: nu(B) truncated at 40 lags for
24
+ a rational term (delta != 0), the variables summed and subtracted once (atsw-gui
25
+ lib/fuedet; fue >= 0.1.18). The oracle, drvec C 0.13, applies the same rule, so
26
+ w is the C's bit for bit; BUG-40, the C's old exact filter, is closed by
27
+ agreeing with fue (docs/PORT.md §13).
28
+
29
+ The deterministic component is kept over the common sample AND the forecast
30
+ horizon for the back-transform of the levels (bt_det, BUG-36): `Data.det_path`,
31
+ fue's `_build_xi` (the regressor fue's own forecast adds back), as drtran's
32
+ `to_level` does.
33
+
34
+ The files are lined up by DATE, on the intersection of their samples (the C's
35
+ rule, 6810-6840), which is not drvarma's ladder rule (same last date).
36
+
37
+ Refused: what fue's reader refuses, with fue's message (a type it does not
38
+ know, a malformed file); a NON-STANDARD deterministic variable (fue reads it as
39
+ a data column, the C refuses it by design: it is a transfer input, drtran's
40
+ job), with the C's message; `easter` off monthly data (fue would build a null
41
+ regressor, the C refuses it); and seasonal differences D > 0 (the C reads them
42
+ and silently applies none).
43
+ """
44
+ from __future__ import annotations
45
+
46
+ from dataclasses import dataclass, field
47
+
48
+ import numpy as np
49
+
50
+
51
+ def abs_period(year, sub, freq):
52
+ """drvec.c:6768: one index on a common calendar."""
53
+ if freq <= 1:
54
+ return int(year)
55
+ return int(year) * freq + (int(sub) - 1)
56
+
57
+
58
+ @dataclass
59
+ class RankData:
60
+ """datamat and Y2_levels for one rank (build_y2_levels, levels layout).
61
+
62
+ `dm[t][i]` (0-based t = 0..n-1) is nabla Y2_i for i < s and Y1 in levels for
63
+ i >= s; `y2[t][i]` is the Y2 level. Both as lists (for the C-order loops of
64
+ the seeds) and as arrays (for the column-wise W of the cast)."""
65
+ r: int
66
+ n: int
67
+ dm: list
68
+ y2: list
69
+ dm_np: np.ndarray
70
+ y2_np: np.ndarray
71
+
72
+
73
+ @dataclass
74
+ class Data:
75
+ """The system's LEVELS in w units, (nobs_raw, M), in the .inp's column
76
+ order: the first s series are the nabla-Y2 block, the last r the Y1 block."""
77
+ raw: np.ndarray
78
+ names: list
79
+ freq: int = 1
80
+ start: tuple = (1, 1)
81
+ files: list = field(default_factory=list)
82
+ refactors: list = field(default_factory=list)
83
+ pre_mean_free: list = field(default_factory=list) # each .pre frees its mean (Imu)
84
+ pre_mu: list = field(default_factory=list) # and its value
85
+ xl: object = None # -xpre/-xlink: xlink.Inputs (the inputs, with presample)
86
+ lambdas: list = field(default_factory=list) # each series' Box-Cox lambda
87
+ estwin: int = None # -estwin E: the fit sees rows 1..E of nabla Y (drvec.c:740)
88
+ det_src: list = field(default_factory=list) # per series: (fue Model, off) or None
89
+ _ranks: dict = field(default_factory=dict, repr=False)
90
+ ladder_cache: dict = field(default_factory=dict, repr=False)
91
+
92
+ @property
93
+ def M(self):
94
+ return self.raw.shape[1]
95
+
96
+ @property
97
+ def nobs_raw(self):
98
+ return self.raw.shape[0]
99
+
100
+ def with_raw(self, raw):
101
+ """The same system on other levels (a bootstrap replication, a rescale):
102
+ a fresh object, so its rank data and its ladder cache start empty."""
103
+ return Data(np.asarray(raw, float), list(self.names), self.freq,
104
+ self.start, list(self.files), list(self.refactors),
105
+ list(self.pre_mean_free), list(self.pre_mu),
106
+ lambdas=list(self.lambdas), det_src=list(self.det_src))
107
+
108
+ def det_path(self, i, T):
109
+ """bt_det[i][1..T] (drvec.c:6876-6882): series i's deterministic
110
+ component on the common sample and beyond, in w units, 0-based (row t
111
+ is raw observation t + 1). Zeros when the file declares none."""
112
+ src = self.det_src[i] if i < len(self.det_src) else None
113
+ if src is None:
114
+ return [0.0] * T
115
+ model, off = src
116
+ return det_path(model, off, T)
117
+
118
+ @property
119
+ def nobs(self):
120
+ """The C's nobs: the rows of nabla Y the fit sees (-estwin trims it)."""
121
+ return self.estwin if self.estwin else self.nobs_raw - 1
122
+
123
+ def at(self, r, full=False):
124
+ """build_y2_levels for rank r (cached); full=True ignores -estwin (the
125
+ rolling evaluation filters the whole sample)."""
126
+ key = r if (full is False or not self.estwin) else (r, "full")
127
+ if key in self._ranks:
128
+ return self._ranks[key]
129
+ M = self.M
130
+ s = M - r
131
+ n = self.nobs_raw - 1 if (full or not self.estwin) else self.estwin
132
+ if n < 3:
133
+ raise ValueError("the levels layout needs at least 4 observations")
134
+ raw = self.raw
135
+ dm = [[0.0] * M for _ in range(n)]
136
+ y2 = [[0.0] * s for _ in range(n)]
137
+ for t in range(n):
138
+ for i in range(s):
139
+ dm[t][i] = float(raw[t + 1, i]) - float(raw[t, i])
140
+ y2[t][i] = float(raw[t + 1, i])
141
+ for j in range(r):
142
+ dm[t][s + j] = float(raw[t + 1, s + j])
143
+ rd = RankData(r, n, dm, y2, np.array(dm, float),
144
+ np.array(y2, float) if s else np.zeros((n, 0)))
145
+ rd.xl = self.xl
146
+ rd.nobs_raw = self.nobs_raw
147
+ self._ranks[key] = rd
148
+ return rd
149
+
150
+ def first_estimated(self):
151
+ """(year, sub) of the first observation of the estimation sample
152
+ (BUG-37: one after the raw start, the first is used by the difference)."""
153
+ y, sub = self.start
154
+ # nobs_raw - nobs + 1 (drvec.c:10970): with -estwin the C counts the
155
+ # window's trim at the START, so its date is late by nobs_full - E
156
+ k = abs_period(y, sub, self.freq) + (self.nobs_raw - self.nobs)
157
+ if self.freq <= 1:
158
+ return k, 1
159
+ return k // self.freq, k % self.freq + 1
160
+
161
+
162
+
163
+
164
+ NONSTANDARD_MSG = (
165
+ " Las variables NO ESTÁNDAR no se admiten por diseño: son\n"
166
+ " una versión rudimentaria de un modelo de transferencia con\n"
167
+ " input X. Especifica esa relación como transferencia (ω/δ, b),\n"
168
+ " que es precisamente lo que drtran estima.")
169
+
170
+
171
+ def load_model(path, what="ERROR: cannot read"):
172
+ """fue.load(path) -> (ts, model), its refusals passed on with the file named.
173
+ A non-standard deterministic variable (fue's `custom`) is refused as the C
174
+ refuses it."""
175
+ import fue
176
+ try:
177
+ ts, model = fue.load(str(path))
178
+ except (ValueError, IndexError, KeyError, OSError) as e:
179
+ raise ValueError(f"{e}\n{what} {path}") from None
180
+ freq = int(ts.freq) if ts.freq else 1
181
+ for k, itv in enumerate(model.interventions):
182
+ if itv.type == "custom":
183
+ raise ValueError(f"{path}: variable determinista {k + 1} no reconocida.\n"
184
+ + NONSTANDARD_MSG)
185
+ if itv.type == "easter" and freq != 12:
186
+ # fue reads it and builds an identically null regressor (its
187
+ # _build_indicator generates easter on monthly data only); the C
188
+ # refuses it. Refused rather than carried as a term that is zero.
189
+ raise ValueError(f"{path}: variable determinista {k + 1} (easter) on data of "
190
+ f"frequency {freq}: easter is monthly only")
191
+ return ts, model
192
+
193
+
194
+ def levels_cast(model):
195
+ """fue's cast of `model` at its own parameters, with the non-stationary
196
+ operator emptied: -> (phi, theta, mu, z), z[0..nobs-1] = refactor *
197
+ BoxCox(y) - det (cast_us_py's step [6]; step [7] is the identity).
198
+
199
+ The model with d = D = 0 and no ifadf factors is built as drtran builds the
200
+ input re-differenced by its output's operator (_alt_est_specs): a copy of
201
+ fue's model with only the operator changed, `build_est_spec`, and the cast
202
+ at `_build_initial_x` (the .pre's values in fue's own parameter order).
203
+ phi and theta are fue's factors multiplied out (`_unscramble`, the
204
+ fixed-frequency AR(2)/MA(2) included), mu the mean's value whatever its
205
+ flag."""
206
+ import copy
207
+ from fue.cast_us import _build_initial_x, build_est_spec, cast_us_py
208
+ alt = copy.deepcopy(model)
209
+ alt.d, alt.D = 0, 0
210
+ alt.ifadf = [0] * len(model.ifadf) if model.ifadf else model.ifadf
211
+ spec = build_est_spec(alt)
212
+ _p, _q, phi, theta, mu, z, ifault = cast_us_py(_build_initial_x(alt), spec)
213
+ if ifault:
214
+ raise ValueError("a fixed-frequency AR(2)/MA(2) factor of the .pre has c2 >= 0: "
215
+ "fue's cast refuses it")
216
+ return [float(v) for v in phi], [float(v) for v in theta], float(mu), z
217
+
218
+
219
+ def det_path(model, off, T):
220
+ """The deterministic component of fue's `model` on the file's rows off+1 ..
221
+ off+T (its own calendar, t = 1 its first observation), beyond the sample if
222
+ needed: fue's `_build_xi` at the .pre's omegas and deltas (a step or a
223
+ trend goes on). -> list of T floats."""
224
+ from fue.forecast import _build_xi
225
+ nobs = int(model.series.nobs)
226
+ freq = int(model.series.freq) if model.series.freq else 1
227
+ horizon = max(0, off + T - nobs)
228
+ xi = _build_xi(model, nobs, freq, horizon,
229
+ [list(i.omega) for i in model.interventions],
230
+ [list(i.delta) for i in model.interventions])
231
+ return [float(v) for v in xi[1 + off:1 + off + T]]
232
+
233
+
234
+ def _check_positive(f, ts, lam):
235
+ if abs(lam - 1.0) > 1.0e-12:
236
+ for t, z in enumerate(ts.data):
237
+ if float(z) <= 0.0:
238
+ raise ValueError(f"{f} asks for a Box-Cox with lambda = {lam:g} and "
239
+ f"observation {t + 1} is {float(z):g}")
240
+
241
+
242
+ def read_pre(files):
243
+ """Read M fue files and line them up by date (read_pre_inputs)."""
244
+ if len(files) < 2:
245
+ raise ValueError(f"a VEC model needs at least two series, got {len(files)}")
246
+ series = []
247
+ freq0 = None
248
+ first = last = None
249
+ for k, f in enumerate(files):
250
+ ts, model = load_model(f)
251
+ if ts.nobs < 4:
252
+ raise ValueError(f"{f} carries {ts.nobs} observations")
253
+ freq = int(ts.freq) if ts.freq else 1
254
+ if freq0 is None:
255
+ freq0 = freq
256
+ elif freq != freq0:
257
+ raise ValueError(f"{f} has frequency {freq} and {files[0]} has {freq0}. "
258
+ "A VEC model is one\n system on one calendar; the "
259
+ "series cannot be mixed.")
260
+ if int(model.D or 0) > 0:
261
+ raise NotImplementedError(
262
+ f"{f} declares D = {model.D}: drvec differences only the nabla-Y2 "
263
+ "block, regularly; the C ignores D in silence, the port refuses it")
264
+ y, sub = ts.start
265
+ st = abs_period(y, sub if freq > 1 else 1, freq)
266
+ en = st + int(ts.nobs) - 1
267
+ first = st if first is None else max(first, st)
268
+ last = en if last is None else min(last, en)
269
+ series.append((f, ts, model, st))
270
+ if last - first + 1 < 4:
271
+ raise ValueError(f"the .pre files overlap in {last - first + 1} observation(s); "
272
+ "at least 4 are\n needed. They are lined up by DATE, not "
273
+ "by position.")
274
+ n = last - first + 1
275
+ M = len(series)
276
+ raw = np.zeros((n, M))
277
+ names, refs, mfree, mus, lams, dets = [], [], [], [], [], []
278
+ for i, (f, ts, model, st) in enumerate(series):
279
+ off = first - st
280
+ lam = float(model.boxlam)
281
+ _check_positive(f, ts, lam)
282
+ names.append(ts.name or str(f))
283
+ refs.append(float(model.refactor))
284
+ lams.append(lam)
285
+ mfree.append(bool(model.estimate_mu))
286
+ mus.append(float(model.mu0))
287
+ _phi, _theta, _mu, z = levels_cast(model)
288
+ dets.append((model, off) if model.interventions else None)
289
+ raw[:, i] = z[off:off + n]
290
+ if freq0 <= 1:
291
+ start = (first, 1)
292
+ else:
293
+ start = (first // freq0, first % freq0 + 1)
294
+ return Data(raw, names, freq0, start, [str(f) for f in files], refs, mfree, mus,
295
+ lambdas=lams, det_src=dets)