dflimit 0.4.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 (55) hide show
  1. dflimit-0.4.0/CHANGELOG.md +42 -0
  2. dflimit-0.4.0/COPYRIGHTS +31 -0
  3. dflimit-0.4.0/LICENSE +21 -0
  4. dflimit-0.4.0/MANIFEST.in +7 -0
  5. dflimit-0.4.0/PKG-INFO +163 -0
  6. dflimit-0.4.0/README.md +135 -0
  7. dflimit-0.4.0/csrc/Faddeeva.cc +2518 -0
  8. dflimit-0.4.0/csrc/Faddeeva.h +62 -0
  9. dflimit-0.4.0/csrc/dfl_api.c +283 -0
  10. dflimit-0.4.0/csrc/dfl_double.c +1191 -0
  11. dflimit-0.4.0/csrc/dfl_gen.c +1497 -0
  12. dflimit-0.4.0/csrc/dfl_gilpelaez.c +218 -0
  13. dflimit-0.4.0/csrc/dfl_lock.h +17 -0
  14. dflimit-0.4.0/csrc/dfl_mgf.c +395 -0
  15. dflimit-0.4.0/csrc/dfl_moments.c +121 -0
  16. dflimit-0.4.0/csrc/dfl_single.c +458 -0
  17. dflimit-0.4.0/csrc/dfl_special.c +130 -0
  18. dflimit-0.4.0/csrc/dfl_threads.c +79 -0
  19. dflimit-0.4.0/csrc/dfl_vmath.h +83 -0
  20. dflimit-0.4.0/csrc/dflimit.h +279 -0
  21. dflimit-0.4.0/csrc/faddeeva_shim.cpp +13 -0
  22. dflimit-0.4.0/csrc/tables.c +44735 -0
  23. dflimit-0.4.0/pyproject.toml +63 -0
  24. dflimit-0.4.0/setup.cfg +4 -0
  25. dflimit-0.4.0/setup.py +80 -0
  26. dflimit-0.4.0/src/dflimit/UPSTREAM +5 -0
  27. dflimit-0.4.0/src/dflimit/__init__.py +46 -0
  28. dflimit-0.4.0/src/dflimit/_adfmax.py +233 -0
  29. dflimit-0.4.0/src/dflimit/_coef.py +206 -0
  30. dflimit-0.4.0/src/dflimit/_engine.c +262 -0
  31. dflimit-0.4.0/src/dflimit/_lincdf.py +142 -0
  32. dflimit-0.4.0/src/dflimit/_ltratio.py +328 -0
  33. dflimit-0.4.0/src/dflimit/_region.py +110 -0
  34. dflimit-0.4.0/src/dflimit/_threads.py +60 -0
  35. dflimit-0.4.0/src/dflimit/_utils.py +147 -0
  36. dflimit-0.4.0/src/dflimit.egg-info/PKG-INFO +163 -0
  37. dflimit-0.4.0/src/dflimit.egg-info/SOURCES.txt +53 -0
  38. dflimit-0.4.0/src/dflimit.egg-info/dependency_links.txt +1 -0
  39. dflimit-0.4.0/src/dflimit.egg-info/requires.txt +4 -0
  40. dflimit-0.4.0/src/dflimit.egg-info/top_level.txt +1 -0
  41. dflimit-0.4.0/tests/conftest.py +4 -0
  42. dflimit-0.4.0/tests/helpers.py +55 -0
  43. dflimit-0.4.0/tests/ref/app_ref.txt +40 -0
  44. dflimit-0.4.0/tests/ref/contour_ref.txt +13 -0
  45. dflimit-0.4.0/tests/ref/dbl_ref.txt +29 -0
  46. dflimit-0.4.0/tests/ref/fixed_ref.txt +13 -0
  47. dflimit-0.4.0/tests/ref/gen_ref.txt +31 -0
  48. dflimit-0.4.0/tests/ref/mom_ref.txt +25 -0
  49. dflimit-0.4.0/tests/ref/single_ref.txt +95 -0
  50. dflimit-0.4.0/tests/test_coef.py +63 -0
  51. dflimit-0.4.0/tests/test_docs.py +13 -0
  52. dflimit-0.4.0/tests/test_interface.py +235 -0
  53. dflimit-0.4.0/tests/test_published.py +40 -0
  54. dflimit-0.4.0/tests/test_reference.py +177 -0
  55. dflimit-0.4.0/tools/sync-engine.sh +54 -0
@@ -0,0 +1,42 @@
1
+ # Changelog
2
+
3
+ ## 0.4.0
4
+
5
+ - The documentation and the comments refer to the representations by name (the line integral, the contour integral
6
+ and the conditional integral representation) instead of by the paper's theorem and equation numbers. The results are
7
+ unchanged.
8
+ - The C engine is now copied from dflimit-matlab, the repository of the MATLAB package, which holds the C engine since
9
+ it left the paper's repository (`tools/sync-engine.sh /path/to/dflimit-matlab`); the sources are unchanged.
10
+
11
+ ## 0.3.0
12
+
13
+ - Every value is now one evaluation by one method by default: no second evaluation, no refinement driven by an error
14
+ estimate, no fallback to another representation and no recomputation of the tails. `"auto"` takes at each point the
15
+ fastest representation that one evaluation gives to well below 1e-5 (the Notes of `ltratio_cdf`). The new argument
16
+ `verified=True` of `ltratio_cdf`, `ltratio_pdf`, `ltratio_icdf`, `coef_cdf` and `coef_icdf` gives the checked
17
+ computation of before (error estimates, the agreement of two evaluations, the fallbacks and the recomputation of the
18
+ tails), and reproduces the values of before. Where the parameters lie in a regime in which one evaluation is known to
19
+ be brittle (with the conditional integral: a zero start with `c0 > 0` below the unit root, case DK with `c0 != 0` for
20
+ `c > -5`, case SK for `c > -0.5`, `c < -100` with a zero start and `c < -50` with a stationary one, a fixed start below
21
+ `c = -20` in case DK and `c = -30` in cases DU, DT; with the contour integral: `c0 > 0` for `c < -15`, `c0 < 0` for
22
+ `c > 1`, and in case DU `c0 > 3` for `c > 1.5`) a `RuntimeWarning` names the regime, once per call. Away from these
23
+ regimes the default values agree with the verified ones to well below 1e-5 (to 5e-9 at the reference points of the
24
+ contour integral).
25
+ - A third representation, the contour integral (`method="contour"`), for a fixed start `g0 != 0` in cases DU and DT:
26
+ a double integral from the inversion formula of the paper on paths around the singularities of the moment
27
+ generating function, with the integral over v in closed form, the paths in s around the roots of the determinant and a hyperbola in t, an explicit integrand where the line
28
+ integral needs the noncentral kernel, itself an integral. `"auto"` takes it there (one evaluation takes 5 to 12 ms a value on ten threads, against 8 to 89 ms for the line integral with its noncentral kernel and 0.24 to 0.28 s for the conditional integral), except for `c > 1` with `c0 < 0` and, in case DU,
29
+ for `c > 1.5` with `c0 > 3`, where it fails and the conditional integral serves. Where the line integral was
30
+ accurate the values change by at most 4e-13 (3.5e-10 at the corner `(c g0)^2/2 = 7200` of case DT, where the line
31
+ integral is the less accurate); with `c0 > 0` at `c` below about -60 the line integral, which `"auto"` took before,
32
+ is wrong (`ltratio_cdf` gave values up to 1e83 there), and the values are now right. `method="contour"` elsewhere
33
+ raises a `ValueError`.
34
+ - The moments of case DK with a fixed start (`ltratio_mom`) were NaN below `c` of about -280 (a factor of the moment
35
+ generating function overflowed); it is now computed in a form that stays finite.
36
+ - The C engine re-synced from DF-Limit (November 2026). The power envelope of the trend case,
37
+ `power_envelope(c, "DG")`, uses the weight `a = c^2/(2 (c - 1))` of the point-optimal invariant test of Elliott,
38
+ Rothenberg and Stock (it used `c/2`, the weight of case DK; the curve rises by at most 3e-5). With a stationary
39
+ start the functions raise a `ValueError` for `c > -1e-4`, where the variance `-1/(2c)` of the start is too large
40
+ for the quadrature. In case SK the conditional integral no longer cuts off the mass of `V` near zero as `c` tends
41
+ to zero: the coefficient statistic of case SK was off by up to 1e-3 for `c` between -0.01 and 0
42
+ (`coef_cdf(-8.039, "SK", -0.001)` gave 6e-6 for 0.0010438).
@@ -0,0 +1,31 @@
1
+ dflimit (Python): copyright and licences
2
+
3
+ The package (the Python code, the gateway src/dflimit/_engine.c, the C engine in csrc/ other than the files below,
4
+ tests and documentation):
5
+ Copyright (c) 2026 Yong Bao, Simon A. Broda and Raymond Kan
6
+ MIT License (see the file LICENSE of the package and https://opensource.org/license/mit).
7
+ The C engine is copied from the dflimit-matlab repository (directory c/) by tools/sync-engine.sh; the upstream
8
+ commit is recorded in the file src/dflimit/UPSTREAM.
9
+
10
+ csrc/Faddeeva.cc, csrc/Faddeeva.h (Faddeeva.hh upstream): the Faddeeva package (http://ab-initio.mit.edu/Faddeeva),
11
+ by Steven G. Johnson, Massachusetts Institute of Technology.
12
+ Copyright (c) 2012 Massachusetts Institute of Technology
13
+
14
+ Permission is hereby granted, free of charge, to any person obtaining
15
+ a copy of this software and associated documentation files (the
16
+ "Software"), to deal in the Software without restriction, including
17
+ without limitation the rights to use, copy, modify, merge, publish,
18
+ distribute, sublicense, and/or sell copies of the Software, and to
19
+ permit persons to whom the Software is furnished to do so, subject to
20
+ the following conditions:
21
+
22
+ The above copyright notice and this permission notice shall be
23
+ included in all copies or substantial portions of the Software.
24
+
25
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
26
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
28
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
29
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
30
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
31
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
dflimit-0.4.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Yong Bao, Simon A. Broda and Raymond Kan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,7 @@
1
+ # the sdist: the C engine (csrc/), the gateway, the tests with their reference files, the sync script
2
+ include README.md CHANGELOG.md LICENSE COPYRIGHTS setup.py pyproject.toml
3
+ recursive-include csrc *.c *.h *.cc *.cpp
4
+ include src/dflimit/_engine.c src/dflimit/UPSTREAM
5
+ include tests/*.py
6
+ include tests/ref/*.txt
7
+ include tools/sync-engine.sh
dflimit-0.4.0/PKG-INFO ADDED
@@ -0,0 +1,163 @@
1
+ Metadata-Version: 2.4
2
+ Name: dflimit
3
+ Version: 0.4.0
4
+ Summary: Exact limiting distribution of the Dickey-Fuller t-ratio
5
+ Author: Yong Bao, Raymond Kan
6
+ Author-email: "Simon A. Broda" <simon.broda@hslu.ch>
7
+ Maintainer-email: "Simon A. Broda" <simon.broda@hslu.ch>
8
+ License-Expression: MIT
9
+ Project-URL: Homepage, https://github.com/s-broda/dflimit-py
10
+ Project-URL: Source, https://github.com/s-broda/dflimit-py
11
+ Project-URL: R package, https://github.com/s-broda/dflimit
12
+ Keywords: unit root,Dickey-Fuller,local alternatives,limiting distribution,econometrics
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Programming Language :: C
16
+ Classifier: Programming Language :: C++
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
20
+ Requires-Python: >=3.9
21
+ Description-Content-Type: text/markdown
22
+ License-File: LICENSE
23
+ License-File: COPYRIGHTS
24
+ Requires-Dist: numpy
25
+ Provides-Extra: test
26
+ Requires-Dist: pytest; extra == "test"
27
+ Dynamic: license-file
28
+
29
+ # dflimit
30
+
31
+ The exact limiting distribution of the Dickey-Fuller t-ratio in Python.
32
+
33
+ `dflimit` computes the distribution function, density, quantiles and moments of the limits of the Dickey-Fuller
34
+ t-ratios under local alternatives, phi = 1 + c/n, by the exact representations of
35
+
36
+ > Bao, Y., Broda, S. A. and Kan, R., "The Exact Limiting Distribution of the Dickey-Fuller t-Ratio and Some Related
37
+ > Statistics", working paper.
38
+
39
+ for the regression without deterministic terms, with an intercept and with an intercept and a trend; with a zero,
40
+ a fixed or a stationary initial observation; for the t-ratio centred at the unit root or at a local null value c0;
41
+ and for the GLS-detrended trend case of Elliott, Rothenberg and Stock (1996). It also has the ADFmax test of
42
+ Leybourne (1995), the probabilities of regions {U <= g(V)} of the limit experiment (point-optimal and
43
+ weighted-average-power tests), the distribution of the linear form U - aV and the asymptotic power envelope of
44
+ Elliott, Rothenberg and Stock. The numbers come from the multithreaded C engine of the paper (a port of its Julia
45
+ reference implementation, checked against it to 1e-10 or better); the same functions, with the same names and
46
+ arguments, exist in R, MATLAB and Julia.
47
+
48
+ | function | computes |
49
+ |---|---|
50
+ | `ltratio_cdf(x, cas, c=0, c0=0, g0=0, method="auto")` | distribution function P[t <= x] of the limit |
51
+ | `ltratio_pdf(x, cas, c=0, c0=0, g0=0, method="auto")` | its density |
52
+ | `ltratio_icdf(p, cas, c=0, c0=0, g0=0, method="auto", tol=1e-10)` | quantiles (asymptotic critical values) |
53
+ | `ltratio_mom(p, cas, c=0, c0=0, g0=0)` | moments E[t^j], j = 1..p |
54
+ | `coef_cdf(y, cas, c, c0, g0, method)`, `coef_icdf(p, ...)` | the coefficient statistic n(phi^ - phi0) |
55
+ | `adfmax_cdf`, `adfmax_pdf`, `adfmax_icdf` | the ADFmax statistic (cases DU, DT, SU, ST) |
56
+ | `ltratio_region(bnd, "DK", c)` | P{U <= g(V)} for a line, the parabola of the t-ratio, the WAP boundary |
57
+ | `ltratio_lincdf(b, a, cas, c=0, cbar=-13.5)` | P(U - aV <= b), cases DK and DG (a = nan: P(V <= b)) |
58
+ | `power_envelope(c, cas="DK", alpha=0.05)` | the asymptotic power envelope of Elliott, Rothenberg and Stock (cases DK, DU, DG) |
59
+ | `ltratio_threads(n)` | the number of worker threads of the engine |
60
+
61
+ The case `cas` is a two-letter code: `D` (fixed start, `g0`, default 0) or `S` (stationary start, c <= -1e-4),
62
+ followed by `K` (no deterministic terms, tau), `U` (intercept, tau_mu) or `T` (intercept and trend, tau_tau);
63
+ `"DG"` is the GLS-detrended trend case (DF-GLS, cbar = -13.5). `method` is `"auto"` (at each point the fastest
64
+ representation that one evaluation gives to well below 1e-5), `"single"` (the line integral representation of the
65
+ paper), `"double"` (the conditional integral representation) or `"contour"`
66
+ (the contour integral representation, a fixed start in cases DU, DT only). Every
67
+ value is one evaluation by one method, with a warning where the parameters lie in a regime in which one evaluation is
68
+ known to be brittle; `verified=True` gives the checked computation (error estimates and fallbacks). The
69
+ boundary `bnd` of `ltratio_region` is a dict: `{"type": "line", "a": a, "b": b}`, `{"type": "parabola", "x": x,
70
+ "c0": c0}` or `{"type": "wap", "k": k, "omega": omega}`, with the optional keys `"v0"` and `"brks"`.
71
+
72
+ A scalar argument gives a float and an array (or a list) a NumPy array of the same shape; `info=True` gives a
73
+ `Result`, a dict whose keys are also attributes (`r.q`, `r["q"]`). The help of each function (`help(ltratio_cdf)`)
74
+ has the details of the R help pages. Arguments of the wrong type raise `TypeError`, arguments out of range
75
+ `ValueError` (outside the ranges in which the programs are checked, with the engine's message), and the warnings of
76
+ the R package are `RuntimeWarning`s.
77
+
78
+ All numbers come from the C engine. `coef_cdf`, `coef_icdf` and `adfmax_icdf` have no entry point of their own
79
+ there: as in the MATLAB programs and the R package, they are short Python-level wrappers (the distribution function
80
+ of the t-ratio at 0 with a shifted local null value, and root searches on the engine's distribution functions). Not
81
+ in the package, because the C engine does not have it: the boundary type `"fun"` (any function g) of
82
+ `ltratio_region`.
83
+
84
+ ## Example
85
+
86
+ ```python
87
+ >>> from dflimit import *
88
+ >>> ltratio_icdf([0.01, 0.05, 0.10], "DU") # asymptotic critical values of tau_mu
89
+ array([-3.430353 , -2.86156886, -2.56679107])
90
+ >>> ltratio_cdf(-2.86157, "DU", -5) # limiting power of the 5% test at c = -5
91
+ 0.11651356209305042
92
+ >>> ltratio_cdf(-2.86157, "SU", -5) # the same with a stationary start
93
+ 0.12496412271251967
94
+ >>> ltratio_cdf(0, "DK", 2, c0=2) # t-ratio centred at the true value
95
+ 0.6504355619776852
96
+ >>> ltratio_cdf(-2, "DU", -5, g0=1.5) # fixed start
97
+ 0.8649772400771647
98
+ >>> ltratio_pdf(-2, "DT", -5) # density
99
+ 0.5088008223324625
100
+ >>> ltratio_mom(4, "DT") # first four moments of tau_tau
101
+ array([ -2.18135582, 5.32067592, -14.0358001 , 39.5544305 ])
102
+ >>> coef_cdf(-14.0936, "DU", -10) # power of the 5% coefficient test at c = -10
103
+ 0.45925256320730823
104
+ >>> ltratio_region({"type": "wap", "k": 3.6658, "omega": 10}) # size of the WAP test of the paper
105
+ 0.04999962283465172
106
+ >>> ltratio_lincdf(-0.2639, -3.5, "DK", -7) # power of the point-optimal test against cbar = -7 at c = -7
107
+ 0.4993815721046887
108
+ >>> power_envelope([-5, -10], "DG") # the power envelope of the trend case
109
+ array([0.11484596, 0.31005163])
110
+
111
+ ```
112
+
113
+ (The last digits can differ by rounding between machines and numbers of threads.)
114
+
115
+ The engine uses all processors by default; `ltratio_threads(n)` changes that, and so does the environment variable
116
+ `DFL_NTHREADS` (set before the first computation); `OMP_THREAD_LIMIT`, if set when the package is imported, caps the
117
+ default. The engine releases the GIL while it computes; calls from several Python threads run one after another,
118
+ each on all the worker threads.
119
+
120
+ ## Installation
121
+
122
+ `dflimit` is an ordinary Python package with a C extension (the engine is C11 and the C++ of the Faddeeva package);
123
+ it needs Python 3.9 or later and NumPy.
124
+
125
+ **From source** (needs a C and C++ compiler: the Xcode command line tools on macOS (`xcode-select --install`), the
126
+ compilers of the distribution on Linux, e.g. `build-essential`, the Microsoft C++ Build Tools on Windows):
127
+
128
+ ```sh
129
+ pip install git+https://github.com/s-broda/dflimit-py
130
+ ```
131
+
132
+ or, from a downloaded source distribution, `pip install dflimit-0.4.0.tar.gz`.
133
+
134
+ **From a wheel** (no compiler needed): the releases of the GitHub repository (the Releases page of
135
+ `s-broda/dflimit-py`) carry wheels for Linux (x86_64 and aarch64, manylinux), macOS (Apple silicon and Intel) and
136
+ Windows (x86_64). There is one wheel per platform, which serves every CPython from 3.9 on (the tag `cp39-abi3`).
137
+ Download the one for your platform and
138
+
139
+ ```sh
140
+ pip install dflimit-0.4.0-cp39-abi3-macosx_11_0_arm64.whl # macOS, Apple silicon (the name of the file you downloaded)
141
+ ```
142
+
143
+ The package is not on PyPI (yet).
144
+
145
+ The tests (`pip install pytest`, then `pytest tests` in a copy of the repository) compare the installed package with
146
+ the stored reference values of the Julia engine, as the tests of the R package do.
147
+
148
+ ## Sibling implementations
149
+
150
+ The same functions, with the same names and arguments: the R package
151
+ [`dflimit`](https://github.com/s-broda/dflimit) (the same C engine, the same tests), the MATLAB package dflimit-matlab
152
+ (the MATLAB programs, and the C engine with a MEX gateway) and the Julia package
153
+ [`DFLimit.jl`](https://github.com/s-broda/DFLimit.jl), the Julia reference implementation.
154
+
155
+ ## Licence and citation
156
+
157
+ MIT (see `LICENSE`); the Faddeeva package in `csrc/Faddeeva.cc` is by Steven G. Johnson, MIT licence (see
158
+ `COPYRIGHTS`). Please cite the paper when using the package.
159
+
160
+ The C engine in `csrc/` is copied from dflimit-matlab, the repository of the MATLAB package, which holds the C engine
161
+ (its directory `c/`), by `tools/sync-engine.sh` (the upstream commit is in `src/dflimit/UPSTREAM`, which is installed
162
+ with the package); do not edit those files here. The engine was developed in the paper's repository up to commit
163
+ b484d4f.
@@ -0,0 +1,135 @@
1
+ # dflimit
2
+
3
+ The exact limiting distribution of the Dickey-Fuller t-ratio in Python.
4
+
5
+ `dflimit` computes the distribution function, density, quantiles and moments of the limits of the Dickey-Fuller
6
+ t-ratios under local alternatives, phi = 1 + c/n, by the exact representations of
7
+
8
+ > Bao, Y., Broda, S. A. and Kan, R., "The Exact Limiting Distribution of the Dickey-Fuller t-Ratio and Some Related
9
+ > Statistics", working paper.
10
+
11
+ for the regression without deterministic terms, with an intercept and with an intercept and a trend; with a zero,
12
+ a fixed or a stationary initial observation; for the t-ratio centred at the unit root or at a local null value c0;
13
+ and for the GLS-detrended trend case of Elliott, Rothenberg and Stock (1996). It also has the ADFmax test of
14
+ Leybourne (1995), the probabilities of regions {U <= g(V)} of the limit experiment (point-optimal and
15
+ weighted-average-power tests), the distribution of the linear form U - aV and the asymptotic power envelope of
16
+ Elliott, Rothenberg and Stock. The numbers come from the multithreaded C engine of the paper (a port of its Julia
17
+ reference implementation, checked against it to 1e-10 or better); the same functions, with the same names and
18
+ arguments, exist in R, MATLAB and Julia.
19
+
20
+ | function | computes |
21
+ |---|---|
22
+ | `ltratio_cdf(x, cas, c=0, c0=0, g0=0, method="auto")` | distribution function P[t <= x] of the limit |
23
+ | `ltratio_pdf(x, cas, c=0, c0=0, g0=0, method="auto")` | its density |
24
+ | `ltratio_icdf(p, cas, c=0, c0=0, g0=0, method="auto", tol=1e-10)` | quantiles (asymptotic critical values) |
25
+ | `ltratio_mom(p, cas, c=0, c0=0, g0=0)` | moments E[t^j], j = 1..p |
26
+ | `coef_cdf(y, cas, c, c0, g0, method)`, `coef_icdf(p, ...)` | the coefficient statistic n(phi^ - phi0) |
27
+ | `adfmax_cdf`, `adfmax_pdf`, `adfmax_icdf` | the ADFmax statistic (cases DU, DT, SU, ST) |
28
+ | `ltratio_region(bnd, "DK", c)` | P{U <= g(V)} for a line, the parabola of the t-ratio, the WAP boundary |
29
+ | `ltratio_lincdf(b, a, cas, c=0, cbar=-13.5)` | P(U - aV <= b), cases DK and DG (a = nan: P(V <= b)) |
30
+ | `power_envelope(c, cas="DK", alpha=0.05)` | the asymptotic power envelope of Elliott, Rothenberg and Stock (cases DK, DU, DG) |
31
+ | `ltratio_threads(n)` | the number of worker threads of the engine |
32
+
33
+ The case `cas` is a two-letter code: `D` (fixed start, `g0`, default 0) or `S` (stationary start, c <= -1e-4),
34
+ followed by `K` (no deterministic terms, tau), `U` (intercept, tau_mu) or `T` (intercept and trend, tau_tau);
35
+ `"DG"` is the GLS-detrended trend case (DF-GLS, cbar = -13.5). `method` is `"auto"` (at each point the fastest
36
+ representation that one evaluation gives to well below 1e-5), `"single"` (the line integral representation of the
37
+ paper), `"double"` (the conditional integral representation) or `"contour"`
38
+ (the contour integral representation, a fixed start in cases DU, DT only). Every
39
+ value is one evaluation by one method, with a warning where the parameters lie in a regime in which one evaluation is
40
+ known to be brittle; `verified=True` gives the checked computation (error estimates and fallbacks). The
41
+ boundary `bnd` of `ltratio_region` is a dict: `{"type": "line", "a": a, "b": b}`, `{"type": "parabola", "x": x,
42
+ "c0": c0}` or `{"type": "wap", "k": k, "omega": omega}`, with the optional keys `"v0"` and `"brks"`.
43
+
44
+ A scalar argument gives a float and an array (or a list) a NumPy array of the same shape; `info=True` gives a
45
+ `Result`, a dict whose keys are also attributes (`r.q`, `r["q"]`). The help of each function (`help(ltratio_cdf)`)
46
+ has the details of the R help pages. Arguments of the wrong type raise `TypeError`, arguments out of range
47
+ `ValueError` (outside the ranges in which the programs are checked, with the engine's message), and the warnings of
48
+ the R package are `RuntimeWarning`s.
49
+
50
+ All numbers come from the C engine. `coef_cdf`, `coef_icdf` and `adfmax_icdf` have no entry point of their own
51
+ there: as in the MATLAB programs and the R package, they are short Python-level wrappers (the distribution function
52
+ of the t-ratio at 0 with a shifted local null value, and root searches on the engine's distribution functions). Not
53
+ in the package, because the C engine does not have it: the boundary type `"fun"` (any function g) of
54
+ `ltratio_region`.
55
+
56
+ ## Example
57
+
58
+ ```python
59
+ >>> from dflimit import *
60
+ >>> ltratio_icdf([0.01, 0.05, 0.10], "DU") # asymptotic critical values of tau_mu
61
+ array([-3.430353 , -2.86156886, -2.56679107])
62
+ >>> ltratio_cdf(-2.86157, "DU", -5) # limiting power of the 5% test at c = -5
63
+ 0.11651356209305042
64
+ >>> ltratio_cdf(-2.86157, "SU", -5) # the same with a stationary start
65
+ 0.12496412271251967
66
+ >>> ltratio_cdf(0, "DK", 2, c0=2) # t-ratio centred at the true value
67
+ 0.6504355619776852
68
+ >>> ltratio_cdf(-2, "DU", -5, g0=1.5) # fixed start
69
+ 0.8649772400771647
70
+ >>> ltratio_pdf(-2, "DT", -5) # density
71
+ 0.5088008223324625
72
+ >>> ltratio_mom(4, "DT") # first four moments of tau_tau
73
+ array([ -2.18135582, 5.32067592, -14.0358001 , 39.5544305 ])
74
+ >>> coef_cdf(-14.0936, "DU", -10) # power of the 5% coefficient test at c = -10
75
+ 0.45925256320730823
76
+ >>> ltratio_region({"type": "wap", "k": 3.6658, "omega": 10}) # size of the WAP test of the paper
77
+ 0.04999962283465172
78
+ >>> ltratio_lincdf(-0.2639, -3.5, "DK", -7) # power of the point-optimal test against cbar = -7 at c = -7
79
+ 0.4993815721046887
80
+ >>> power_envelope([-5, -10], "DG") # the power envelope of the trend case
81
+ array([0.11484596, 0.31005163])
82
+
83
+ ```
84
+
85
+ (The last digits can differ by rounding between machines and numbers of threads.)
86
+
87
+ The engine uses all processors by default; `ltratio_threads(n)` changes that, and so does the environment variable
88
+ `DFL_NTHREADS` (set before the first computation); `OMP_THREAD_LIMIT`, if set when the package is imported, caps the
89
+ default. The engine releases the GIL while it computes; calls from several Python threads run one after another,
90
+ each on all the worker threads.
91
+
92
+ ## Installation
93
+
94
+ `dflimit` is an ordinary Python package with a C extension (the engine is C11 and the C++ of the Faddeeva package);
95
+ it needs Python 3.9 or later and NumPy.
96
+
97
+ **From source** (needs a C and C++ compiler: the Xcode command line tools on macOS (`xcode-select --install`), the
98
+ compilers of the distribution on Linux, e.g. `build-essential`, the Microsoft C++ Build Tools on Windows):
99
+
100
+ ```sh
101
+ pip install git+https://github.com/s-broda/dflimit-py
102
+ ```
103
+
104
+ or, from a downloaded source distribution, `pip install dflimit-0.4.0.tar.gz`.
105
+
106
+ **From a wheel** (no compiler needed): the releases of the GitHub repository (the Releases page of
107
+ `s-broda/dflimit-py`) carry wheels for Linux (x86_64 and aarch64, manylinux), macOS (Apple silicon and Intel) and
108
+ Windows (x86_64). There is one wheel per platform, which serves every CPython from 3.9 on (the tag `cp39-abi3`).
109
+ Download the one for your platform and
110
+
111
+ ```sh
112
+ pip install dflimit-0.4.0-cp39-abi3-macosx_11_0_arm64.whl # macOS, Apple silicon (the name of the file you downloaded)
113
+ ```
114
+
115
+ The package is not on PyPI (yet).
116
+
117
+ The tests (`pip install pytest`, then `pytest tests` in a copy of the repository) compare the installed package with
118
+ the stored reference values of the Julia engine, as the tests of the R package do.
119
+
120
+ ## Sibling implementations
121
+
122
+ The same functions, with the same names and arguments: the R package
123
+ [`dflimit`](https://github.com/s-broda/dflimit) (the same C engine, the same tests), the MATLAB package dflimit-matlab
124
+ (the MATLAB programs, and the C engine with a MEX gateway) and the Julia package
125
+ [`DFLimit.jl`](https://github.com/s-broda/DFLimit.jl), the Julia reference implementation.
126
+
127
+ ## Licence and citation
128
+
129
+ MIT (see `LICENSE`); the Faddeeva package in `csrc/Faddeeva.cc` is by Steven G. Johnson, MIT licence (see
130
+ `COPYRIGHTS`). Please cite the paper when using the package.
131
+
132
+ The C engine in `csrc/` is copied from dflimit-matlab, the repository of the MATLAB package, which holds the C engine
133
+ (its directory `c/`), by `tools/sync-engine.sh` (the upstream commit is in `src/dflimit/UPSTREAM`, which is installed
134
+ with the package); do not edit those files here. The engine was developed in the paper's repository up to commit
135
+ b484d4f.