drtran 0.1.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.
- drtran-0.1.0/PKG-INFO +229 -0
- drtran-0.1.0/README.md +197 -0
- drtran-0.1.0/pyproject.toml +65 -0
- drtran-0.1.0/setup.cfg +4 -0
- drtran-0.1.0/src/drtran/__init__.py +91 -0
- drtran-0.1.0/src/drtran/__main__.py +12 -0
- drtran-0.1.0/src/drtran/aggregate.py +169 -0
- drtran-0.1.0/src/drtran/calibrate.py +299 -0
- drtran-0.1.0/src/drtran/cast.py +377 -0
- drtran-0.1.0/src/drtran/cli.py +815 -0
- drtran-0.1.0/src/drtran/diagnose.py +203 -0
- drtran-0.1.0/src/drtran/embed.py +270 -0
- drtran-0.1.0/src/drtran/estimate.py +414 -0
- drtran-0.1.0/src/drtran/evaluate.py +204 -0
- drtran-0.1.0/src/drtran/forecast.py +581 -0
- drtran-0.1.0/src/drtran/identify.py +342 -0
- drtran-0.1.0/src/drtran/irf.py +209 -0
- drtran-0.1.0/src/drtran/mcp_server.py +815 -0
- drtran-0.1.0/src/drtran/netid.py +321 -0
- drtran-0.1.0/src/drtran/network.py +141 -0
- drtran-0.1.0/src/drtran/plots.py +210 -0
- drtran-0.1.0/src/drtran/pre.py +198 -0
- drtran-0.1.0/src/drtran/report.py +137 -0
- drtran-0.1.0/src/drtran/slots.py +439 -0
- drtran-0.1.0/src/drtran.egg-info/PKG-INFO +229 -0
- drtran-0.1.0/src/drtran.egg-info/SOURCES.txt +48 -0
- drtran-0.1.0/src/drtran.egg-info/dependency_links.txt +1 -0
- drtran-0.1.0/src/drtran.egg-info/entry_points.txt +3 -0
- drtran-0.1.0/src/drtran.egg-info/requires.txt +17 -0
- drtran-0.1.0/src/drtran.egg-info/top_level.txt +1 -0
- drtran-0.1.0/tests/test_aggregate.py +142 -0
- drtran-0.1.0/tests/test_baseline_univariate.py +68 -0
- drtran-0.1.0/tests/test_cast_diagonal.py +84 -0
- drtran-0.1.0/tests/test_cli.py +294 -0
- drtran-0.1.0/tests/test_diagnose.py +175 -0
- drtran-0.1.0/tests/test_evaluate.py +215 -0
- drtran-0.1.0/tests/test_forecast.py +328 -0
- drtran-0.1.0/tests/test_homologation_c.py +155 -0
- drtran-0.1.0/tests/test_identification.py +147 -0
- drtran-0.1.0/tests/test_irf.py +151 -0
- drtran-0.1.0/tests/test_mcp_server.py +370 -0
- drtran-0.1.0/tests/test_network.py +422 -0
- drtran-0.1.0/tests/test_network_identification.py +202 -0
- drtran-0.1.0/tests/test_pre_roundtrip.py +113 -0
- drtran-0.1.0/tests/test_refactor_scale.py +115 -0
- drtran-0.1.0/tests/test_report.py +137 -0
- drtran-0.1.0/tests/test_stderr.py +289 -0
- drtran-0.1.0/tests/test_transfer.py +194 -0
- drtran-0.1.0/tests/test_walkthrough_mtram.py +109 -0
- drtran-0.1.0/tests/test_write_pre.py +122 -0
drtran-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: drtran
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Box-Jenkins transfer function models by exact maximum likelihood — the bridge from fue (univariate) to drvarma (exact VARMA likelihood)
|
|
5
|
+
Author-email: "David E. Guerrero" <davidesg@ucm.es>
|
|
6
|
+
License-Expression: GPL-2.0-or-later
|
|
7
|
+
Project-URL: Homepage, https://github.com/davidesg/drtran-python
|
|
8
|
+
Project-URL: Repository, https://github.com/davidesg/drtran-python
|
|
9
|
+
Project-URL: Issues, https://github.com/davidesg/drtran-python/issues
|
|
10
|
+
Keywords: transfer function,Box-Jenkins,time series,exact maximum likelihood,VARMA,econometrics,intervention analysis
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
Requires-Dist: numpy>=1.24
|
|
19
|
+
Requires-Dist: scipy>=1.10
|
|
20
|
+
Requires-Dist: fue>=0.1.9
|
|
21
|
+
Requires-Dist: drvarma>=0.1.3
|
|
22
|
+
Provides-Extra: mcp
|
|
23
|
+
Requires-Dist: mcp<2,>=1.2; extra == "mcp"
|
|
24
|
+
Requires-Dist: matplotlib>=3.6; extra == "mcp"
|
|
25
|
+
Requires-Dist: jinja2>=3.0; extra == "mcp"
|
|
26
|
+
Requires-Dist: drvarma>=0.1.3; extra == "mcp"
|
|
27
|
+
Provides-Extra: plots
|
|
28
|
+
Requires-Dist: matplotlib>=3.6; extra == "plots"
|
|
29
|
+
Requires-Dist: pyfug>=2.0; extra == "plots"
|
|
30
|
+
Provides-Extra: test
|
|
31
|
+
Requires-Dist: pytest>=7; extra == "test"
|
|
32
|
+
|
|
33
|
+
# drtran (Python)
|
|
34
|
+
|
|
35
|
+
**Box–Jenkins transfer function models by exact maximum likelihood.**
|
|
36
|
+
|
|
37
|
+
A Python port of [`drtran`](../drtran) (C). It is the **bridge** between two
|
|
38
|
+
programs that already work:
|
|
39
|
+
|
|
40
|
+
- **[fue]** — identifies and estimates **univariate** models (ARIMA + Box–Cox +
|
|
41
|
+
deterministics). Produces one `.pre` per series.
|
|
42
|
+
- **[drvarma]** — evaluates Mauricio's **exact VARMA likelihood** (`elf`) and
|
|
43
|
+
maximises it with factored BFGS.
|
|
44
|
+
|
|
45
|
+
drtran reads the `.pre` files already specified in fue — one output and one or
|
|
46
|
+
more inputs — and estimates them **jointly**, every parameter at once:
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
Y_t = SUM_j omega_j(B)/delta_j(B) * B^b_j * X_j,t + N_t
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## The `.pre` is the contract, not an input format
|
|
53
|
+
|
|
54
|
+
fue leaves each series' best estimated univariate model in the `.pre`; drtran
|
|
55
|
+
takes it as a seed. `.pre` and `.inp` share a format — the difference is that a
|
|
56
|
+
`.pre`'s seeds are the estimates of the last iteration. That is what makes the
|
|
57
|
+
chain **iterative and continuous**: one rung's output feeds the next.
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
fue -> .pre -> drtran (diagonal) -> residual CCFs -> .dag/.cns -> drtran (network) -> ...
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The artifacts are inspectable text files **on purpose**: the analyst's
|
|
64
|
+
intervention between rungs is part of the method (the identified network is a
|
|
65
|
+
guide, not the final one), not a limitation to be abstracted away.
|
|
66
|
+
|
|
67
|
+
## Design principle, non-negotiable
|
|
68
|
+
|
|
69
|
+
> drvarma's `elf` is used **as it is**. Not modified, not patched, not
|
|
70
|
+
> special-cased. It is the reference implementation of the exact likelihood. Any
|
|
71
|
+
> discrepancy with fue is a bug of drtran's cast, **never** of `elf`.
|
|
72
|
+
|
|
73
|
+
## The external oracle: TASTE
|
|
74
|
+
|
|
75
|
+
Everything else on this page compares the port against programs that share its
|
|
76
|
+
ancestry: fue, drvarma and drtran use literally the same `elfvarma`,
|
|
77
|
+
`qnewtopt` and `nlatools`. A defect in that common code would be invisible to
|
|
78
|
+
every battery here. And fue, being univariate, **cannot validate the transfer
|
|
79
|
+
function** — which is precisely what drtran adds.
|
|
80
|
+
|
|
81
|
+
**TASTE does not share that code.** Written by José Alberto Mauricio, directed by
|
|
82
|
+
Arthur B. Treadway and Gregorio R. Serrano (UCM, 1987–2001), it estimates
|
|
83
|
+
multi-input transfer functions by the **unconditional sum of squares with
|
|
84
|
+
backforecasting** (classical Box–Jenkins, Levenberg–Marquardt) against this
|
|
85
|
+
port's exact ML.
|
|
86
|
+
|
|
87
|
+
~/Dropbox/SRC/atws/Taste private repo: github.com/davidesg/taste-port
|
|
88
|
+
Taste/oracle/battery.py ./battery.py --datos <drtran>/tests
|
|
89
|
+
Taste/port/tools/ pre2bjd, mkdet, mktsm, tbatch, tbatch2drtran
|
|
90
|
+
|
|
91
|
+
**7 of 7 cases pass.** Verified against this port: transfer estimation
|
|
92
|
+
(omega_0 **exact**; the rest 8.5e-05 … 4.0e-03), identification by prewhitening +
|
|
93
|
+
CCF (**same (b, r, s)**), forecasting with a transfer (agreeing to five decimals
|
|
94
|
+
with the parameters fixed on both sides) and the **full canonical case** of 12
|
|
95
|
+
inputs and 15 parameters — there, also the **standard errors** to 3–4 figures,
|
|
96
|
+
which come from inverting the Hessian of **two different objective functions**.
|
|
97
|
+
|
|
98
|
+
The chain of custody is closed: TASTE's own 64-bit port was validated against the
|
|
99
|
+
1993 `TASTE.EXE` under DOSBox-X first, **303 of 305 identical lines**.
|
|
100
|
+
|
|
101
|
+
The agreement to expect is 3–4 figures, not 13 — they are different estimators.
|
|
102
|
+
A battery failure does not prove the port is wrong; it proves something changed
|
|
103
|
+
since the last time the two agreed, which is what a regression battery is for.
|
|
104
|
+
|
|
105
|
+
TASTE also corroborates, with an exact factor of 100, that the forecast standard
|
|
106
|
+
deviation lives in the **transformed** scale and is a percentage — the same
|
|
107
|
+
conclusion this port reached independently from the C's own published band. The
|
|
108
|
+
comparable function is `level_band`, not `report_forecast`.
|
|
109
|
+
|
|
110
|
+
## Validation criterion (the gate to everything else)
|
|
111
|
+
|
|
112
|
+
**Diagonal joint estimation == fue run separately.** With a diagonal structure
|
|
113
|
+
the exact likelihood factorises, so the joint fit must reproduce the sum of the
|
|
114
|
+
univariate ones. Canonical case `ES_CPI_m10` <- `WTI_ar1`:
|
|
115
|
+
|
|
116
|
+
| | phi | logL |
|
|
117
|
+
|---|---|---|
|
|
118
|
+
| ES_CPI | 0.402839 | −7.3917 |
|
|
119
|
+
| WTI | 0.299193 | −760.0326 |
|
|
120
|
+
| **sum = joint target** | | **−767.424341** |
|
|
121
|
+
|
|
122
|
+
## An example
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
import drtran
|
|
126
|
+
from drtran.cast import build_cast_spec, Link
|
|
127
|
+
from drtran.estimate import fit, unpack
|
|
128
|
+
|
|
129
|
+
Y = drtran.load_pre("ES_CPI_m10.pre") # the output
|
|
130
|
+
X = drtran.load_pre("WTI_ar1.pre") # the input
|
|
131
|
+
|
|
132
|
+
cs = build_cast_spec([Y, X], links=[Link(out=0, inp=1, b=0, r=0, s=1)])
|
|
133
|
+
f = fit(cs) # embedded by default, as in the C
|
|
134
|
+
print(f.loglik, unpack(f)["links"])
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`identify(cs, link)` proposes (b, r, s) by prewhitening and the CCF before
|
|
138
|
+
estimating. `forecast(f, L=12)` and `to_level(fc, cs, serie=0)` give the forecast
|
|
139
|
+
back in the original units.
|
|
140
|
+
|
|
141
|
+
And a **network** of transfers, with its constraints:
|
|
142
|
+
|
|
143
|
+
```python
|
|
144
|
+
from drtran import build_slots, read_cns, read_dag
|
|
145
|
+
|
|
146
|
+
cs = build_cast_spec(specs) # the m series
|
|
147
|
+
cs = build_cast_spec(specs, links=read_dag("m6.dag", cs.names))
|
|
148
|
+
slots = build_slots(cs) # the q[i,j] are born fixed at 0
|
|
149
|
+
read_cns("m6.cns", slots) # free / fix / share / x=y*z
|
|
150
|
+
f = fit(cs, slots=slots)
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
# m6.dag # m6.cns
|
|
155
|
+
EP <- EI 1 0 1 q[5,2] = free
|
|
156
|
+
EI <- EU 1 0 3 omega1[1] = omega1[0] * theta_2[B^1]
|
|
157
|
+
EU <- EC 2 0 1 omega3[0] = omega3[1] + omega3[2] + omega3[3]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## The command line
|
|
161
|
+
|
|
162
|
+
The C's own options, verbatim — a command line written for the binary runs here
|
|
163
|
+
unchanged. The executable is `drtran-py` (not `drtran`: that name belongs to the
|
|
164
|
+
C binary), and `python -m drtran` works too.
|
|
165
|
+
|
|
166
|
+
```
|
|
167
|
+
drtran-py ES_CPI_m10.pre WTI_ar1.pre -b 0 -r 0 -s 1 -V -f 6
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`-estwin E` estimates once on the first E observations, holds the parameters
|
|
171
|
+
fixed and rolls the forecast origin forward, reporting MAE / RMSE / MAPE by
|
|
172
|
+
horizon — the only way to decide **empirically** whether one specification
|
|
173
|
+
forecasts better than another, since every other figure the program prints is
|
|
174
|
+
theoretical. `-C FILE` writes the per-origin errors as CSV.
|
|
175
|
+
|
|
176
|
+
`-L` writes the SPS forecast report — **fuf's own**, so a univariate report from
|
|
177
|
+
fuf and a transfer-function report from drtran are the same page.
|
|
178
|
+
|
|
179
|
+
What is not ported yet (`-a`) is **refused with exit code 2, not
|
|
180
|
+
ignored**: a silently dropped option is how a script starts publishing numbers
|
|
181
|
+
that answer a different question.
|
|
182
|
+
|
|
183
|
+
## Status — 0.1.0b1, first beta
|
|
184
|
+
|
|
185
|
+
**Steps 0 to 7 — closed.** The input is validated field by field, the diagonal
|
|
186
|
+
cast passes the gate (−767.424341, differing by 3.9e-07 from fue's sum), both
|
|
187
|
+
transfer casts are in — by subtraction and **embedded**, the latter the default —
|
|
188
|
+
with joint estimation, the identification of (b, r, s) by prewhitening + CCF, and
|
|
189
|
+
the **network**: the `.dag`, the `.cns` slot table (fixed, shared, products and
|
|
190
|
+
linear combinations) and the non-diagonal covariance. Then the diagnostics, the
|
|
191
|
+
forecast — core and level layer — and the CLI. All homologated against the C
|
|
192
|
+
binary to ~1e-7, with tests that **relaunch it live**. **170 tests**, green,
|
|
193
|
+
and validated against the external TASTE oracle (7 of 7 cases).
|
|
194
|
+
|
|
195
|
+
Relloso's **m6** system (1997) is reproduced in full: diagonal −1709.511575 and
|
|
196
|
+
free network −1697.613401, the C's own targets.
|
|
197
|
+
|
|
198
|
+
The **network identification** (`-i`/`-g`) is there too: having read the CCFs of
|
|
199
|
+
the diagonal model's residuals, `identify_network(cs, x=f.x)` proposes the links
|
|
200
|
+
with their (b, s), the contemporaneous covariances and the pairs with feedback;
|
|
201
|
+
`write_guided` writes the draft `.dag` and `.cns`. It is a **guide**: prune by
|
|
202
|
+
exogeneity, acyclicity and how plausible the delay is before estimating.
|
|
203
|
+
|
|
204
|
+
Standard errors come from the Hessian recomputed **at the optimum** by finite
|
|
205
|
+
differences, not from the optimiser's accumulated BFGS matrix — the latter is
|
|
206
|
+
path-dependent and is never even built when the search starts at the optimum,
|
|
207
|
+
which is drtran's normal case. All 17 of the canonical case match the binary.
|
|
208
|
+
`docs/PORTE.md` §9 records why Mauricio left that call commented out, and what
|
|
209
|
+
measuring it settled.
|
|
210
|
+
|
|
211
|
+
**Everything the C does is ported**, plus `-W`, which writes the jointly
|
|
212
|
+
re-estimated univariate blocks back out as `.pre` files. Details in
|
|
213
|
+
[`TODO.md`](TODO.md).
|
|
214
|
+
|
|
215
|
+
> **[`docs/PORTE.md`](docs/PORTE.md) — the record of the process.** How it was
|
|
216
|
+
> done, which decisions are not translation and why, the homologation figures,
|
|
217
|
+
> the three defects the port found in the original (among them that **mu is the
|
|
218
|
+
> mean, not an intercept**) and the traps in comparing against the binary.
|
|
219
|
+
|
|
220
|
+
## Scope of the port
|
|
221
|
+
|
|
222
|
+
Most of the C is **not ported**, it is reused: `elfvarma` + `drvmlest` +
|
|
223
|
+
`qnewtopt` + `nlatools` are already in drvarma Python; `gnuplot_i` -> matplotlib;
|
|
224
|
+
the `.pre` reader -> `fue.load()`. That is ~5,800 of the C's 12,615 lines.
|
|
225
|
+
|
|
226
|
+
Ported: `tran_shootx.c` (the cast, 668) -> `cast.py` + `embed.py`, `diagnose.c`
|
|
227
|
+
-> `identify.py` + `diagnose.py` + `netid.py`, `forecast.c` -> `forecast.py`, and
|
|
228
|
+
`drtran.c`'s CLI/orchestration -> `cli.py` (4201 lines of C become 490 of
|
|
229
|
+
Python).
|
drtran-0.1.0/README.md
ADDED
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
# drtran (Python)
|
|
2
|
+
|
|
3
|
+
**Box–Jenkins transfer function models by exact maximum likelihood.**
|
|
4
|
+
|
|
5
|
+
A Python port of [`drtran`](../drtran) (C). It is the **bridge** between two
|
|
6
|
+
programs that already work:
|
|
7
|
+
|
|
8
|
+
- **[fue]** — identifies and estimates **univariate** models (ARIMA + Box–Cox +
|
|
9
|
+
deterministics). Produces one `.pre` per series.
|
|
10
|
+
- **[drvarma]** — evaluates Mauricio's **exact VARMA likelihood** (`elf`) and
|
|
11
|
+
maximises it with factored BFGS.
|
|
12
|
+
|
|
13
|
+
drtran reads the `.pre` files already specified in fue — one output and one or
|
|
14
|
+
more inputs — and estimates them **jointly**, every parameter at once:
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
Y_t = SUM_j omega_j(B)/delta_j(B) * B^b_j * X_j,t + N_t
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## The `.pre` is the contract, not an input format
|
|
21
|
+
|
|
22
|
+
fue leaves each series' best estimated univariate model in the `.pre`; drtran
|
|
23
|
+
takes it as a seed. `.pre` and `.inp` share a format — the difference is that a
|
|
24
|
+
`.pre`'s seeds are the estimates of the last iteration. That is what makes the
|
|
25
|
+
chain **iterative and continuous**: one rung's output feeds the next.
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
fue -> .pre -> drtran (diagonal) -> residual CCFs -> .dag/.cns -> drtran (network) -> ...
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The artifacts are inspectable text files **on purpose**: the analyst's
|
|
32
|
+
intervention between rungs is part of the method (the identified network is a
|
|
33
|
+
guide, not the final one), not a limitation to be abstracted away.
|
|
34
|
+
|
|
35
|
+
## Design principle, non-negotiable
|
|
36
|
+
|
|
37
|
+
> drvarma's `elf` is used **as it is**. Not modified, not patched, not
|
|
38
|
+
> special-cased. It is the reference implementation of the exact likelihood. Any
|
|
39
|
+
> discrepancy with fue is a bug of drtran's cast, **never** of `elf`.
|
|
40
|
+
|
|
41
|
+
## The external oracle: TASTE
|
|
42
|
+
|
|
43
|
+
Everything else on this page compares the port against programs that share its
|
|
44
|
+
ancestry: fue, drvarma and drtran use literally the same `elfvarma`,
|
|
45
|
+
`qnewtopt` and `nlatools`. A defect in that common code would be invisible to
|
|
46
|
+
every battery here. And fue, being univariate, **cannot validate the transfer
|
|
47
|
+
function** — which is precisely what drtran adds.
|
|
48
|
+
|
|
49
|
+
**TASTE does not share that code.** Written by José Alberto Mauricio, directed by
|
|
50
|
+
Arthur B. Treadway and Gregorio R. Serrano (UCM, 1987–2001), it estimates
|
|
51
|
+
multi-input transfer functions by the **unconditional sum of squares with
|
|
52
|
+
backforecasting** (classical Box–Jenkins, Levenberg–Marquardt) against this
|
|
53
|
+
port's exact ML.
|
|
54
|
+
|
|
55
|
+
~/Dropbox/SRC/atws/Taste private repo: github.com/davidesg/taste-port
|
|
56
|
+
Taste/oracle/battery.py ./battery.py --datos <drtran>/tests
|
|
57
|
+
Taste/port/tools/ pre2bjd, mkdet, mktsm, tbatch, tbatch2drtran
|
|
58
|
+
|
|
59
|
+
**7 of 7 cases pass.** Verified against this port: transfer estimation
|
|
60
|
+
(omega_0 **exact**; the rest 8.5e-05 … 4.0e-03), identification by prewhitening +
|
|
61
|
+
CCF (**same (b, r, s)**), forecasting with a transfer (agreeing to five decimals
|
|
62
|
+
with the parameters fixed on both sides) and the **full canonical case** of 12
|
|
63
|
+
inputs and 15 parameters — there, also the **standard errors** to 3–4 figures,
|
|
64
|
+
which come from inverting the Hessian of **two different objective functions**.
|
|
65
|
+
|
|
66
|
+
The chain of custody is closed: TASTE's own 64-bit port was validated against the
|
|
67
|
+
1993 `TASTE.EXE` under DOSBox-X first, **303 of 305 identical lines**.
|
|
68
|
+
|
|
69
|
+
The agreement to expect is 3–4 figures, not 13 — they are different estimators.
|
|
70
|
+
A battery failure does not prove the port is wrong; it proves something changed
|
|
71
|
+
since the last time the two agreed, which is what a regression battery is for.
|
|
72
|
+
|
|
73
|
+
TASTE also corroborates, with an exact factor of 100, that the forecast standard
|
|
74
|
+
deviation lives in the **transformed** scale and is a percentage — the same
|
|
75
|
+
conclusion this port reached independently from the C's own published band. The
|
|
76
|
+
comparable function is `level_band`, not `report_forecast`.
|
|
77
|
+
|
|
78
|
+
## Validation criterion (the gate to everything else)
|
|
79
|
+
|
|
80
|
+
**Diagonal joint estimation == fue run separately.** With a diagonal structure
|
|
81
|
+
the exact likelihood factorises, so the joint fit must reproduce the sum of the
|
|
82
|
+
univariate ones. Canonical case `ES_CPI_m10` <- `WTI_ar1`:
|
|
83
|
+
|
|
84
|
+
| | phi | logL |
|
|
85
|
+
|---|---|---|
|
|
86
|
+
| ES_CPI | 0.402839 | −7.3917 |
|
|
87
|
+
| WTI | 0.299193 | −760.0326 |
|
|
88
|
+
| **sum = joint target** | | **−767.424341** |
|
|
89
|
+
|
|
90
|
+
## An example
|
|
91
|
+
|
|
92
|
+
```python
|
|
93
|
+
import drtran
|
|
94
|
+
from drtran.cast import build_cast_spec, Link
|
|
95
|
+
from drtran.estimate import fit, unpack
|
|
96
|
+
|
|
97
|
+
Y = drtran.load_pre("ES_CPI_m10.pre") # the output
|
|
98
|
+
X = drtran.load_pre("WTI_ar1.pre") # the input
|
|
99
|
+
|
|
100
|
+
cs = build_cast_spec([Y, X], links=[Link(out=0, inp=1, b=0, r=0, s=1)])
|
|
101
|
+
f = fit(cs) # embedded by default, as in the C
|
|
102
|
+
print(f.loglik, unpack(f)["links"])
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
`identify(cs, link)` proposes (b, r, s) by prewhitening and the CCF before
|
|
106
|
+
estimating. `forecast(f, L=12)` and `to_level(fc, cs, serie=0)` give the forecast
|
|
107
|
+
back in the original units.
|
|
108
|
+
|
|
109
|
+
And a **network** of transfers, with its constraints:
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
from drtran import build_slots, read_cns, read_dag
|
|
113
|
+
|
|
114
|
+
cs = build_cast_spec(specs) # the m series
|
|
115
|
+
cs = build_cast_spec(specs, links=read_dag("m6.dag", cs.names))
|
|
116
|
+
slots = build_slots(cs) # the q[i,j] are born fixed at 0
|
|
117
|
+
read_cns("m6.cns", slots) # free / fix / share / x=y*z
|
|
118
|
+
f = fit(cs, slots=slots)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
# m6.dag # m6.cns
|
|
123
|
+
EP <- EI 1 0 1 q[5,2] = free
|
|
124
|
+
EI <- EU 1 0 3 omega1[1] = omega1[0] * theta_2[B^1]
|
|
125
|
+
EU <- EC 2 0 1 omega3[0] = omega3[1] + omega3[2] + omega3[3]
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## The command line
|
|
129
|
+
|
|
130
|
+
The C's own options, verbatim — a command line written for the binary runs here
|
|
131
|
+
unchanged. The executable is `drtran-py` (not `drtran`: that name belongs to the
|
|
132
|
+
C binary), and `python -m drtran` works too.
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
drtran-py ES_CPI_m10.pre WTI_ar1.pre -b 0 -r 0 -s 1 -V -f 6
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`-estwin E` estimates once on the first E observations, holds the parameters
|
|
139
|
+
fixed and rolls the forecast origin forward, reporting MAE / RMSE / MAPE by
|
|
140
|
+
horizon — the only way to decide **empirically** whether one specification
|
|
141
|
+
forecasts better than another, since every other figure the program prints is
|
|
142
|
+
theoretical. `-C FILE` writes the per-origin errors as CSV.
|
|
143
|
+
|
|
144
|
+
`-L` writes the SPS forecast report — **fuf's own**, so a univariate report from
|
|
145
|
+
fuf and a transfer-function report from drtran are the same page.
|
|
146
|
+
|
|
147
|
+
What is not ported yet (`-a`) is **refused with exit code 2, not
|
|
148
|
+
ignored**: a silently dropped option is how a script starts publishing numbers
|
|
149
|
+
that answer a different question.
|
|
150
|
+
|
|
151
|
+
## Status — 0.1.0b1, first beta
|
|
152
|
+
|
|
153
|
+
**Steps 0 to 7 — closed.** The input is validated field by field, the diagonal
|
|
154
|
+
cast passes the gate (−767.424341, differing by 3.9e-07 from fue's sum), both
|
|
155
|
+
transfer casts are in — by subtraction and **embedded**, the latter the default —
|
|
156
|
+
with joint estimation, the identification of (b, r, s) by prewhitening + CCF, and
|
|
157
|
+
the **network**: the `.dag`, the `.cns` slot table (fixed, shared, products and
|
|
158
|
+
linear combinations) and the non-diagonal covariance. Then the diagnostics, the
|
|
159
|
+
forecast — core and level layer — and the CLI. All homologated against the C
|
|
160
|
+
binary to ~1e-7, with tests that **relaunch it live**. **170 tests**, green,
|
|
161
|
+
and validated against the external TASTE oracle (7 of 7 cases).
|
|
162
|
+
|
|
163
|
+
Relloso's **m6** system (1997) is reproduced in full: diagonal −1709.511575 and
|
|
164
|
+
free network −1697.613401, the C's own targets.
|
|
165
|
+
|
|
166
|
+
The **network identification** (`-i`/`-g`) is there too: having read the CCFs of
|
|
167
|
+
the diagonal model's residuals, `identify_network(cs, x=f.x)` proposes the links
|
|
168
|
+
with their (b, s), the contemporaneous covariances and the pairs with feedback;
|
|
169
|
+
`write_guided` writes the draft `.dag` and `.cns`. It is a **guide**: prune by
|
|
170
|
+
exogeneity, acyclicity and how plausible the delay is before estimating.
|
|
171
|
+
|
|
172
|
+
Standard errors come from the Hessian recomputed **at the optimum** by finite
|
|
173
|
+
differences, not from the optimiser's accumulated BFGS matrix — the latter is
|
|
174
|
+
path-dependent and is never even built when the search starts at the optimum,
|
|
175
|
+
which is drtran's normal case. All 17 of the canonical case match the binary.
|
|
176
|
+
`docs/PORTE.md` §9 records why Mauricio left that call commented out, and what
|
|
177
|
+
measuring it settled.
|
|
178
|
+
|
|
179
|
+
**Everything the C does is ported**, plus `-W`, which writes the jointly
|
|
180
|
+
re-estimated univariate blocks back out as `.pre` files. Details in
|
|
181
|
+
[`TODO.md`](TODO.md).
|
|
182
|
+
|
|
183
|
+
> **[`docs/PORTE.md`](docs/PORTE.md) — the record of the process.** How it was
|
|
184
|
+
> done, which decisions are not translation and why, the homologation figures,
|
|
185
|
+
> the three defects the port found in the original (among them that **mu is the
|
|
186
|
+
> mean, not an intercept**) and the traps in comparing against the binary.
|
|
187
|
+
|
|
188
|
+
## Scope of the port
|
|
189
|
+
|
|
190
|
+
Most of the C is **not ported**, it is reused: `elfvarma` + `drvmlest` +
|
|
191
|
+
`qnewtopt` + `nlatools` are already in drvarma Python; `gnuplot_i` -> matplotlib;
|
|
192
|
+
the `.pre` reader -> `fue.load()`. That is ~5,800 of the C's 12,615 lines.
|
|
193
|
+
|
|
194
|
+
Ported: `tran_shootx.c` (the cast, 668) -> `cast.py` + `embed.py`, `diagnose.c`
|
|
195
|
+
-> `identify.py` + `diagnose.py` + `netid.py`, `forecast.c` -> `forecast.py`, and
|
|
196
|
+
`drtran.c`'s CLI/orchestration -> `cli.py` (4201 lines of C become 490 of
|
|
197
|
+
Python).
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "drtran"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Box-Jenkins transfer function models by exact maximum likelihood — the bridge from fue (univariate) to drvarma (exact VARMA likelihood)"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "GPL-2.0-or-later"
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "David E. Guerrero", email = "davidesg@ucm.es" },
|
|
14
|
+
]
|
|
15
|
+
keywords = [
|
|
16
|
+
"transfer function", "Box-Jenkins", "time series", "exact maximum likelihood",
|
|
17
|
+
"VARMA", "econometrics", "intervention analysis",
|
|
18
|
+
]
|
|
19
|
+
classifiers = [
|
|
20
|
+
"Development Status :: 4 - Beta",
|
|
21
|
+
"Intended Audience :: Science/Research",
|
|
22
|
+
"Operating System :: OS Independent",
|
|
23
|
+
"Programming Language :: Python :: 3",
|
|
24
|
+
"Topic :: Scientific/Engineering :: Mathematics",
|
|
25
|
+
]
|
|
26
|
+
dependencies = [
|
|
27
|
+
"numpy>=1.24",
|
|
28
|
+
"scipy>=1.10",
|
|
29
|
+
# >=0.1.9 for the same reason as drvarma below: every fue binary wheel before
|
|
30
|
+
# it was inert (cffi absent from the runtime dependencies).
|
|
31
|
+
"fue>=0.1.9",
|
|
32
|
+
# >=0.1.3, not 0.1.2: 0.1.2 was the first release with binary wheels but they
|
|
33
|
+
# could not LOAD -- cffi was missing from its runtime dependencies, so the
|
|
34
|
+
# extension silently degraded to the pure-Python fallback. Since drtran
|
|
35
|
+
# scores every likelihood through drvarma's compiled `elf_c`, pinning lower
|
|
36
|
+
# would let a user install the inert engine and never know.
|
|
37
|
+
"drvarma>=0.1.3",
|
|
38
|
+
]
|
|
39
|
+
|
|
40
|
+
[project.urls]
|
|
41
|
+
Homepage = "https://github.com/davidesg/drtran-python"
|
|
42
|
+
Repository = "https://github.com/davidesg/drtran-python"
|
|
43
|
+
Issues = "https://github.com/davidesg/drtran-python/issues"
|
|
44
|
+
|
|
45
|
+
[project.scripts]
|
|
46
|
+
# NOT `drtran`: that name is the C binary's on this system, and
|
|
47
|
+
# shadowing it is exactly the trap that bit `fue` once.
|
|
48
|
+
drtran-py = "drtran.cli:main"
|
|
49
|
+
mtram = "drtran.mcp_server:main" # transfer-model MCP (pip install "drtran[mcp]")
|
|
50
|
+
|
|
51
|
+
[project.optional-dependencies]
|
|
52
|
+
# mcp<2 is NOT conservatism: mcp 2.0.0 REMOVED `mcp.server.fastmcp`, which is
|
|
53
|
+
# where FastMCP lives and what this server imports. An unbounded `mcp>=1.2`
|
|
54
|
+
# resolves to 2.x on any fresh install and mtram then fails to import at all.
|
|
55
|
+
# Verified: 1.27.2 works, 2.0.0 raises ModuleNotFoundError. Lift the cap only
|
|
56
|
+
# after porting the import.
|
|
57
|
+
mcp = ["mcp>=1.2,<2", "matplotlib>=3.6", "jinja2>=3.0", "drvarma>=0.1.3"]
|
|
58
|
+
plots = ["matplotlib>=3.6", "pyfug>=2.0"]
|
|
59
|
+
test = ["pytest>=7"]
|
|
60
|
+
|
|
61
|
+
[tool.setuptools.packages.find]
|
|
62
|
+
where = ["src"]
|
|
63
|
+
|
|
64
|
+
[tool.pytest.ini_options]
|
|
65
|
+
testpaths = ["tests"]
|
drtran-0.1.0/setup.cfg
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
"""drtran — Box-Jenkins transfer function models by exact maximum likelihood.
|
|
2
|
+
|
|
3
|
+
The bridge between two programs that already work:
|
|
4
|
+
|
|
5
|
+
- **fue** identifies and estimates **univariate** models and leaves one `.pre`
|
|
6
|
+
per series.
|
|
7
|
+
- **drvarma** evaluates Mauricio's **exact VARMA likelihood** (`elf`) and
|
|
8
|
+
maximises it with factored BFGS.
|
|
9
|
+
|
|
10
|
+
drtran reads the `.pre` files, builds the parametric *cast* (parameters -> VARMA
|
|
11
|
+
structure) and lets drvarma estimate **every parameter at once**: the transfer,
|
|
12
|
+
both ARMA, the deterministics, the means and the variances.
|
|
13
|
+
|
|
14
|
+
Y_t = SUM_j omega_j(B)/delta_j(B) * B^b_j * X_j,t + N_t
|
|
15
|
+
|
|
16
|
+
Design principle, non-negotiable
|
|
17
|
+
--------------------------------
|
|
18
|
+
drvarma's `elf` is used **as it is**: not modified, not patched, not
|
|
19
|
+
special-cased. It is the reference implementation of the exact likelihood. Any
|
|
20
|
+
discrepancy with fue is a bug of drtran's cast, **never** of `elf`.
|
|
21
|
+
|
|
22
|
+
Validation criterion (the gate to everything else)
|
|
23
|
+
--------------------------------------------------
|
|
24
|
+
**Diagonal joint estimation == fue run separately.** With a diagonal structure
|
|
25
|
+
(diagonal AR/MA and covariance, no transfer) the exact likelihood factorises, so
|
|
26
|
+
the joint fit must reproduce the **sum** of the univariate ones. If it does not
|
|
27
|
+
match, the cast is wrong.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
from .aggregate import (Aggregate, forecast_aggregates, read_aggregates,
|
|
31
|
+
report_aggregates)
|
|
32
|
+
from .cast import (Link, build_cast_spec, build_sigma, cast_diagonal,
|
|
33
|
+
compute_irf, x0_from_pre)
|
|
34
|
+
from .diagnose import (Adequacy, chi_test, report_adequacy,
|
|
35
|
+
transfer_adequacy)
|
|
36
|
+
from .embed import cast_embedded, loglik_embedded, normalize_phi0
|
|
37
|
+
from .estimate import Fit, StdErrors, fit, loglik, standard_errors, unpack, x0_full
|
|
38
|
+
from .evaluate import (RollingEval, fixed_window_fit, report_rolling,
|
|
39
|
+
rolling_evaluation, truncate, write_rolling_csv)
|
|
40
|
+
from .forecast import (Forecast, error_variance, forecast,
|
|
41
|
+
forecast_mean, integrated_weights, psi_weights,
|
|
42
|
+
level_band, report_forecast, to_level,
|
|
43
|
+
variance_decomposition)
|
|
44
|
+
from .identify import (Identification, identify, prewhiten,
|
|
45
|
+
report_identification)
|
|
46
|
+
from .irf import ImpulseResponse, impulse_response, report_irf
|
|
47
|
+
from .netid import (Candidate, IdentifiedNetwork, identify_network,
|
|
48
|
+
report_network, residuals, write_guided)
|
|
49
|
+
from .network import check_acyclic, find_cycle, read_dag, write_dag
|
|
50
|
+
from .plots import plot_ccf, plot_forecast, plot_irf, prewhitened_pair, save
|
|
51
|
+
from .pre import PreSpec, check_scale, load_pre, next_pre_path, write_pre
|
|
52
|
+
from .report import build_forecast_result, write_forecast_report
|
|
53
|
+
from .slots import Slot, SlotTable, build_slots, read_cns
|
|
54
|
+
|
|
55
|
+
# Read from the installed metadata rather than repeated here: this line said
|
|
56
|
+
# "0.1.0b1" while pyproject.toml said "0.1.0", so `drtran.__version__` reported a
|
|
57
|
+
# version that had not existed for some time. Two places to change is one place
|
|
58
|
+
# too many, and the one that drifts is always the one nobody builds from.
|
|
59
|
+
try:
|
|
60
|
+
from importlib.metadata import PackageNotFoundError, version as _pkg_version
|
|
61
|
+
try:
|
|
62
|
+
__version__ = _pkg_version("drtran")
|
|
63
|
+
except PackageNotFoundError: # running from a source tree
|
|
64
|
+
__version__ = "0.0.0.dev0"
|
|
65
|
+
except ImportError: # pragma: no cover
|
|
66
|
+
__version__ = "0.0.0.dev0"
|
|
67
|
+
|
|
68
|
+
__all__ = [
|
|
69
|
+
"PreSpec", "load_pre", "check_scale", "write_pre", "next_pre_path",
|
|
70
|
+
"plot_ccf", "plot_irf", "plot_forecast", "prewhitened_pair", "save",
|
|
71
|
+
"Aggregate", "read_aggregates", "forecast_aggregates", "report_aggregates",
|
|
72
|
+
"write_forecast_report", "build_forecast_result",
|
|
73
|
+
"Link", "build_cast_spec", "build_sigma", "cast_diagonal", "compute_irf",
|
|
74
|
+
"x0_from_pre",
|
|
75
|
+
"cast_embedded", "loglik_embedded", "normalize_phi0",
|
|
76
|
+
"Adequacy", "transfer_adequacy", "report_adequacy", "chi_test",
|
|
77
|
+
"Fit", "fit", "loglik", "unpack", "x0_full",
|
|
78
|
+
"StdErrors", "standard_errors",
|
|
79
|
+
"RollingEval", "rolling_evaluation", "fixed_window_fit", "truncate",
|
|
80
|
+
"report_rolling", "write_rolling_csv",
|
|
81
|
+
"Identification", "identify", "prewhiten", "report_identification",
|
|
82
|
+
"ImpulseResponse", "impulse_response", "report_irf",
|
|
83
|
+
"Forecast", "forecast", "report_forecast", "level_band", "psi_weights",
|
|
84
|
+
"error_variance", "integrated_weights", "forecast_mean", "to_level",
|
|
85
|
+
"variance_decomposition",
|
|
86
|
+
"Candidate", "IdentifiedNetwork", "identify_network", "report_network",
|
|
87
|
+
"residuals", "write_guided",
|
|
88
|
+
"read_dag", "write_dag", "find_cycle", "check_acyclic",
|
|
89
|
+
"Slot", "SlotTable", "build_slots", "read_cns",
|
|
90
|
+
"__version__",
|
|
91
|
+
]
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
"""`python -m drtran` — the same entry point as the `drtran-py` script.
|
|
2
|
+
|
|
3
|
+
Deliberately NOT installed as `drtran`: that name belongs to the C binary on a
|
|
4
|
+
machine that has both, and shadowing it silently is how a battery starts
|
|
5
|
+
comparing a program against itself.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import sys
|
|
9
|
+
|
|
10
|
+
from .cli import main
|
|
11
|
+
|
|
12
|
+
sys.exit(main())
|