xtbreak API Reference

Complete reference for the public Python API of xtbreak.

The three entry points (test, estimate, select) accept time-series or panel data with covariance options ssr, hc, hac, np, and wpn. Panel-specific options include factor controls (csa=, csanobreak=, kfactors=, nbkfactors=, csd=True). The select() function provides oracle-backed sequential break selection; it requires caller-supplied critical values rather than shipping built-in tables.

Runtime Dependencies

The package depends on Python ≥ 3.10 and NumPy at runtime. Optional:

scipy — Chow test p-values
pandas — DataFrame input/output
matplotlib — plotting functions

Stata is used by the test suite as a numerical parity oracle but is not a runtime dependency.

Source Authority

The API follows this authority order:

Methodology paper: paper/arXiv-2211.06707v2/Multiple_Breaks_Main.tex
Stata software paper: paper/arXiv-2110.14550v3/xtbreak_article.tex
Stata package and fixtures: xtbreak-2.2/
Tested Python public contract

Public API and Deprecation Policy

The public API is the xtbreak namespace: __all__, __version__, test, estimate, select, result classes, and exception classes. Underscored modules (_api, _result, _panel, _covariance, _benchmark, _numerics) are internal.

No deprecated aliases exist. Unsupported requests fail with XTBreakValidationError. Future deprecations must identify the deprecated symbol, its replacement, the first warning release, and the earliest removal release.

Stata Migration Boundaries

The Python API is a documented subset of Stata xtbreak, not a command-line clone. Known gaps:

xtbreak.test(...) does not expose Stata’s full hypothesis(), level, sequential, cvalue, or built-in critical-value table surface. Public H2 and WDmax diagnostics are available through xtbreak.select(...) only when callers provide the required critical-value inputs.
Stata deterministic and panel-model options such as breakconstant, noconstant, and breakfixedeffects are not public Python keyword arguments. Users who need these designs must construct the corresponding columns explicitly in x or wait for a documented public API. Note: trend and breaktrend are now supported as public keyword arguments on test(), estimate(), and select() (see New Parameters below).
Stata region() and date-list breakpoint parsing with index or fmt() are not public Python surfaces. Python breakpoints= values are sample-axis break indexes; callers must map calendar labels outside the package.
Python post-estimation exposes JSON-safe payloads, single-break SSR path data, regime_statistics, chow_tests, to_dataframe(), and break_date_labels() where available. It does not expose a public multi-break segment-SSR matrix equivalent to Stata e(SSRvmat) unless return_segment_ssr=True is passed to estimate()/select().
Public vce accepts only ssr, hc, hac, np, and wpn. Stata HAC routing aliases such as kw and nw are not public Python option values; use vce="hac" for HAC covariance requests.

Public Entry Points

The public API consists of the xtbreak namespace: __all__, __version__, test, estimate, select, result classes, and exception classes. Underscored modules are internal. Unsupported requests raise XTBreakValidationError. Any future deprecation must document the deprecated symbol, the replacement, the first warning release, and the earliest removal release.

`xtbreak.test(...)`

Tests for structural breaks in a time-series or panel design matrix.

Current behavior:

requires raw y and x arrays;
accepts matching entity= and time= arrays for the public panel slice;
accepts breakpoints= for known-breakpoint vce="ssr" Chow/F tests and known-breakpoint vce="hc"/vce="hac" Wald tests, plus explicit-panel vce="np"/vce="wpn" Wald tests;
accepts the vce option;
allows ssr, hac, hc, np, and wpn;
raises XTBreakValidationError for unknown vce values;
returns XTBreakResult for vce="ssr" and robust XTBreakResult snapshots for time-series and explicit panel covariance paths;
records metadata["df_semantics"] so denominator_df and numerator_df are not ambiguous: SSR tests use ssr_model_degrees_of_freedom, while non-SSR Wald tests use q_normalized_wald_restriction_degrees_of_freedom;
raises XTBreakValidationError for time-series np/wpn because those panel covariance estimators require explicit entity= and time= arrays;
accepts panel csa=, csanobreak=, kfactors=, nbkfactors=, and csd=True controls, rejecting observed factors that vary across entities within a time period; SSR test(...) statistics count entity-specific common-factor nuisance loadings in the numerator and denominator degrees of freedom for the same factor surface used by the segment SSR objective;
accepts nobreak_x= only for the narrow known-break panel partial path test(..., nobreak_x=..., breakpoints=(single,), entity=..., time=..., vce="ssr") and the narrow single-break unknown path test(..., nobreak_x=..., entity=..., time=..., breaks=1, vce="ssr"); robust covariance is explicitly unsupported for panel partial nobreak_x and vce="hc", vce="hac", vce="np", and vce="wpn" fail fast; these paths also reject multi-break tests, factor controls including csa, csanobreak, kfactors, nbkfactors, csd, and fixed_effects=False; on balanced panels they accept reweigh=False with the same SSR/F objective as reweigh=True;
rejects csd=True combined with manual csa= or csanobreak= because the shortcut already defines those cross-sectional-average lists;
records separate breaking and non-breaking factor metadata plus source_governed_common_factor_covariance for supported robust factor paths.

`xtbreak.estimate(...)`

Estimates break dates by SSR-minimizing dynamic programming, for time-series or panel data (when entity= and time= arrays are supplied).

Current behavior:

accepts the same strict vce contract as xtbreak.test(...);
accepts matching entity= and time= arrays for panel raw-data SSR execution;
accepts nobreak_x= only for the narrow panel partial path estimate(..., nobreak_x=..., entity=..., time=..., breaks=1, vce="ssr"); this path requires balanced panels with fixed effects and currently rejects robust covariance is explicitly unsupported for panel partial nobreak_x and vce="hc", vce="hac", vce="np", and vce="wpn" fail fast; confidence-interval parity, multi-break, factor controls including csa, csanobreak, kfactors, nbkfactors, csd, and fixed_effects=False also remain unsupported; it accepts reweigh=False on balanced panels, where the reweighting factors are identical to reweigh=True; its public payload is row-order invariant and JSON-serializable through EstimateResult.to_dict(); CI bounds are nullable when ci_method="not_computed_panel_partial"; rejects time_values= because panel partial paths use time=;
maps panel break indexes to the common time axis, not raw observation rows;
records the SSR-minimizing dynamic-programming objective in metadata["break_search_objective"] and the source anchor in metadata["break_search_source"];
does not silently fall back to SSR for unknown covariance names;
returns EstimateResult for supported time-series and explicit-panel covariance paths;
computes homoskedastic plug-in break-date confidence intervals for supported time-series and explicit-panel samples; pass ci_level= to choose the interval level, with a degenerate fallback and ci_error metadata when the plug-in cannot be formed;
records non-SSR covariance metadata through metadata["covariance_estimator"], metadata["bandwidth"], and metadata["covariance"]; the covariance payload is computed on the post-break unrestricted regime-interaction design and contains coefficients, standard errors, a covariance matrix, residual SSR, residual degrees of freedom, and source-governed limitation flags where applicable;
records separate csa, csanobreak, kfactors, nbkfactors, and csd expansion counts and metadata["csa_covariance_status"] == "source_governed_common_factor_covariance" when supported panel factor controls are supplied on robust paths;
exposes metadata["solver_diagnostics"] for the break-search design so callers can audit the normalized solver name, rank, condition number, and fallback flag without changing the current estimator contract;
raises XTBreakValidationError for time-series np/wpn because those panel covariance estimators require explicit entity= and time= arrays.

`xtbreak.select(...)`

Provides oracle-backed sequential break selection and selected break counts via caller-supplied critical values. This is not a built-in critical-value-table replacement. It:

accepts the same raw-data and panel axes as xtbreak.estimate(...);
accepts the same panel factor controls, including csd=True for all-breaking RHS cross-sectional-average expansion;
accepts nobreak_x= only for the narrow panel partial path select(..., nobreak_x=..., entity=..., time=..., max_breaks=1, critical_values={1: ...}); this path evaluates one caller-supplied critical-value F(1|0) step from the public unknown-break panel partial statistic and currently rejects omitted or multi-break max_breaks, including the explicit max_breaks=0 boundary, factor controls, csd, and fixed_effects=False; missing critical_values is reported before this panel partial max-breaks boundary; it accepts reweigh=False on balanced panels with zero statistic drift relative to reweigh=True and records reweigh=False on the selector metadata as well as the promoted estimate metadata; rejects time_values= because panel partial paths use time=; public selection has no vce keyword for panel partial nobreak_x and remains the single-step SSR selector; H2 diagnostic components use level_critical_values metadata when skip_h2=False, so their critical-value level, source, and rejection flag are separate from the sequential critical_values decision;
evaluates the sequential F(k+1|k) path up to max_breaks; selector step and H2 component payloads record df_semantics="ssr_model_degrees_of_freedom" because public selection statistics are SSR/F comparisons rather than robust Wald restrictions;
when max_breaks is omitted, uses the methodology-paper rule floor(1 / trimming) - 2 from paper/arXiv-2211.06707v2/Multiple_Breaks_Main.tex line 374, then applies the public guard max(1, ...) so the omitted-default path never returns a nonpositive break count. The software paper’s US example footnote uses a ceil convention; PyXTBreak follows the higher-authority methodology paper and records the source boundary in result metadata. The live Stata 18 xtbreak-2.2 probe in artifacts/verification/stata/phase40_default_maxbreaks_probe.txt records default_r_f_rows: 5 at trimming=0.15; PyXTBreak keeps the methodology-paper default of 4 and treats the Stata row count as an explicit parity boundary;
can optionally compute the H2 double-maximum diagnostic through wdmax; H2 diagnostic components expose critical-value level, source, rejection flag, weighted statistic, and weight from level_critical_values across raw-data, common_x, and panel partial nobreak_x selector paths; weighted H2 component rejection flags use the WDmax baseline critical value level_critical_values[1], while unweighted H2 component rejection flags use each component’s own level_critical_values[k]; H2 selected_breaks is 0 when no H2 component rejects and otherwise reports the strongest rejected H2 component count. For panel selections, sequential steps and H2/WDmax diagnostics use the same panel sample-size, fixed-effect, and common-factor nuisance degrees of freedom;
returns BreakSelectionResult with the evaluated steps, selected break count, selected min/max range, optional H2 payload, and optional EstimateResult for the selected count. In non-strict ambiguous ranges, selected_breaks follows the conservative lower terminal rejection used for estimate handoff while selected_min_breaks and selected_max_breaks preserve the full range. For common_x selections, nested promoted estimates match the conservative selected_breaks handoff count rather than the upper ambiguous bound, and their metadata reports the actual brute-force partial break-search algorithm. When partial structural-change confidence intervals are not computed, promoted estimates keep nullable CI bounds rather than synthetic zero-width intervals. num_fixed_regressors must match common_x.shape[1] for non-empty common_x; every common_x column enters the partial structural-change design as a non-breaking regressor and is counted in the statistic denominator degrees of freedom. A zero-column common_x matrix is invalid; omit common_x when there are no non-breaking regressors. Selector metadata records num_fixed_regressors and num_breaking_regressors, matching the non-breaking common_x columns and the breaking x columns used by the promoted estimate and sequential degrees of freedom. Common-X selections expose a dual SSR contract: selector steps and promoted estimate SSR keep the paper-style free/refit common-X objective, while EstimateResult.ssr_path, ssr_path_plot_data(), and metadata["ssr_path_objective"] expose the Stata e(SSRvec) fixed-selected-common oracle semantics used for estat ssr display. BreakSelectionResult.to_dict() preserves selection_ssr_objective and the nested estimate ssr_path_objective labels alongside the selected SSR and fixed-common SSR path values. The nested ssr_path_objective is present only for selected one-break estimates with an actual SSR path; multi-break common-X promoted estimates keep ssr_path absent and do not claim Stata estat ssr path semantics. Weighted and unweighted common-X H2 diagnostics expose ssr_objective="free_common_coefficients_candidate_refit" so diagnostic SSR values are not confused with the one-break Stata display path. Zero-break common-X selections omit promoted estimates, selected breakpoint lists, and SSR-path objective metadata, while preserving selection_ssr_objective and H2/component ssr_objective labels for evaluated diagnostics. H2 selected_breaks is diagnostic and independent of the conservative sequential selected_breaks used for promoted estimate handoff, so the two counts may differ on non-strict ambiguous selections. Strict sequential stopping does not truncate H2 diagnostics, which still evaluate the admissible hypothesis-(2) components and remain independent of promoted estimate handoff.
reports the narrow public panel partial estimate(..., nobreak_x=...) search as break_search_algorithm="initialized_dynamicpartial_helper_ssr", matching the initialized dynamicpartial helper-matrix SSR path rather than the generic raw-data dynamic-programming optimizer.

New Parameters (test / estimate / select)

The following parameters are available on xtbreak.test(), xtbreak.estimate(), and xtbreak.select() unless otherwise noted:

Parameter	Type	Default	Available In	Description
`data`	`pd.DataFrame \| None`	`None`	test, estimate, select	Pandas DataFrame input. When provided, `y`/`x`/`entity`/`time` should be column name strings (or lists of strings for `x`).
`trend`	`bool`	`False`	test, estimate, select	Add a linear trend to non-breaking regressors (fixed trend across regimes).
`breaktrend`	`bool`	`False`	test, estimate, select	Add a linear trend to breaking regressors (trend allowed to shift at breakpoints).
`n_jobs`	`int`	`1`	estimate, select	Number of parallel workers. When >1, parallelizes the dynamic-programming break search.
`lazy_ssr`	`bool \| None`	`None`	estimate, select	Memory optimization for segment SSR computation. `None` = auto (enabled when T > 5000), `True` = force lazy evaluation, `False` = force full matrix.
`return_segment_ssr`	`bool`	`False`	estimate, select	When `True`, includes the full segment SSR matrix in result metadata. Not available with `lazy_ssr=True`.
`information_criterion`	`str \| None`	`None`	select	Information criterion for model selection. Accepted values: `'bic'` or `'aic'`. When set, the selector uses the specified criterion instead of the sequential F procedure.

Result Containers

`xtbreak.CommandType`

Literal["test", "estimate", "select"] — a type alias constraining the command field on XTBreakResult, EstimateResult, and BreakSelectionResult.

`xtbreak.XTBreakResult`

Immutable snapshot container for future test results. It stores command metadata, hypothesis number, break indexes, a statistic, a p-value, critical values, and arbitrary metadata. Use to_dict() for JSON-safe serialization. When metadata includes any SSR/df contract field (restricted_ssr, unrestricted_ssr, denominator_df, numerator_df, or df_semantics), it must include the complete set: SSR values must be finite and nonnegative, unrestricted SSR cannot exceed restricted SSR, degrees of freedom must be positive integers, and df_semantics must be one of the documented public semantics. This keeps xtbreak.test(...) result payloads fail-closed instead of allowing partial or ambiguous statistical metadata.

`xtbreak.EstimateResult`

Immutable result surface for Stata-shaped xtbreak estimate output. It supports the current parity and documentation examples and is also returned by the first raw-data estimate(...) runtime slice.

Create it with:

result = xtbreak.EstimateResult.from_break_matrices(
    command=payload["command"],
    break_matrix=payload["results"]["breaks"],
    ci_matrix=payload["results"]["ci"],
    ssr=payload["results"]["ssr"],
    metadata={"scenario_id": payload["scenario_id"]},
)

Pass sample_time_values=... when an oracle or runtime result carries the full time axis. The result validates that every break index points to the same time value recorded in the Stata-shaped break matrix. For single-break estat ssr payloads, pass both ssr_path and sample_time_values. Phase 140 locks EstimateResult break-index order validation: break estimate indexes must be strictly increasing even when no sample_time_values axis is attached. Duplicate or decreasing indexes fail with break estimate indexes must be strictly increasing. rather than being serialized into impossible break tables or post-estimation regimes. Phase 141 locks EstimateResult time-axis validation: sample_time_values and FittedSample.time_axis entries must be strictly increasing. Duplicate or decreasing time axes fail with sample_time_values entries must be strictly increasing. or time_axis entries must be strictly increasing. so regime boundaries and ssr_path_plot_data() cannot contradict the ordered t=1..T sample index. Phase 142 locks EstimateResult terminal-break validation when a sample axis is attached: a break index must be smaller than len(sample_time_values) so the post-break regime is non-empty. Terminal sample-axis breaks fail with break estimate index must leave a non-empty post-break regime. Phase 143 locks EstimateResult CI-axis validation when a sample axis is attached: non-null confidence-interval index bounds must be positive, and confidence-interval time bounds must equal sample_time_values when the CI index falls on the attached axis. Positive CI bounds outside a candidate SSR axis remain allowed for source oracles whose confidence interval extends beyond that display axis. Mismatches fail with break estimate ci_index must align with sample_time_values. or break estimate ci_time_value must align with sample_time_values. Phase 144 locks EstimateResult SSR-path selected-value validation: single-break ssr_path payloads must have a finite value at the selected break index, and that value must match EstimateResult.ssr within machine precision. Missing or contradictory selected path values fail with selected ssr_path value must match ssr. Phase 145 locks FittedSample row-id validation: fitted-sample row IDs must be unique and hashable at construction time, because post-estimation indicator, split, and scatter payloads use them as observation identity keys. Invalid row IDs fail with row_ids entries must be unique. or row_ids entries must be hashable. Phase 146 locks FittedSample variable-name validation: fitted-sample regressor_names and break_variable_names must each be unique, because post-estimation split and scatter payloads resolve fitted columns by name. Duplicate names fail with regressor_names entries must be unique. or break_variable_names entries must be unique.

Available fields:

regime_statistics: tuple[RegimeStatistics, ...] — per-regime OLS statistics (coefficients, standard errors, t-statistics, R², adjusted R², SSR) computed from the estimated break partition. Empty when regime statistics are not computed.
chow_tests: tuple[ChowTestResult, ...] — between-regime Chow F test results for coefficient equality across each pair of adjacent regimes. Empty when Chow tests are not computed.

Available methods:

to_dataframe() -> pd.DataFrame converts regime statistics to a tidy DataFrame with one row per variable per regime, containing columns: regime, variable_index, coefficient, std_error, t_statistic, regime_start, regime_end, n_obs, r_squared, adjusted_r_squared, ssr. Raises ImportError if pandas is not installed. Returns an empty DataFrame when regime_statistics is empty.
break_date_labels(time_labels=None) -> tuple[str, ...] maps break indices to human-readable date labels. If time_labels (a sequence of strings matching each time period) is provided, uses those; otherwise falls back to time_value from each EstimateBreak, or formats as "t={index}".
break_table() returns one row per break with index, time value, and confidence-interval bounds.
plot_data() returns breakpoint, confidence-interval, and optional sample-axis payloads for downstream plotting.
regime_indicators() returns a JSON-safe command="indicator" payload with Stata-style regime labels, row IDs, time values, optional entity values, and an explicit outside-sample policy.
split_design() returns a JSON-safe command="split" payload with regime-specific columns for fitted variables listed in fitted_sample.break_variable_names and any requested breaking constant; non-breaking fitted regressors are retained in the fitted sample but are not eligible for regime splitting.
scatter_plot_data() returns a JSON-safe command="scatter" payload with row-level points, regime-grouped traces, break lines, confidence intervals, legend labels, and source anchors. For common-X promoted estimates, scatter_plot_data() only accepts breaking variables as the x-axis variable, matching Stata estat scatter; non-breaking common-X regressors remain inspectable through FittedSample but are not valid scatter x variables.
summary() returns a compact text summary.
ssr_path_plot_data() returns a JSON-safe command="ssr" payload when ssr_path and sample_time_values were supplied for a single-break result.

The post-estimation helpers return data only. They do not require matplotlib, plotly, or any plotting backend; callers pass the returned payloads into their own plotting or reporting tools.

For promoted estimates from select(..., common_x=..., num_fixed_regressors=common_x.shape[1]), the fitted sample metadata distinguishes breaking x columns from non-breaking common_x columns. Default split_design() uses only the breaking x columns, and explicit requests for non-breaking common_x columns fail clearly instead of creating incoherent regime-specific common-X columns. scatter_plot_data() has the same boundary: scatter_plot_data("common_x*") fails because Stata estat scatter is defined for a variable with breaks on the x-axis. Historical non-common-X fitted-sample scatter payloads keep their existing compatibility.

`xtbreak.BreakSelectionResult`

Immutable automatic-selection payload. It stores the sequential evidence, selected break counts, optional H2 diagnostic, optional EstimateResult, and selection metadata. selected_breaks is the estimate-handoff count; in non-strict ambiguous ranges the full span remains available as selected_min_breaks and selected_max_breaks. Use to_dict() for JSON-safe serialization. For common_x selectors, nested promoted estimates match selected_breaks, metadata reports the actual brute-force partial break-search algorithm, and promoted estimates use nullable CI bounds when partial structural-change confidence intervals are not computed. num_fixed_regressors must match the number of common_x columns, and zero-column common_x designs are rejected. Top-level metadata records both BreakSelectionResult.metadata["num_fixed_regressors"] and BreakSelectionResult.metadata["num_breaking_regressors"] so serialized payloads carry the denominator and numerator regressor counts used by the selection statistics. Optional H2/WDmax diagnostic selected_breaks can differ from the conservative sequential BreakSelectionResult.selected_breaks used for promoted estimates. Strict sequential stopping does not truncate H2 diagnostics; nested H2 components continue to represent the independent hypothesis-(2) diagnostic surface. Raw-data, common_x, and panel partial selectors use the same public separation between sequential estimate handoff and H2 diagnostics. Strict sequential stopping can return selected_breaks == 0 and omit a promoted estimate while the nested H2 payload still reports its independently evaluated diagnostic components. Raw-data H2 diagnostics report ssr_objective="standard_segment_ssr_candidate_refit"; panel partial nobreak_x diagnostics report ssr_objective="initialized_dynamicpartial_helper_ssr". Count metadata keeps the same distinction: selection_steps_evaluated records returned sequential steps, selection_statistics_computed records evaluated selection statistics, and h2_components_evaluated records evaluated H2 components.

Manually constructed BreakSelectionResult objects validate their public payloads at construction time. Break-count fields must be non-bool integers in their admissible ranges, max_breaks must be at least one, and selected ranges must either be zero or refer to returned sequential steps. Critical-value levels must be finite probabilities with real boolean exact-match flags, and reserved metadata mirrors such as requested_cvalue, requested_level, and max_breaks must match the canonical top-level fields. Positive selections may omit a promoted estimate, but a supplied estimate must be an EstimateResult whose num_breaks equals top-level selected_breaks.

Sequential steps are SSR/F payloads. Each step must be a mapping with finite nonnegative SSR values, positive integer numerator and denominator degrees of freedom, df_semantics="ssr_model_degrees_of_freedom", finite nonnegative statistic, positive finite critical_value, and a boolean rejected field that matches statistic > critical_value. The returned step family must be the contiguous sequence 1..len(steps), and selected_min_breaks / selected_max_breaks must match the step decisions under strict or non-strict selection.

When present, h2 must be a mapping, must be omitted when skip_h2=True, and must carry a real boolean weighted flag matching wdmax. H2 payloads include selected_breaks with selected_breaks_role="h2_diagnostic_not_estimate_handoff", a finite top-level statistic, a non-empty ordered component family, and a top-level ssr_objective shared by all components. H2 selected-break counts are diagnostic counts: they must be nonnegative integers no larger than max_breaks, and they aggregate the strongest rejected component rather than overwriting the top-level estimate handoff.

Each H2 component must include finite statistic and weighted_statistic fields, an integer breaks value in the contiguous sequence 1..len(components), positive finite critical_value and weight, a boolean rejected decision, finite nonnegative restricted and unrestricted SSR values, positive integer numerator and denominator degrees of freedom, and df_semantics="ssr_model_degrees_of_freedom". Component algebra is checked: unrestricted SSR cannot exceed restricted SSR, weighted_statistic must equal statistic * weight, rejected must match the H2/WDmax decision rule, and the top-level H2 statistic and selected-break count must match the component evidence.

`xtbreak.EstimateBreak`

Represents one estimated break date. It stores the break number, one-based break index, time-axis value, confidence interval in indexes, and confidence interval in time values. Public constructors require positive one-based break numbers and indexes, ordered nullable confidence-interval bounds, and matching nullable index/time confidence-interval shape. Inside EstimateResult, break entries must be EstimateBreak objects with contiguous break_number == 1..num_breaks, and SSR plus SSR-path values must be nonnegative.

`xtbreak.FittedSample`

Immutable fitted-sample metadata used by EstimateResult post-estimation helpers. Runtime estimate(...) results populate it when fitted row IDs, time values, optional entity values, dependent values, regressor values, regressor names, break-variable names, and the aligned time axis are available. Users normally consume this through regime_indicators(), split_design(), and scatter_plot_data() rather than constructing it directly. Direct construction validates that row_ids are non-empty, unique, and hashable before serialization or post-estimation mapping. It also validates that regressor_names and break_variable_names are unique, so split and scatter helpers do not silently choose the first of multiple same-named fitted columns.

`xtbreak.RegimeStatistics`

Frozen dataclass holding per-regime OLS regression statistics computed from the estimated break partition. One instance per regime (0-based indexing). Fields:

regime_index: int — regime number (0-based).
start_index: int — first observation index in this regime.
end_index: int — end observation index (exclusive).
n_observations: int — number of observations in this regime.
coefficients: tuple[float, ...] — OLS coefficient estimates β̂_j.
standard_errors: tuple[float, ...] — standard errors SE(β̂_j).
t_statistics: tuple[float, ...] — t-statistics for each coefficient.
r_squared: float — R² for this regime.
adjusted_r_squared: float — adjusted R² for this regime.
ssr: float — regime-specific residual sum of squares.

`xtbreak.ChowTestResult`

Frozen dataclass holding the result of a between-regime Chow F test for coefficient equality across adjacent regimes. Fields:

regime_j: int — index of the first regime in the pair.
regime_j_plus_1: int — index of the second regime in the pair.
f_statistic: float — the Chow F statistic.
p_value: float | None — p-value from the F distribution (None if scipy unavailable).
degrees_of_freedom: tuple[int, int] — (numerator_df, denominator_df).

`xtbreak.LazySegmentSSR`

Lazy SSR matrix that computes segment-level OLS residual sums of squares on demand with caching. For large T, avoids precomputing the full T×T matrix. Only segments that are actually requested are computed. Instances behave like a 2-D array (shape (T, T+1), ndim == 2) and support [i, j] indexing.

from xtbreak import LazySegmentSSR
import numpy as np

y = np.random.randn(200)
x = np.ones((200, 1))
ssr_matrix = LazySegmentSSR(y, x, min_segment=10)
print(ssr_matrix[0, 100])  # SSR for segment [0, 100)

Plotting Functions

All plotting functions require matplotlib as an optional dependency.

`xtbreak.plot_breaks`

plot_breaks(y, *, break_indices, time_values=None, ci_indices=None,
            title="Structural Breaks", figsize=(12, 5), ax=None)

Plot a time series with vertical lines at estimated break dates and optional confidence-interval shading. Returns the matplotlib Figure.

`xtbreak.plot_regime_fit`

plot_regime_fit(y, x, *, break_indices, time_values=None,
                title="Regime-Specific Fitted Values", figsize=(12, 5), ax=None)

Plot raw data with per-regime OLS fitted values (different colors per regime). Returns the matplotlib Figure.

`xtbreak.plot_ssr_path`

plot_ssr_path(ssr_path, *, time_values=None, break_index=None,
              title="SSR Path (Single Break)", figsize=(10, 5), ax=None)

Plot the SSR path for single-break estimation, showing SSR as a function of candidate break position with a vertical line at the optimal break. Returns the matplotlib Figure.

Utility Functions

`xtbreak.get_blas_info`

get_blas_info() -> dict[str, str]

Detect the BLAS library backing NumPy operations. Returns a dict with keys 'library' (mkl, openblas, accelerate, blas, or unknown), 'version', and 'threading'.

`xtbreak.LazySegmentSSR`

Lazy SSR matrix that computes segment-level OLS residual sums of squares on demand with caching. For large T, avoids precomputing the full T×T matrix. Only segments that are actually requested are computed. Instances behave like a 2-D array (shape (T, T+1), ndim == 2) and support [i, j] indexing.

from xtbreak import LazySegmentSSR
import numpy as np

y = np.random.randn(200)
x = np.ones((200, 1))
ssr_matrix = LazySegmentSSR(y, x, min_segment=10)
print(ssr_matrix[0, 100])  # SSR for segment [0, 100)

Plotting Functions

All plotting functions require matplotlib as an optional dependency.

`xtbreak.plot_breaks`

plot_breaks(y, *, break_indices, time_values=None, ci_indices=None,
            title="Structural Breaks", figsize=(12, 5), ax=None)

Plot a time series with vertical lines at estimated break dates and optional confidence-interval shading. Returns the matplotlib Figure.

`xtbreak.plot_regime_fit`

plot_regime_fit(y, x, *, break_indices, time_values=None,
                title="Regime-Specific Fitted Values", figsize=(12, 5), ax=None)

Plot raw data with per-regime OLS fitted values (different colors per regime). Returns the matplotlib Figure.

`xtbreak.plot_ssr_path`

plot_ssr_path(ssr_path, *, time_values=None, break_index=None,
              title="SSR Path (Single Break)", figsize=(10, 5), ax=None)

Plot the SSR path for single-break estimation, showing SSR as a function of candidate break position with a vertical line at the optimal break. Returns the matplotlib Figure.

Utility Functions

`xtbreak.get_blas_info`

get_blas_info() -> dict[str, str]

Detect the BLAS library backing NumPy operations. Returns a dict with keys 'library' (mkl, openblas, accelerate, blas, or unknown), 'version', and 'threading'.

`xtbreak.recommend_blas_optimization`

recommend_blas_optimization() -> str | None

Return an optimization recommendation string if a suboptimal BLAS is detected. Returns None when an optimized BLAS (MKL, OpenBLAS, Accelerate) is already in use.

Exceptions

`xtbreak.XTBreakError`

Base package exception.

`xtbreak.XTBreakValidationError`

Raised for invalid user-facing options or malformed matrix-shaped result payloads.

Internal Modules

The following modules are internal. They appear here only for auditability:

xtbreak._segments: segment-level OLS SSR and SSR matrices.
xtbreak._breakpoints: trimming-aware breakpoint enumeration.
xtbreak._dynamic: dynamic-programming break search and brute-force oracles.
xtbreak._statistics: SSR-based known-break F, supF, double-maximum, and additional-break statistics.
xtbreak._critical: critical-value records and sequential decision helpers.
xtbreak._result: result containers and Stata-shaped estimate hydration.
xtbreak._confidence: homoskedastic plug-in break-date confidence intervals for the current time-series and explicit-panel raw-data estimate slices.
xtbreak._panel: panel indexing, fixed-effect transforms, cross-section averages, panel segment SSR, and panel covariance grids.
xtbreak._covariance: SSR, HC0, Bartlett HAC OLS covariance helpers, plus explicit-panel np and wpn covariance helpers.
xtbreak._partial: partial structural-change search where selected regressors break and common regressors do not.

Outside the narrow single-break balanced-panel fixed-effects vce="ssr" nobreak_x slice, panel raw-data partial structural-change requests that require Stata nobreakvariables(...) semantics remain a public validation boundary. The Phase 45 crosswalk at .planning/phases/45-panel-partial-structural-change-crosswalk/45-CONTEXT.md records the methodology-paper x/w split, Stata dynamicpartial handoff, and future oracle prerequisites.

Internal module names and signatures can still change before a public release.

xtbreak API Reference

Runtime Dependencies

Source Authority

Public API and Deprecation Policy

Stata Migration Boundaries

Public Entry Points

xtbreak.test(...)

xtbreak.estimate(...)

xtbreak.select(...)

New Parameters (test / estimate / select)

Result Containers

xtbreak.CommandType

xtbreak.XTBreakResult

xtbreak.EstimateResult

xtbreak.BreakSelectionResult

xtbreak.EstimateBreak

xtbreak.FittedSample

xtbreak.RegimeStatistics

xtbreak.ChowTestResult

xtbreak.LazySegmentSSR

Plotting Functions

xtbreak.plot_breaks

xtbreak.plot_regime_fit

xtbreak.plot_ssr_path

Utility Functions

xtbreak.get_blas_info

xtbreak.recommend_blas_optimization

xtbreak.LazySegmentSSR

Plotting Functions

xtbreak.plot_breaks

xtbreak.plot_regime_fit

xtbreak.plot_ssr_path

Utility Functions

xtbreak.get_blas_info

xtbreak.recommend_blas_optimization

Exceptions

xtbreak.XTBreakError

xtbreak.XTBreakValidationError

Internal Modules

`xtbreak.test(...)`

`xtbreak.estimate(...)`

`xtbreak.select(...)`

`xtbreak.CommandType`

`xtbreak.XTBreakResult`

`xtbreak.EstimateResult`

`xtbreak.BreakSelectionResult`

`xtbreak.EstimateBreak`

`xtbreak.FittedSample`

`xtbreak.RegimeStatistics`

`xtbreak.ChowTestResult`

`xtbreak.LazySegmentSSR`

`xtbreak.plot_breaks`

`xtbreak.plot_regime_fit`

`xtbreak.plot_ssr_path`

`xtbreak.get_blas_info`

`xtbreak.recommend_blas_optimization`

`xtbreak.LazySegmentSSR`

`xtbreak.plot_breaks`

`xtbreak.plot_regime_fit`

`xtbreak.plot_ssr_path`

`xtbreak.get_blas_info`

`xtbreak.recommend_blas_optimization`

`xtbreak.XTBreakError`

`xtbreak.XTBreakValidationError`