fmbqml 0.1.0__py3-none-any.whl
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/__init__.py +9 -0
- fmbqml/break_tools/__init__.py +7 -0
- fmbqml/break_tools/breakpoint_classification.py +205 -0
- fmbqml/break_tools/classification_summary.py +55 -0
- fmbqml/break_tools/classify_break_types.py +401 -0
- fmbqml/factor_tools/__init__.py +11 -0
- fmbqml/factor_tools/nb_factors.py +221 -0
- fmbqml/factor_tools/panel_factor.py +35 -0
- fmbqml/factor_tools/panel_factors_lr.py +65 -0
- fmbqml/factor_tools/var_selection.py +140 -0
- fmbqml/multiple_break/__init__.py +5 -0
- fmbqml/multiple_break/eig_sort.py +66 -0
- fmbqml/multiple_break/find_min_qml.py +50 -0
- fmbqml/multiple_break/joint_estimation.py +307 -0
- fmbqml/multiple_break/joint_testing.py +141 -0
- fmbqml/multiple_break/multiple_break_qml.py +705 -0
- fmbqml/single_break/__init__.py +5 -0
- fmbqml/single_break/qml_profile.py +64 -0
- fmbqml/single_break/single_break_qml.py +642 -0
- fmbqml/statistical_tools/__init__.py +25 -0
- fmbqml/statistical_tools/brownian.py +20 -0
- fmbqml/statistical_tools/critical_values.py +461 -0
- fmbqml/statistical_tools/hac.py +85 -0
- fmbqml/utils/__init__.py +79 -0
- fmbqml/utils/breakpoint_utils.py +130 -0
- fmbqml/utils/criteria.py +83 -0
- fmbqml/utils/data_input.py +82 -0
- fmbqml/utils/formatting.py +561 -0
- fmbqml/utils/partition.py +60 -0
- fmbqml/utils/plotting.py +365 -0
- fmbqml/utils/safe_logdet.py +56 -0
- fmbqml/utils/validation.py +183 -0
- fmbqml-0.1.0.dist-info/METADATA +194 -0
- fmbqml-0.1.0.dist-info/RECORD +37 -0
- fmbqml-0.1.0.dist-info/WHEEL +5 -0
- fmbqml-0.1.0.dist-info/licenses/LICENSE.txt +21 -0
- fmbqml-0.1.0.dist-info/top_level.txt +1 -0
fmbqml/__init__.py
ADDED
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,401 @@
|
|
|
1
|
+
"""Statistical procedures for classifying factor-model breaks."""
|
|
2
|
+
|
|
3
|
+
import warnings
|
|
4
|
+
from typing import Any, Dict, List, Optional, Union
|
|
5
|
+
|
|
6
|
+
import numpy as np
|
|
7
|
+
import pandas as pd
|
|
8
|
+
|
|
9
|
+
import fmbqml.utils as U
|
|
10
|
+
from fmbqml.factor_tools.nb_factors import bai_ng_factor_count
|
|
11
|
+
|
|
12
|
+
def _zscore_columns(X: np.ndarray) -> np.ndarray:
|
|
13
|
+
"""
|
|
14
|
+
Standardize each column using the sample standard deviation.
|
|
15
|
+
"""
|
|
16
|
+
mu = np.mean(X, axis=0)
|
|
17
|
+
sd = np.std(X, axis=0, ddof=1)
|
|
18
|
+
|
|
19
|
+
sd[~np.isfinite(sd) | (sd == 0)] = 1.0
|
|
20
|
+
|
|
21
|
+
return (X - mu) / sd
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _criterion_vector_from_bai_ng_result(
|
|
25
|
+
result: Dict[str, Any],
|
|
26
|
+
criterion: str
|
|
27
|
+
) -> np.ndarray:
|
|
28
|
+
"""
|
|
29
|
+
Extract criterion values for k = 0, ..., kmax from bai_ng_factor_count output.
|
|
30
|
+
|
|
31
|
+
Parameters
|
|
32
|
+
----------
|
|
33
|
+
result : dict
|
|
34
|
+
Output dictionary returned by bai_ng_factor_count().
|
|
35
|
+
criterion : str
|
|
36
|
+
Criterion name.
|
|
37
|
+
|
|
38
|
+
Returns
|
|
39
|
+
-------
|
|
40
|
+
ndarray
|
|
41
|
+
Criterion value vector over the candidate factor numbers.
|
|
42
|
+
"""
|
|
43
|
+
if criterion == "IC1":
|
|
44
|
+
return np.asarray(result["IC"][:, 1], dtype=float)
|
|
45
|
+
if criterion == "IC2":
|
|
46
|
+
return np.asarray(result["IC"][:, 2], dtype=float)
|
|
47
|
+
if criterion == "IC3":
|
|
48
|
+
return np.asarray(result["IC"][:, 3], dtype=float)
|
|
49
|
+
if criterion == "PC1":
|
|
50
|
+
return np.asarray(result["PC"][:, 1], dtype=float)
|
|
51
|
+
if criterion == "PC2":
|
|
52
|
+
return np.asarray(result["PC"][:, 2], dtype=float)
|
|
53
|
+
if criterion == "PC3":
|
|
54
|
+
return np.asarray(result["PC"][:, 3], dtype=float)
|
|
55
|
+
if criterion == "AIC3":
|
|
56
|
+
return np.asarray(result["AIC3"][:, 1], dtype=float)
|
|
57
|
+
if criterion == "BIC3":
|
|
58
|
+
return np.asarray(result["BIC3"][:, 1], dtype=float)
|
|
59
|
+
|
|
60
|
+
raise ValueError(f"Unsupported criterion: {criterion}")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _estimate_factor_number_by_nb(
|
|
64
|
+
X_segment: np.ndarray,
|
|
65
|
+
max_factors: int,
|
|
66
|
+
factor_criterion: str,
|
|
67
|
+
min_length: int,
|
|
68
|
+
lower_bound: int = 0,
|
|
69
|
+
upper_bound: Optional[int] = None,
|
|
70
|
+
standardize_segment: bool = True,
|
|
71
|
+
) -> Optional[int]:
|
|
72
|
+
"""
|
|
73
|
+
Estimate the number of factors in a segment using Bai--Ng criteria.
|
|
74
|
+
|
|
75
|
+
The search can be restricted to a constrained grid
|
|
76
|
+
[lower_bound, upper_bound]. This is useful when estimating the number
|
|
77
|
+
of pseudo-factors in a merged adjacent regime.
|
|
78
|
+
|
|
79
|
+
Parameters
|
|
80
|
+
----------
|
|
81
|
+
X_segment : ndarray, shape (T_seg, N)
|
|
82
|
+
Data matrix for the segment.
|
|
83
|
+
max_factors : int
|
|
84
|
+
Maximum number of factors considered.
|
|
85
|
+
factor_criterion : str
|
|
86
|
+
Factor-selection criterion.
|
|
87
|
+
min_length : int
|
|
88
|
+
Minimum segment length required for factor-number selection.
|
|
89
|
+
lower_bound : int, default=0
|
|
90
|
+
Lower bound of the candidate factor-number grid.
|
|
91
|
+
upper_bound : int, optional
|
|
92
|
+
Upper bound of the candidate factor-number grid.
|
|
93
|
+
standardize_segment : bool, default=True
|
|
94
|
+
Whether to standardize the segment before factor-number selection.
|
|
95
|
+
|
|
96
|
+
Returns
|
|
97
|
+
-------
|
|
98
|
+
int or None
|
|
99
|
+
Estimated number of factors. Returns None if the segment is too short
|
|
100
|
+
or no feasible search grid is available.
|
|
101
|
+
"""
|
|
102
|
+
T_seg, N_seg = X_segment.shape
|
|
103
|
+
|
|
104
|
+
if T_seg < min_length:
|
|
105
|
+
warnings.warn(
|
|
106
|
+
f"Segment is too short for factor-number selection: "
|
|
107
|
+
f"T_seg={T_seg}, required min_length={min_length}. "
|
|
108
|
+
"This segment will be skipped and the corresponding break type "
|
|
109
|
+
"may be reported as Unknown.",
|
|
110
|
+
RuntimeWarning,
|
|
111
|
+
stacklevel=2,
|
|
112
|
+
)
|
|
113
|
+
return None
|
|
114
|
+
|
|
115
|
+
if T_seg < 2 or N_seg < 2:
|
|
116
|
+
warnings.warn(
|
|
117
|
+
f"Segment is too small for factor-number selection: "
|
|
118
|
+
f"T_seg={T_seg}, N_seg={N_seg}. "
|
|
119
|
+
"At least two observations and two variables are required.",
|
|
120
|
+
RuntimeWarning,
|
|
121
|
+
stacklevel=2,
|
|
122
|
+
)
|
|
123
|
+
return None
|
|
124
|
+
|
|
125
|
+
Z = _zscore_columns(X_segment) if standardize_segment else X_segment.copy()
|
|
126
|
+
|
|
127
|
+
kmax_eff = min(int(max_factors), T_seg - 1, N_seg - 1)
|
|
128
|
+
|
|
129
|
+
if upper_bound is not None:
|
|
130
|
+
kmax_eff = min(kmax_eff, int(upper_bound))
|
|
131
|
+
|
|
132
|
+
lower_eff = max(0, int(lower_bound))
|
|
133
|
+
|
|
134
|
+
if kmax_eff < lower_eff:
|
|
135
|
+
warnings.warn(
|
|
136
|
+
f"No feasible factor-number search grid: "
|
|
137
|
+
f"lower_bound={lower_eff}, upper_bound={kmax_eff}. "
|
|
138
|
+
"This may occur when the segment is too short or when the "
|
|
139
|
+
"merged-regime lower bound exceeds the feasible upper bound.",
|
|
140
|
+
RuntimeWarning,
|
|
141
|
+
stacklevel=2,
|
|
142
|
+
)
|
|
143
|
+
return None
|
|
144
|
+
|
|
145
|
+
result = bai_ng_factor_count(Z, kmax=kmax_eff)
|
|
146
|
+
values = _criterion_vector_from_bai_ng_result(result, factor_criterion)
|
|
147
|
+
|
|
148
|
+
sub_values = values[lower_eff:kmax_eff + 1]
|
|
149
|
+
idx = int(np.argmin(sub_values))
|
|
150
|
+
|
|
151
|
+
return int(lower_eff + idx)
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def classify_break_types(
|
|
155
|
+
X: Union[np.ndarray, pd.DataFrame],
|
|
156
|
+
breakpoints: List[int],
|
|
157
|
+
max_factors: int = 10,
|
|
158
|
+
trim_ratio: Optional[float] = 0.1,
|
|
159
|
+
min_regime_length: Optional[int] = None,
|
|
160
|
+
factor_criterion: Union[int, str] = "IC2",
|
|
161
|
+
full_sample_factor_number: Optional[int] = None,
|
|
162
|
+
full_sample_standardize: bool = True,
|
|
163
|
+
segment_standardize: bool = True,
|
|
164
|
+
) -> Dict[str, Any]:
|
|
165
|
+
"""
|
|
166
|
+
Classify estimated breakpoints according to factor-number relationships.
|
|
167
|
+
|
|
168
|
+
For each estimated breakpoint, the procedure estimates:
|
|
169
|
+
1. the number of effective factors in the left regime, r_j;
|
|
170
|
+
2. the number of effective factors in the right regime, r_{j+1};
|
|
171
|
+
3. the number of pseudo-factors in the merged adjacent regime, r_{j,j+1}.
|
|
172
|
+
|
|
173
|
+
The breakpoint type is then determined by comparing these quantities.
|
|
174
|
+
|
|
175
|
+
Parameters
|
|
176
|
+
----------
|
|
177
|
+
X : ndarray or pandas.DataFrame, shape (T, N)
|
|
178
|
+
Input data matrix after missing-value processing or imputation.
|
|
179
|
+
breakpoints : list of int
|
|
180
|
+
Estimated break indices. The convention is
|
|
181
|
+
edges = [0] + breakpoints + [T], so X[0:bp] is the left segment
|
|
182
|
+
for a breakpoint bp.
|
|
183
|
+
max_factors : int, default=10
|
|
184
|
+
Maximum number of candidate factors.
|
|
185
|
+
trim_ratio : float, optional, default=0.1
|
|
186
|
+
Minimum regime-length fraction. Used only when min_regime_length
|
|
187
|
+
is not provided.
|
|
188
|
+
min_regime_length : int, optional
|
|
189
|
+
Minimum number of observations in each regime. If provided, it
|
|
190
|
+
overrides trim_ratio.
|
|
191
|
+
factor_criterion : str or int, default="IC2"
|
|
192
|
+
Factor-selection criterion. Supported names are
|
|
193
|
+
{'IC1', 'IC2', 'IC3', 'PC1', 'PC2', 'PC3', 'AIC3', 'BIC3'}.
|
|
194
|
+
Integer values 0--7 are also supported.
|
|
195
|
+
full_sample_factor_number : int, optional
|
|
196
|
+
Full-sample number of pseudo-factors. If not provided, it is estimated
|
|
197
|
+
using the selected Bai--Ng criterion.
|
|
198
|
+
full_sample_standardize : bool, default=True
|
|
199
|
+
Whether to standardize the full input data before classification.
|
|
200
|
+
segment_standardize : bool, default=True
|
|
201
|
+
Whether to standardize each single or merged segment before
|
|
202
|
+
factor-number selection.
|
|
203
|
+
|
|
204
|
+
Classification rule
|
|
205
|
+
-------------------
|
|
206
|
+
Type 1 (Singular):
|
|
207
|
+
r_{j,j+1} > min(r_j, r_{j+1})
|
|
208
|
+
|
|
209
|
+
Type 2 (Rotational):
|
|
210
|
+
r_{j,j+1} = min(r_j, r_{j+1})
|
|
211
|
+
|
|
212
|
+
Returns
|
|
213
|
+
-------
|
|
214
|
+
dict
|
|
215
|
+
Dictionary containing break types, regime-specific factor numbers,
|
|
216
|
+
merged-regime factor numbers, classification criteria, regime
|
|
217
|
+
boundaries, and related settings.
|
|
218
|
+
"""
|
|
219
|
+
factor_criterion_index = U.normalize_factor_criterion(factor_criterion)
|
|
220
|
+
|
|
221
|
+
factor_criterion_name = U.CRITERION_NAMES[factor_criterion_index]
|
|
222
|
+
|
|
223
|
+
if isinstance(X, pd.DataFrame):
|
|
224
|
+
X = X.to_numpy(dtype=float)
|
|
225
|
+
else:
|
|
226
|
+
X = np.asarray(X, dtype=float)
|
|
227
|
+
|
|
228
|
+
T, N = U.validate_input_matrix(X, name="X")
|
|
229
|
+
|
|
230
|
+
max_factors = U.validate_max_factors(max_factors, T, N)
|
|
231
|
+
|
|
232
|
+
breakpoints = sorted(set(int(b) for b in breakpoints if 0 < int(b) < T))
|
|
233
|
+
|
|
234
|
+
if min_regime_length is not None:
|
|
235
|
+
min_length = U.validate_positive_integer(
|
|
236
|
+
min_regime_length,
|
|
237
|
+
"min_regime_length"
|
|
238
|
+
)
|
|
239
|
+
else:
|
|
240
|
+
trim_ratio = U.validate_trim_ratio(trim_ratio)
|
|
241
|
+
min_length = U.compute_min_segment_length(T, trim_ratio)
|
|
242
|
+
|
|
243
|
+
X_work = _zscore_columns(X) if full_sample_standardize else X.copy()
|
|
244
|
+
|
|
245
|
+
# Estimate or use the full-sample number of pseudo-factors.
|
|
246
|
+
if full_sample_factor_number is None:
|
|
247
|
+
r_full = _estimate_factor_number_by_nb(
|
|
248
|
+
X_segment=X_work,
|
|
249
|
+
max_factors=max_factors,
|
|
250
|
+
factor_criterion=factor_criterion_name,
|
|
251
|
+
min_length=1,
|
|
252
|
+
lower_bound=0,
|
|
253
|
+
upper_bound=max_factors,
|
|
254
|
+
standardize_segment=False,
|
|
255
|
+
)
|
|
256
|
+
if r_full is None:
|
|
257
|
+
r_full = 0
|
|
258
|
+
else:
|
|
259
|
+
r_full = U.validate_nonnegative_integer(
|
|
260
|
+
full_sample_factor_number,
|
|
261
|
+
"full_sample_factor_number"
|
|
262
|
+
)
|
|
263
|
+
if len(breakpoints) == 0:
|
|
264
|
+
return {
|
|
265
|
+
"break_types": [],
|
|
266
|
+
"regime_factors": [],
|
|
267
|
+
"combined_factors": [],
|
|
268
|
+
"classification_criteria": [],
|
|
269
|
+
"regime_boundaries": [0, T],
|
|
270
|
+
"n_regimes": 1,
|
|
271
|
+
"min_regime_length": min_length,
|
|
272
|
+
"factor_criterion": factor_criterion,
|
|
273
|
+
"r_full": r_full,
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
regime_boundaries = [0] + breakpoints + [T]
|
|
277
|
+
n_regimes = len(regime_boundaries) - 1
|
|
278
|
+
|
|
279
|
+
# Estimate r_j for each individual regime.
|
|
280
|
+
regime_factors = []
|
|
281
|
+
|
|
282
|
+
for i in range(n_regimes):
|
|
283
|
+
start = regime_boundaries[i]
|
|
284
|
+
end = regime_boundaries[i + 1]
|
|
285
|
+
|
|
286
|
+
r_i = _estimate_factor_number_by_nb(
|
|
287
|
+
X_segment=X_work[start:end, :],
|
|
288
|
+
max_factors=max_factors,
|
|
289
|
+
factor_criterion=factor_criterion_name,
|
|
290
|
+
min_length=min_length,
|
|
291
|
+
lower_bound=0,
|
|
292
|
+
upper_bound=r_full,
|
|
293
|
+
standardize_segment=segment_standardize,
|
|
294
|
+
)
|
|
295
|
+
regime_factors.append(r_i)
|
|
296
|
+
|
|
297
|
+
# Estimate r_{j,j+1} for each merged adjacent regime and classify breaks.
|
|
298
|
+
break_types = []
|
|
299
|
+
combined_factors = []
|
|
300
|
+
classification_criteria = []
|
|
301
|
+
|
|
302
|
+
for j, bp in enumerate(breakpoints):
|
|
303
|
+
left_regime = j
|
|
304
|
+
right_regime = j + 1
|
|
305
|
+
|
|
306
|
+
r_j = regime_factors[left_regime]
|
|
307
|
+
r_j1 = regime_factors[right_regime]
|
|
308
|
+
|
|
309
|
+
if r_j is None or r_j1 is None:
|
|
310
|
+
break_type = "Unknown (insufficient data)"
|
|
311
|
+
r_j_j1 = None
|
|
312
|
+
min_r = None
|
|
313
|
+
max_r = None
|
|
314
|
+
r_lower = None
|
|
315
|
+
r_upper = None
|
|
316
|
+
condition = (
|
|
317
|
+
"At least one adjacent regime is shorter than min_regime_length."
|
|
318
|
+
)
|
|
319
|
+
else:
|
|
320
|
+
combined_start = regime_boundaries[left_regime]
|
|
321
|
+
combined_end = regime_boundaries[right_regime + 1]
|
|
322
|
+
|
|
323
|
+
min_r = min(r_j, r_j1)
|
|
324
|
+
max_r = max(r_j, r_j1)
|
|
325
|
+
|
|
326
|
+
# The merged-regime factor number should not be smaller than
|
|
327
|
+
# the larger factor number of the two adjacent regimes.
|
|
328
|
+
r_lower = max_r
|
|
329
|
+
r_upper = r_full
|
|
330
|
+
|
|
331
|
+
r_j_j1 = _estimate_factor_number_by_nb(
|
|
332
|
+
X_segment=X_work[combined_start:combined_end, :],
|
|
333
|
+
max_factors=max_factors,
|
|
334
|
+
factor_criterion=factor_criterion_name,
|
|
335
|
+
min_length=min_length,
|
|
336
|
+
lower_bound=r_lower,
|
|
337
|
+
upper_bound=r_upper,
|
|
338
|
+
standardize_segment=segment_standardize,
|
|
339
|
+
)
|
|
340
|
+
|
|
341
|
+
if r_j_j1 is None:
|
|
342
|
+
# Fallback when the constrained search grid is empty.
|
|
343
|
+
q_merge = min(combined_end - combined_start, N)
|
|
344
|
+
r_j_j1 = min(r_upper, q_merge - 1)
|
|
345
|
+
condition_extra = (
|
|
346
|
+
" Constrained grid was empty; used feasible upper bound."
|
|
347
|
+
)
|
|
348
|
+
else:
|
|
349
|
+
condition_extra = ""
|
|
350
|
+
|
|
351
|
+
if r_j_j1 > min_r:
|
|
352
|
+
break_type = "Type 1 (Singular)"
|
|
353
|
+
condition = (
|
|
354
|
+
f"r_j,j+1 ({r_j_j1}) > min(r_j,r_j+1) ({min_r}); "
|
|
355
|
+
f"merged search grid=[{r_lower},{r_upper}]."
|
|
356
|
+
+ condition_extra
|
|
357
|
+
)
|
|
358
|
+
elif r_j_j1 == min_r:
|
|
359
|
+
break_type = "Type 2 (Rotational)"
|
|
360
|
+
condition = (
|
|
361
|
+
f"r_j,j+1 ({r_j_j1}) = min(r_j,r_j+1) ({min_r}); "
|
|
362
|
+
f"merged search grid=[{r_lower},{r_upper}]."
|
|
363
|
+
+ condition_extra
|
|
364
|
+
)
|
|
365
|
+
else:
|
|
366
|
+
break_type = "Unknown (invalid rank relation)"
|
|
367
|
+
condition = (
|
|
368
|
+
f"Estimated r_j,j+1 ({r_j_j1}) < "
|
|
369
|
+
f"min(r_j,r_j+1) ({min_r}); "
|
|
370
|
+
"this violates the expected rank relation."
|
|
371
|
+
+ condition_extra
|
|
372
|
+
)
|
|
373
|
+
|
|
374
|
+
combined_factors.append(r_j_j1)
|
|
375
|
+
|
|
376
|
+
classification_criteria.append({
|
|
377
|
+
"break_index": bp,
|
|
378
|
+
"r_j": r_j,
|
|
379
|
+
"r_j1": r_j1,
|
|
380
|
+
"r_j_j1": r_j_j1,
|
|
381
|
+
"min_r": min_r,
|
|
382
|
+
"max_r": max_r,
|
|
383
|
+
"r_lower_for_merge": r_lower,
|
|
384
|
+
"r_upper_for_merge": r_upper,
|
|
385
|
+
"condition": condition,
|
|
386
|
+
"type": break_type,
|
|
387
|
+
})
|
|
388
|
+
|
|
389
|
+
break_types.append(break_type)
|
|
390
|
+
|
|
391
|
+
return {
|
|
392
|
+
"break_types": break_types,
|
|
393
|
+
"regime_factors": regime_factors,
|
|
394
|
+
"combined_factors": combined_factors,
|
|
395
|
+
"classification_criteria": classification_criteria,
|
|
396
|
+
"regime_boundaries": regime_boundaries,
|
|
397
|
+
"n_regimes": n_regimes,
|
|
398
|
+
"min_regime_length": min_length,
|
|
399
|
+
"factor_criterion": factor_criterion_name,
|
|
400
|
+
"r_full": r_full,
|
|
401
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Factor-number selection and principal-component estimation tools."""
|
|
2
|
+
|
|
3
|
+
from .nb_factors import bai_ng_factor_count
|
|
4
|
+
from .panel_factor import estimate_panel_factors
|
|
5
|
+
from .panel_factors_lr import estimate_panel_factors_lr
|
|
6
|
+
|
|
7
|
+
__all__ = [
|
|
8
|
+
"bai_ng_factor_count",
|
|
9
|
+
"estimate_panel_factors_lr",
|
|
10
|
+
"estimate_panel_factors",
|
|
11
|
+
]
|