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.
Files changed (37) hide show
  1. fmbqml/__init__.py +9 -0
  2. fmbqml/break_tools/__init__.py +7 -0
  3. fmbqml/break_tools/breakpoint_classification.py +205 -0
  4. fmbqml/break_tools/classification_summary.py +55 -0
  5. fmbqml/break_tools/classify_break_types.py +401 -0
  6. fmbqml/factor_tools/__init__.py +11 -0
  7. fmbqml/factor_tools/nb_factors.py +221 -0
  8. fmbqml/factor_tools/panel_factor.py +35 -0
  9. fmbqml/factor_tools/panel_factors_lr.py +65 -0
  10. fmbqml/factor_tools/var_selection.py +140 -0
  11. fmbqml/multiple_break/__init__.py +5 -0
  12. fmbqml/multiple_break/eig_sort.py +66 -0
  13. fmbqml/multiple_break/find_min_qml.py +50 -0
  14. fmbqml/multiple_break/joint_estimation.py +307 -0
  15. fmbqml/multiple_break/joint_testing.py +141 -0
  16. fmbqml/multiple_break/multiple_break_qml.py +705 -0
  17. fmbqml/single_break/__init__.py +5 -0
  18. fmbqml/single_break/qml_profile.py +64 -0
  19. fmbqml/single_break/single_break_qml.py +642 -0
  20. fmbqml/statistical_tools/__init__.py +25 -0
  21. fmbqml/statistical_tools/brownian.py +20 -0
  22. fmbqml/statistical_tools/critical_values.py +461 -0
  23. fmbqml/statistical_tools/hac.py +85 -0
  24. fmbqml/utils/__init__.py +79 -0
  25. fmbqml/utils/breakpoint_utils.py +130 -0
  26. fmbqml/utils/criteria.py +83 -0
  27. fmbqml/utils/data_input.py +82 -0
  28. fmbqml/utils/formatting.py +561 -0
  29. fmbqml/utils/partition.py +60 -0
  30. fmbqml/utils/plotting.py +365 -0
  31. fmbqml/utils/safe_logdet.py +56 -0
  32. fmbqml/utils/validation.py +183 -0
  33. fmbqml-0.1.0.dist-info/METADATA +194 -0
  34. fmbqml-0.1.0.dist-info/RECORD +37 -0
  35. fmbqml-0.1.0.dist-info/WHEEL +5 -0
  36. fmbqml-0.1.0.dist-info/licenses/LICENSE.txt +21 -0
  37. fmbqml-0.1.0.dist-info/top_level.txt +1 -0
fmbqml/__init__.py ADDED
@@ -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
+ }
@@ -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
+ ]