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.
Files changed (44) hide show
  1. fmbqml-0.1.0/LICENSE.txt +21 -0
  2. fmbqml-0.1.0/MANIFEST.in +7 -0
  3. fmbqml-0.1.0/PKG-INFO +194 -0
  4. fmbqml-0.1.0/README.md +136 -0
  5. fmbqml-0.1.0/fmbqml/__init__.py +9 -0
  6. fmbqml-0.1.0/fmbqml/break_tools/__init__.py +7 -0
  7. fmbqml-0.1.0/fmbqml/break_tools/breakpoint_classification.py +205 -0
  8. fmbqml-0.1.0/fmbqml/break_tools/classification_summary.py +55 -0
  9. fmbqml-0.1.0/fmbqml/break_tools/classify_break_types.py +401 -0
  10. fmbqml-0.1.0/fmbqml/factor_tools/__init__.py +11 -0
  11. fmbqml-0.1.0/fmbqml/factor_tools/nb_factors.py +221 -0
  12. fmbqml-0.1.0/fmbqml/factor_tools/panel_factor.py +35 -0
  13. fmbqml-0.1.0/fmbqml/factor_tools/panel_factors_lr.py +65 -0
  14. fmbqml-0.1.0/fmbqml/factor_tools/var_selection.py +140 -0
  15. fmbqml-0.1.0/fmbqml/multiple_break/__init__.py +5 -0
  16. fmbqml-0.1.0/fmbqml/multiple_break/eig_sort.py +66 -0
  17. fmbqml-0.1.0/fmbqml/multiple_break/find_min_qml.py +50 -0
  18. fmbqml-0.1.0/fmbqml/multiple_break/joint_estimation.py +307 -0
  19. fmbqml-0.1.0/fmbqml/multiple_break/joint_testing.py +141 -0
  20. fmbqml-0.1.0/fmbqml/multiple_break/multiple_break_qml.py +705 -0
  21. fmbqml-0.1.0/fmbqml/single_break/__init__.py +5 -0
  22. fmbqml-0.1.0/fmbqml/single_break/qml_profile.py +64 -0
  23. fmbqml-0.1.0/fmbqml/single_break/single_break_qml.py +642 -0
  24. fmbqml-0.1.0/fmbqml/statistical_tools/__init__.py +25 -0
  25. fmbqml-0.1.0/fmbqml/statistical_tools/brownian.py +20 -0
  26. fmbqml-0.1.0/fmbqml/statistical_tools/critical_values.py +461 -0
  27. fmbqml-0.1.0/fmbqml/statistical_tools/hac.py +85 -0
  28. fmbqml-0.1.0/fmbqml/utils/__init__.py +79 -0
  29. fmbqml-0.1.0/fmbqml/utils/breakpoint_utils.py +130 -0
  30. fmbqml-0.1.0/fmbqml/utils/criteria.py +83 -0
  31. fmbqml-0.1.0/fmbqml/utils/data_input.py +82 -0
  32. fmbqml-0.1.0/fmbqml/utils/formatting.py +561 -0
  33. fmbqml-0.1.0/fmbqml/utils/partition.py +60 -0
  34. fmbqml-0.1.0/fmbqml/utils/plotting.py +365 -0
  35. fmbqml-0.1.0/fmbqml/utils/safe_logdet.py +56 -0
  36. fmbqml-0.1.0/fmbqml/utils/validation.py +183 -0
  37. fmbqml-0.1.0/fmbqml.egg-info/PKG-INFO +194 -0
  38. fmbqml-0.1.0/fmbqml.egg-info/SOURCES.txt +42 -0
  39. fmbqml-0.1.0/fmbqml.egg-info/dependency_links.txt +1 -0
  40. fmbqml-0.1.0/fmbqml.egg-info/requires.txt +8 -0
  41. fmbqml-0.1.0/fmbqml.egg-info/top_level.txt +1 -0
  42. fmbqml-0.1.0/pyproject.toml +54 -0
  43. fmbqml-0.1.0/setup.cfg +4 -0
  44. fmbqml-0.1.0/setup.py +61 -0
@@ -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.
@@ -0,0 +1,7 @@
1
+ include README.md
2
+ include LICENSE.txt
3
+ prune tests
4
+ prune examples
5
+ prune replication
6
+ global-exclude __pycache__ *.py[cod]
7
+
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
+ [![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://www.python.org/)
62
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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
+ [![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://www.python.org/)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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,9 @@
1
+ """Public interface for structural-break analysis in factor models."""
2
+
3
+ from .single_break.single_break_qml import SingleBreakQML
4
+ from .multiple_break.multiple_break_qml import MultiBreakQML
5
+
6
+ __all__ = [
7
+ "SingleBreakQML",
8
+ "MultiBreakQML",
9
+ ]
@@ -0,0 +1,7 @@
1
+ """Breakpoint-classification tools."""
2
+
3
+ from .breakpoint_classification import classify_breakpoint_result
4
+
5
+ __all__ = [
6
+ "classify_breakpoint_result",
7
+ ]
@@ -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
+ }