fmbqml 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.
- fmbqml-0.1.0/LICENSE.txt +21 -0
- fmbqml-0.1.0/MANIFEST.in +7 -0
- fmbqml-0.1.0/PKG-INFO +194 -0
- fmbqml-0.1.0/README.md +136 -0
- fmbqml-0.1.0/fmbqml/__init__.py +9 -0
- fmbqml-0.1.0/fmbqml/break_tools/__init__.py +7 -0
- fmbqml-0.1.0/fmbqml/break_tools/breakpoint_classification.py +205 -0
- fmbqml-0.1.0/fmbqml/break_tools/classification_summary.py +55 -0
- fmbqml-0.1.0/fmbqml/break_tools/classify_break_types.py +401 -0
- fmbqml-0.1.0/fmbqml/factor_tools/__init__.py +11 -0
- fmbqml-0.1.0/fmbqml/factor_tools/nb_factors.py +221 -0
- fmbqml-0.1.0/fmbqml/factor_tools/panel_factor.py +35 -0
- fmbqml-0.1.0/fmbqml/factor_tools/panel_factors_lr.py +65 -0
- fmbqml-0.1.0/fmbqml/factor_tools/var_selection.py +140 -0
- fmbqml-0.1.0/fmbqml/multiple_break/__init__.py +5 -0
- fmbqml-0.1.0/fmbqml/multiple_break/eig_sort.py +66 -0
- fmbqml-0.1.0/fmbqml/multiple_break/find_min_qml.py +50 -0
- fmbqml-0.1.0/fmbqml/multiple_break/joint_estimation.py +307 -0
- fmbqml-0.1.0/fmbqml/multiple_break/joint_testing.py +141 -0
- fmbqml-0.1.0/fmbqml/multiple_break/multiple_break_qml.py +705 -0
- fmbqml-0.1.0/fmbqml/single_break/__init__.py +5 -0
- fmbqml-0.1.0/fmbqml/single_break/qml_profile.py +64 -0
- fmbqml-0.1.0/fmbqml/single_break/single_break_qml.py +642 -0
- fmbqml-0.1.0/fmbqml/statistical_tools/__init__.py +25 -0
- fmbqml-0.1.0/fmbqml/statistical_tools/brownian.py +20 -0
- fmbqml-0.1.0/fmbqml/statistical_tools/critical_values.py +461 -0
- fmbqml-0.1.0/fmbqml/statistical_tools/hac.py +85 -0
- fmbqml-0.1.0/fmbqml/utils/__init__.py +79 -0
- fmbqml-0.1.0/fmbqml/utils/breakpoint_utils.py +130 -0
- fmbqml-0.1.0/fmbqml/utils/criteria.py +83 -0
- fmbqml-0.1.0/fmbqml/utils/data_input.py +82 -0
- fmbqml-0.1.0/fmbqml/utils/formatting.py +561 -0
- fmbqml-0.1.0/fmbqml/utils/partition.py +60 -0
- fmbqml-0.1.0/fmbqml/utils/plotting.py +365 -0
- fmbqml-0.1.0/fmbqml/utils/safe_logdet.py +56 -0
- fmbqml-0.1.0/fmbqml/utils/validation.py +183 -0
- fmbqml-0.1.0/fmbqml.egg-info/PKG-INFO +194 -0
- fmbqml-0.1.0/fmbqml.egg-info/SOURCES.txt +42 -0
- fmbqml-0.1.0/fmbqml.egg-info/dependency_links.txt +1 -0
- fmbqml-0.1.0/fmbqml.egg-info/requires.txt +8 -0
- fmbqml-0.1.0/fmbqml.egg-info/top_level.txt +1 -0
- fmbqml-0.1.0/pyproject.toml +54 -0
- fmbqml-0.1.0/setup.cfg +4 -0
- fmbqml-0.1.0/setup.py +61 -0
fmbqml-0.1.0/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Liting Chen, Jiangtao Duan, Xu Han
|
|
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.
|
fmbqml-0.1.0/MANIFEST.in
ADDED
fmbqml-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fmbqml
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Structural-break detection in high-dimensional factor models using QML methods.
|
|
5
|
+
Home-page: https://github.com/JiangtaoDuan/fmbqml
|
|
6
|
+
Author: Liting Chen, Jiangtao Duan, Xu Han
|
|
7
|
+
Author-email: duanjiangtao@xidian.edu.cn
|
|
8
|
+
Maintainer: Liting Chen
|
|
9
|
+
Maintainer-email: Liting Chen <duanjiangtao@xidian.edu.cn>
|
|
10
|
+
License: MIT License
|
|
11
|
+
|
|
12
|
+
Copyright (c) 2024 Liting Chen, Jiangtao Duan, Xu Han
|
|
13
|
+
|
|
14
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
15
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
16
|
+
in the Software without restriction, including without limitation the rights
|
|
17
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
18
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
19
|
+
furnished to do so, subject to the following conditions:
|
|
20
|
+
|
|
21
|
+
The above copyright notice and this permission notice shall be included in all
|
|
22
|
+
copies or substantial portions of the Software.
|
|
23
|
+
|
|
24
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
25
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
26
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
27
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
28
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
29
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
30
|
+
SOFTWARE.
|
|
31
|
+
Project-URL: Homepage, https://github.com/JiangtaoDuan/fmbqml
|
|
32
|
+
Project-URL: Repository, https://github.com/JiangtaoDuan/fmbqml
|
|
33
|
+
Project-URL: Issues, https://github.com/JiangtaoDuan/fmbqml/issues
|
|
34
|
+
Keywords: factor models,structural breaks,QML,high-dimensional data
|
|
35
|
+
Classifier: Intended Audience :: Science/Research
|
|
36
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
37
|
+
Classifier: Programming Language :: Python :: 3
|
|
38
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
39
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
40
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
41
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
42
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
43
|
+
Classifier: Operating System :: OS Independent
|
|
44
|
+
Requires-Python: >=3.8
|
|
45
|
+
Description-Content-Type: text/markdown
|
|
46
|
+
License-File: LICENSE.txt
|
|
47
|
+
Requires-Dist: numpy>=1.21.6
|
|
48
|
+
Requires-Dist: scipy>=1.7.3
|
|
49
|
+
Requires-Dist: pandas>=1.3.5
|
|
50
|
+
Requires-Dist: matplotlib>=3.5.0
|
|
51
|
+
Requires-Dist: joblib>=1.1.0
|
|
52
|
+
Requires-Dist: importlib_resources; python_version < "3.9"
|
|
53
|
+
Dynamic: author-email
|
|
54
|
+
Dynamic: home-page
|
|
55
|
+
Dynamic: license-file
|
|
56
|
+
Dynamic: maintainer
|
|
57
|
+
Dynamic: requires-python
|
|
58
|
+
|
|
59
|
+
# fmbqml: Structural Break Analysis in High-Dimensional Factor Models
|
|
60
|
+
|
|
61
|
+
[](https://www.python.org/)
|
|
62
|
+
[](https://github.com/JiangtaoDuan/fmbqml/blob/master/LICENSE.txt)
|
|
63
|
+
|
|
64
|
+
`fmbqml` is a Python package for quasi-maximum-likelihood analysis of
|
|
65
|
+
structural breaks in high-dimensional factor models. It provides tools for
|
|
66
|
+
single-break testing and estimation, joint multiple-break estimation, sup-LR
|
|
67
|
+
testing, factor-number selection, break-type classification, and diagnostic
|
|
68
|
+
plots.
|
|
69
|
+
|
|
70
|
+
## Links
|
|
71
|
+
|
|
72
|
+
- [Source code](https://github.com/JiangtaoDuan/fmbqml)
|
|
73
|
+
- [Issue tracker](https://github.com/JiangtaoDuan/fmbqml/issues)
|
|
74
|
+
|
|
75
|
+
## Installation
|
|
76
|
+
|
|
77
|
+
Install the package from PyPI with:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
python -m pip install fmbqml
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
For development from a source checkout, use:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
python -m pip install -e .
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Input data
|
|
90
|
+
|
|
91
|
+
The input data should be a finite two-dimensional NumPy array or pandas
|
|
92
|
+
DataFrame with observations in rows and variables in columns. Missing values
|
|
93
|
+
should be imputed before constructing a model.
|
|
94
|
+
|
|
95
|
+
## Single-break analysis
|
|
96
|
+
|
|
97
|
+
Assuming that `panel_data` contains the input panel dataset:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
from fmbqml import SingleBreakQML
|
|
101
|
+
|
|
102
|
+
model = SingleBreakQML(
|
|
103
|
+
panel_data,
|
|
104
|
+
trim_ratio=0.15,
|
|
105
|
+
max_factors=10,
|
|
106
|
+
factor_criterion="IC2",
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
result = model.lr_test(
|
|
110
|
+
alpha=0.05,
|
|
111
|
+
classify=True,
|
|
112
|
+
n_sim=5000,
|
|
113
|
+
random_state=12345,
|
|
114
|
+
)
|
|
115
|
+
|
|
116
|
+
print(result["reject_null"])
|
|
117
|
+
print(result["break_point"])
|
|
118
|
+
print(result.get("break_type"))
|
|
119
|
+
```
|
|
120
|
+
Use `estimate_breakpoint()` when a break is assumed to exist and significance
|
|
121
|
+
testing is not required. In `lr_test()`, `break_point` is returned when the
|
|
122
|
+
no-break null is rejected, while `estimated_break_candidate` records the
|
|
123
|
+
profile optimizer.
|
|
124
|
+
|
|
125
|
+
## Multiple-break analysis
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
from fmbqml import MultiBreakQML
|
|
129
|
+
|
|
130
|
+
model = MultiBreakQML(
|
|
131
|
+
panel_data,
|
|
132
|
+
max_break=5,
|
|
133
|
+
max_factors=8,
|
|
134
|
+
factor_criterion="IC2",
|
|
135
|
+
trim_ratio=0.10,
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
result = model.estimate_breaks_jointly(
|
|
139
|
+
min_break=0,
|
|
140
|
+
classify=True,
|
|
141
|
+
)
|
|
142
|
+
|
|
143
|
+
print(result["n_breaks"])
|
|
144
|
+
print(result["breakpoints"])
|
|
145
|
+
print(result.get("break_types"))
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
The option `min_break=0` permits selection of a no-break model. Use
|
|
149
|
+
`joint_sup_lr_test(n_breaks=...)` to test no structural change against an exact
|
|
150
|
+
number of breaks.
|
|
151
|
+
|
|
152
|
+
## Factor-number selection
|
|
153
|
+
|
|
154
|
+
`factor_criterion` accepts `IC1`, `IC2`, `IC3`, `PC1`, `PC2`, `PC3`, `AIC3`,
|
|
155
|
+
or `BIC3`. Integer indices `0` through `7` are also accepted in that order.
|
|
156
|
+
The argument `max_factors` is a search bound and should be smaller than
|
|
157
|
+
`min(T, N)`.
|
|
158
|
+
|
|
159
|
+
## Results and model state
|
|
160
|
+
|
|
161
|
+
Result dictionaries contain NumPy arrays for available profiles and nested
|
|
162
|
+
structures for breakpoint classifications and information-criterion paths.
|
|
163
|
+
For example, single-break procedures store candidate break locations together
|
|
164
|
+
with LR or QML profile values, while multiple-break joint estimation stores
|
|
165
|
+
the selected breakpoints and the information-criterion path used to choose the
|
|
166
|
+
number of breaks.
|
|
167
|
+
|
|
168
|
+
Public result methods return independent copies of the cached results, so
|
|
169
|
+
changing a returned object does not modify the model's internal state. Calling
|
|
170
|
+
`set_data()` or `set_parameters()` validates the new values and clears previous
|
|
171
|
+
estimates. Retrieve results with `get_test_results()`, `get_joint_results()`,
|
|
172
|
+
or `get_joint_test_results()` after running the corresponding procedure.
|
|
173
|
+
|
|
174
|
+
## Reproducibility
|
|
175
|
+
|
|
176
|
+
All stochastic procedures accept an explicit random seed. For reproducible
|
|
177
|
+
critical values, pass `random_state` to `lr_test()`, `joint_sup_lr_test()`, and
|
|
178
|
+
profile plotting routines that simulate critical values.
|
|
179
|
+
|
|
180
|
+
Example scripts demonstrating the main functionality of `fmbqml` are available
|
|
181
|
+
in the project repository:
|
|
182
|
+
|
|
183
|
+
- [Examples](https://github.com/JiangtaoDuan/fmbqml/tree/master/examples)
|
|
184
|
+
|
|
185
|
+
## Dependencies
|
|
186
|
+
|
|
187
|
+
`fmbqml` depends on NumPy, SciPy, pandas, matplotlib, and joblib. Python 3.8 or
|
|
188
|
+
newer is required.
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
## License
|
|
192
|
+
|
|
193
|
+
`fmbqml` is distributed under the MIT License. See
|
|
194
|
+
[LICENSE.txt](https://github.com/JiangtaoDuan/fmbqml/blob/master/LICENSE.txt).
|
fmbqml-0.1.0/README.md
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# fmbqml: Structural Break Analysis in High-Dimensional Factor Models
|
|
2
|
+
|
|
3
|
+
[](https://www.python.org/)
|
|
4
|
+
[](https://github.com/JiangtaoDuan/fmbqml/blob/master/LICENSE.txt)
|
|
5
|
+
|
|
6
|
+
`fmbqml` is a Python package for quasi-maximum-likelihood analysis of
|
|
7
|
+
structural breaks in high-dimensional factor models. It provides tools for
|
|
8
|
+
single-break testing and estimation, joint multiple-break estimation, sup-LR
|
|
9
|
+
testing, factor-number selection, break-type classification, and diagnostic
|
|
10
|
+
plots.
|
|
11
|
+
|
|
12
|
+
## Links
|
|
13
|
+
|
|
14
|
+
- [Source code](https://github.com/JiangtaoDuan/fmbqml)
|
|
15
|
+
- [Issue tracker](https://github.com/JiangtaoDuan/fmbqml/issues)
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
Install the package from PyPI with:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
python -m pip install fmbqml
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
For development from a source checkout, use:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
python -m pip install -e .
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Input data
|
|
32
|
+
|
|
33
|
+
The input data should be a finite two-dimensional NumPy array or pandas
|
|
34
|
+
DataFrame with observations in rows and variables in columns. Missing values
|
|
35
|
+
should be imputed before constructing a model.
|
|
36
|
+
|
|
37
|
+
## Single-break analysis
|
|
38
|
+
|
|
39
|
+
Assuming that `panel_data` contains the input panel dataset:
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from fmbqml import SingleBreakQML
|
|
43
|
+
|
|
44
|
+
model = SingleBreakQML(
|
|
45
|
+
panel_data,
|
|
46
|
+
trim_ratio=0.15,
|
|
47
|
+
max_factors=10,
|
|
48
|
+
factor_criterion="IC2",
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
result = model.lr_test(
|
|
52
|
+
alpha=0.05,
|
|
53
|
+
classify=True,
|
|
54
|
+
n_sim=5000,
|
|
55
|
+
random_state=12345,
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
print(result["reject_null"])
|
|
59
|
+
print(result["break_point"])
|
|
60
|
+
print(result.get("break_type"))
|
|
61
|
+
```
|
|
62
|
+
Use `estimate_breakpoint()` when a break is assumed to exist and significance
|
|
63
|
+
testing is not required. In `lr_test()`, `break_point` is returned when the
|
|
64
|
+
no-break null is rejected, while `estimated_break_candidate` records the
|
|
65
|
+
profile optimizer.
|
|
66
|
+
|
|
67
|
+
## Multiple-break analysis
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
from fmbqml import MultiBreakQML
|
|
71
|
+
|
|
72
|
+
model = MultiBreakQML(
|
|
73
|
+
panel_data,
|
|
74
|
+
max_break=5,
|
|
75
|
+
max_factors=8,
|
|
76
|
+
factor_criterion="IC2",
|
|
77
|
+
trim_ratio=0.10,
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
result = model.estimate_breaks_jointly(
|
|
81
|
+
min_break=0,
|
|
82
|
+
classify=True,
|
|
83
|
+
)
|
|
84
|
+
|
|
85
|
+
print(result["n_breaks"])
|
|
86
|
+
print(result["breakpoints"])
|
|
87
|
+
print(result.get("break_types"))
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The option `min_break=0` permits selection of a no-break model. Use
|
|
91
|
+
`joint_sup_lr_test(n_breaks=...)` to test no structural change against an exact
|
|
92
|
+
number of breaks.
|
|
93
|
+
|
|
94
|
+
## Factor-number selection
|
|
95
|
+
|
|
96
|
+
`factor_criterion` accepts `IC1`, `IC2`, `IC3`, `PC1`, `PC2`, `PC3`, `AIC3`,
|
|
97
|
+
or `BIC3`. Integer indices `0` through `7` are also accepted in that order.
|
|
98
|
+
The argument `max_factors` is a search bound and should be smaller than
|
|
99
|
+
`min(T, N)`.
|
|
100
|
+
|
|
101
|
+
## Results and model state
|
|
102
|
+
|
|
103
|
+
Result dictionaries contain NumPy arrays for available profiles and nested
|
|
104
|
+
structures for breakpoint classifications and information-criterion paths.
|
|
105
|
+
For example, single-break procedures store candidate break locations together
|
|
106
|
+
with LR or QML profile values, while multiple-break joint estimation stores
|
|
107
|
+
the selected breakpoints and the information-criterion path used to choose the
|
|
108
|
+
number of breaks.
|
|
109
|
+
|
|
110
|
+
Public result methods return independent copies of the cached results, so
|
|
111
|
+
changing a returned object does not modify the model's internal state. Calling
|
|
112
|
+
`set_data()` or `set_parameters()` validates the new values and clears previous
|
|
113
|
+
estimates. Retrieve results with `get_test_results()`, `get_joint_results()`,
|
|
114
|
+
or `get_joint_test_results()` after running the corresponding procedure.
|
|
115
|
+
|
|
116
|
+
## Reproducibility
|
|
117
|
+
|
|
118
|
+
All stochastic procedures accept an explicit random seed. For reproducible
|
|
119
|
+
critical values, pass `random_state` to `lr_test()`, `joint_sup_lr_test()`, and
|
|
120
|
+
profile plotting routines that simulate critical values.
|
|
121
|
+
|
|
122
|
+
Example scripts demonstrating the main functionality of `fmbqml` are available
|
|
123
|
+
in the project repository:
|
|
124
|
+
|
|
125
|
+
- [Examples](https://github.com/JiangtaoDuan/fmbqml/tree/master/examples)
|
|
126
|
+
|
|
127
|
+
## Dependencies
|
|
128
|
+
|
|
129
|
+
`fmbqml` depends on NumPy, SciPy, pandas, matplotlib, and joblib. Python 3.8 or
|
|
130
|
+
newer is required.
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
## License
|
|
134
|
+
|
|
135
|
+
`fmbqml` is distributed under the MIT License. See
|
|
136
|
+
[LICENSE.txt](https://github.com/JiangtaoDuan/fmbqml/blob/master/LICENSE.txt).
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
|
|
2
|
+
"""High-level orchestration for breakpoint classification."""
|
|
3
|
+
|
|
4
|
+
from typing import Any, Dict, Optional, Sequence, Tuple
|
|
5
|
+
from fmbqml.break_tools.classification_summary import summarize_break_types
|
|
6
|
+
from fmbqml.break_tools.classify_break_types import classify_break_types
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def classify_breakpoint_result(
|
|
10
|
+
X,
|
|
11
|
+
breakpoints: Optional[Sequence[int]],
|
|
12
|
+
result_dict: Dict[str, Any],
|
|
13
|
+
max_factors: int,
|
|
14
|
+
factor_criterion: int,
|
|
15
|
+
full_sample_factor_number: Optional[int],
|
|
16
|
+
T: int,
|
|
17
|
+
trim_ratio: Optional[float] = None,
|
|
18
|
+
min_regime_length: Optional[int] = None,
|
|
19
|
+
full_sample_standardize: bool = False,
|
|
20
|
+
segment_standardize: bool = True,
|
|
21
|
+
verbose: bool = False
|
|
22
|
+
) -> Tuple[Dict[str, Any], Dict[str, Any]]:
|
|
23
|
+
"""
|
|
24
|
+
Classify one or multiple breakpoints and update a result dictionary.
|
|
25
|
+
|
|
26
|
+
This function provides a common wrapper for both SingleBreakQML and
|
|
27
|
+
MultiBreakQML. It calls classify_break_types(), stores the classification
|
|
28
|
+
fields in the result dictionary, and adds a summary of Type 1, Type 2,
|
|
29
|
+
and other breakpoint types.
|
|
30
|
+
|
|
31
|
+
Parameters
|
|
32
|
+
----------
|
|
33
|
+
X : array-like
|
|
34
|
+
Input data matrix.
|
|
35
|
+
breakpoints : sequence of int or None
|
|
36
|
+
Breakpoint locations. For a single-break result, pass [break_point].
|
|
37
|
+
result_dict : dict
|
|
38
|
+
Existing result dictionary to update.
|
|
39
|
+
max_factors : int
|
|
40
|
+
Maximum number of factors considered in classification.
|
|
41
|
+
factor_criterion : int
|
|
42
|
+
Factor-selection criterion index.
|
|
43
|
+
full_sample_factor_number : int or None
|
|
44
|
+
Full-sample factor number used as the upper bound in classification.
|
|
45
|
+
T : int
|
|
46
|
+
Sample size.
|
|
47
|
+
trim_ratio : float, optional
|
|
48
|
+
Minimum spacing ratio used by classify_break_types().
|
|
49
|
+
min_regime_length : int, optional
|
|
50
|
+
Minimum regime length used by classify_break_types().
|
|
51
|
+
full_sample_standardize : bool, default=False
|
|
52
|
+
Whether to standardize the full sample before classification.
|
|
53
|
+
segment_standardize : bool, default=True
|
|
54
|
+
Whether to standardize each segment before classification.
|
|
55
|
+
verbose : bool, default=False
|
|
56
|
+
Whether to print a short classification message.
|
|
57
|
+
|
|
58
|
+
Returns
|
|
59
|
+
-------
|
|
60
|
+
updated_result : dict
|
|
61
|
+
Updated result dictionary.
|
|
62
|
+
classification : dict
|
|
63
|
+
Classification output.
|
|
64
|
+
"""
|
|
65
|
+
updated_result = result_dict.copy()
|
|
66
|
+
|
|
67
|
+
if breakpoints is None:
|
|
68
|
+
breakpoints = []
|
|
69
|
+
else:
|
|
70
|
+
breakpoints = [int(bp) for bp in breakpoints]
|
|
71
|
+
|
|
72
|
+
if len(breakpoints) == 0:
|
|
73
|
+
classification = {
|
|
74
|
+
"break_types": [],
|
|
75
|
+
"regime_factors": [],
|
|
76
|
+
"combined_factors": [],
|
|
77
|
+
"classification_criteria": [],
|
|
78
|
+
"regime_boundaries": [0, T],
|
|
79
|
+
"n_regimes": 1,
|
|
80
|
+
"min_regime_length": min_regime_length,
|
|
81
|
+
"classification_r_full": None,
|
|
82
|
+
"break_type": None,
|
|
83
|
+
"break_type_summary": summarize_break_types([], n_breakpoints=0),
|
|
84
|
+
"classification_full_sample_standardize": full_sample_standardize,
|
|
85
|
+
"classification_segment_standardize": segment_standardize,
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
updated_result.update(classification)
|
|
89
|
+
|
|
90
|
+
if verbose:
|
|
91
|
+
print("No breakpoints available for classification.")
|
|
92
|
+
|
|
93
|
+
return updated_result, classification
|
|
94
|
+
|
|
95
|
+
classification_r_full = None
|
|
96
|
+
|
|
97
|
+
if full_sample_factor_number is not None:
|
|
98
|
+
classification_r_full = int(full_sample_factor_number)
|
|
99
|
+
|
|
100
|
+
if classification_r_full < 0:
|
|
101
|
+
raise ValueError(
|
|
102
|
+
"full_sample_factor_number must be a non-negative integer or None. "
|
|
103
|
+
f"Got {full_sample_factor_number}."
|
|
104
|
+
)
|
|
105
|
+
|
|
106
|
+
kwargs = {
|
|
107
|
+
"X": X,
|
|
108
|
+
"breakpoints": breakpoints,
|
|
109
|
+
"max_factors": max_factors,
|
|
110
|
+
"factor_criterion": factor_criterion,
|
|
111
|
+
"full_sample_factor_number": classification_r_full,
|
|
112
|
+
"full_sample_standardize": full_sample_standardize,
|
|
113
|
+
"segment_standardize": segment_standardize,
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
if min_regime_length is not None:
|
|
117
|
+
kwargs["min_regime_length"] = min_regime_length
|
|
118
|
+
elif trim_ratio is not None:
|
|
119
|
+
kwargs["trim_ratio"] = trim_ratio
|
|
120
|
+
else:
|
|
121
|
+
kwargs["trim_ratio"] = 0.1
|
|
122
|
+
|
|
123
|
+
try:
|
|
124
|
+
classification = classify_break_types(**kwargs)
|
|
125
|
+
except TypeError as exc:
|
|
126
|
+
msg = str(exc)
|
|
127
|
+
if (
|
|
128
|
+
"full_sample_factor_number" in msg
|
|
129
|
+
or "full_sample_standardize" in msg
|
|
130
|
+
or "segment_standardize" in msg
|
|
131
|
+
):
|
|
132
|
+
raise TypeError(
|
|
133
|
+
"classify_break_types() must support the arguments "
|
|
134
|
+
"full_sample_factor_number, full_sample_standardize, and "
|
|
135
|
+
"segment_standardize."
|
|
136
|
+
) from exc
|
|
137
|
+
raise
|
|
138
|
+
|
|
139
|
+
break_types = classification.get("break_types", [])
|
|
140
|
+
|
|
141
|
+
updated_result["break_types"] = break_types
|
|
142
|
+
updated_result["regime_factors"] = classification.get("regime_factors", [])
|
|
143
|
+
updated_result["combined_factors"] = classification.get("combined_factors", [])
|
|
144
|
+
updated_result["classification_criteria"] = classification.get(
|
|
145
|
+
"classification_criteria", []
|
|
146
|
+
)
|
|
147
|
+
updated_result["regime_boundaries"] = classification.get(
|
|
148
|
+
"regime_boundaries", []
|
|
149
|
+
)
|
|
150
|
+
updated_result["n_regimes"] = classification.get(
|
|
151
|
+
"n_regimes",
|
|
152
|
+
len(breakpoints) + 1
|
|
153
|
+
)
|
|
154
|
+
|
|
155
|
+
updated_result["classification_r_full"] = classification.get(
|
|
156
|
+
"r_full",
|
|
157
|
+
classification_r_full
|
|
158
|
+
)
|
|
159
|
+
updated_result["classification_factor_criterion"] = classification.get(
|
|
160
|
+
"factor_criterion",
|
|
161
|
+
factor_criterion
|
|
162
|
+
)
|
|
163
|
+
|
|
164
|
+
if min_regime_length is not None:
|
|
165
|
+
updated_result["min_regime_length"] = min_regime_length
|
|
166
|
+
else:
|
|
167
|
+
updated_result["min_regime_length"] = classification.get(
|
|
168
|
+
"min_regime_length"
|
|
169
|
+
)
|
|
170
|
+
|
|
171
|
+
updated_result["break_type_summary"] = summarize_break_types(
|
|
172
|
+
break_types,
|
|
173
|
+
n_breakpoints=len(breakpoints)
|
|
174
|
+
)
|
|
175
|
+
|
|
176
|
+
if len(break_types) > 0:
|
|
177
|
+
updated_result["break_type"] = break_types[0]
|
|
178
|
+
else:
|
|
179
|
+
updated_result["break_type"] = None
|
|
180
|
+
|
|
181
|
+
updated_result["classification_full_sample_standardize"] = (
|
|
182
|
+
full_sample_standardize
|
|
183
|
+
)
|
|
184
|
+
updated_result["classification_segment_standardize"] = segment_standardize
|
|
185
|
+
|
|
186
|
+
classification["break_type"] = updated_result["break_type"]
|
|
187
|
+
classification["break_type_summary"] = updated_result["break_type_summary"]
|
|
188
|
+
classification["classification_r_full"] = updated_result[
|
|
189
|
+
"classification_r_full"
|
|
190
|
+
]
|
|
191
|
+
classification["classification_full_sample_standardize"] = (
|
|
192
|
+
full_sample_standardize
|
|
193
|
+
)
|
|
194
|
+
classification["classification_segment_standardize"] = segment_standardize
|
|
195
|
+
|
|
196
|
+
if verbose:
|
|
197
|
+
summary = updated_result["break_type_summary"]
|
|
198
|
+
print(
|
|
199
|
+
"Break type summary: "
|
|
200
|
+
f"Type 1 = {summary['type1_count']}, "
|
|
201
|
+
f"Type 2 = {summary['type2_count']}, "
|
|
202
|
+
f"Other = {summary['other_count']}"
|
|
203
|
+
)
|
|
204
|
+
|
|
205
|
+
return updated_result, classification
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
|
|
2
|
+
|
|
3
|
+
"""Formatting helpers for breakpoint-classification results."""
|
|
4
|
+
|
|
5
|
+
from typing import Dict, Iterable, Optional
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def summarize_break_types(
|
|
9
|
+
break_types: Optional[Iterable],
|
|
10
|
+
n_breakpoints: Optional[int] = None
|
|
11
|
+
) -> Dict[str, int]:
|
|
12
|
+
"""
|
|
13
|
+
Summarize breakpoint types.
|
|
14
|
+
|
|
15
|
+
Parameters
|
|
16
|
+
----------
|
|
17
|
+
break_types : iterable or None
|
|
18
|
+
Breakpoint type labels, such as "Type 1 (Singular)" or
|
|
19
|
+
"Type 2 (Rotational)".
|
|
20
|
+
n_breakpoints : int, optional
|
|
21
|
+
Total number of breakpoints. If provided, it is used to compute
|
|
22
|
+
the number of other / ambiguous / unknown breakpoints.
|
|
23
|
+
|
|
24
|
+
Returns
|
|
25
|
+
-------
|
|
26
|
+
dict
|
|
27
|
+
Dictionary containing counts of Type 1, Type 2, and other breakpoints.
|
|
28
|
+
"""
|
|
29
|
+
if break_types is None:
|
|
30
|
+
break_types = []
|
|
31
|
+
|
|
32
|
+
break_types = list(break_types)
|
|
33
|
+
|
|
34
|
+
type1_count = sum(
|
|
35
|
+
1 for bt in break_types
|
|
36
|
+
if isinstance(bt, str) and bt.startswith("Type 1")
|
|
37
|
+
)
|
|
38
|
+
|
|
39
|
+
type2_count = sum(
|
|
40
|
+
1 for bt in break_types
|
|
41
|
+
if isinstance(bt, str) and bt.startswith("Type 2")
|
|
42
|
+
)
|
|
43
|
+
|
|
44
|
+
if n_breakpoints is None:
|
|
45
|
+
total = len(break_types)
|
|
46
|
+
else:
|
|
47
|
+
total = int(n_breakpoints)
|
|
48
|
+
|
|
49
|
+
other_count = max(0, total - type1_count - type2_count)
|
|
50
|
+
|
|
51
|
+
return {
|
|
52
|
+
"type1_count": type1_count,
|
|
53
|
+
"type2_count": type2_count,
|
|
54
|
+
"other_count": other_count,
|
|
55
|
+
}
|