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.
Files changed (50) hide show
  1. drtran-0.1.0/PKG-INFO +229 -0
  2. drtran-0.1.0/README.md +197 -0
  3. drtran-0.1.0/pyproject.toml +65 -0
  4. drtran-0.1.0/setup.cfg +4 -0
  5. drtran-0.1.0/src/drtran/__init__.py +91 -0
  6. drtran-0.1.0/src/drtran/__main__.py +12 -0
  7. drtran-0.1.0/src/drtran/aggregate.py +169 -0
  8. drtran-0.1.0/src/drtran/calibrate.py +299 -0
  9. drtran-0.1.0/src/drtran/cast.py +377 -0
  10. drtran-0.1.0/src/drtran/cli.py +815 -0
  11. drtran-0.1.0/src/drtran/diagnose.py +203 -0
  12. drtran-0.1.0/src/drtran/embed.py +270 -0
  13. drtran-0.1.0/src/drtran/estimate.py +414 -0
  14. drtran-0.1.0/src/drtran/evaluate.py +204 -0
  15. drtran-0.1.0/src/drtran/forecast.py +581 -0
  16. drtran-0.1.0/src/drtran/identify.py +342 -0
  17. drtran-0.1.0/src/drtran/irf.py +209 -0
  18. drtran-0.1.0/src/drtran/mcp_server.py +815 -0
  19. drtran-0.1.0/src/drtran/netid.py +321 -0
  20. drtran-0.1.0/src/drtran/network.py +141 -0
  21. drtran-0.1.0/src/drtran/plots.py +210 -0
  22. drtran-0.1.0/src/drtran/pre.py +198 -0
  23. drtran-0.1.0/src/drtran/report.py +137 -0
  24. drtran-0.1.0/src/drtran/slots.py +439 -0
  25. drtran-0.1.0/src/drtran.egg-info/PKG-INFO +229 -0
  26. drtran-0.1.0/src/drtran.egg-info/SOURCES.txt +48 -0
  27. drtran-0.1.0/src/drtran.egg-info/dependency_links.txt +1 -0
  28. drtran-0.1.0/src/drtran.egg-info/entry_points.txt +3 -0
  29. drtran-0.1.0/src/drtran.egg-info/requires.txt +17 -0
  30. drtran-0.1.0/src/drtran.egg-info/top_level.txt +1 -0
  31. drtran-0.1.0/tests/test_aggregate.py +142 -0
  32. drtran-0.1.0/tests/test_baseline_univariate.py +68 -0
  33. drtran-0.1.0/tests/test_cast_diagonal.py +84 -0
  34. drtran-0.1.0/tests/test_cli.py +294 -0
  35. drtran-0.1.0/tests/test_diagnose.py +175 -0
  36. drtran-0.1.0/tests/test_evaluate.py +215 -0
  37. drtran-0.1.0/tests/test_forecast.py +328 -0
  38. drtran-0.1.0/tests/test_homologation_c.py +155 -0
  39. drtran-0.1.0/tests/test_identification.py +147 -0
  40. drtran-0.1.0/tests/test_irf.py +151 -0
  41. drtran-0.1.0/tests/test_mcp_server.py +370 -0
  42. drtran-0.1.0/tests/test_network.py +422 -0
  43. drtran-0.1.0/tests/test_network_identification.py +202 -0
  44. drtran-0.1.0/tests/test_pre_roundtrip.py +113 -0
  45. drtran-0.1.0/tests/test_refactor_scale.py +115 -0
  46. drtran-0.1.0/tests/test_report.py +137 -0
  47. drtran-0.1.0/tests/test_stderr.py +289 -0
  48. drtran-0.1.0/tests/test_transfer.py +194 -0
  49. drtran-0.1.0/tests/test_walkthrough_mtram.py +109 -0
  50. 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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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())