Diagnostics API

Power-law diagnostics, scale sensitivity analysis, and structural break detection.

PowerLawDiagnostics

class lrdbenchmark.analysis.diagnostics.PowerLawDiagnostics(min_r_squared: float = 0.5, min_points: int = 6)[source]

Comprehensive diagnostics for power-law fits in LRD estimation. Includes log-log checks, residual analysis, and goodness-of-fit tests.

__init__(min_r_squared: float = 0.5, min_points: int = 6)[source]

Initialise power-law diagnostics.

Parameters:

  • min_r_squared (float) – Minimum R² threshold for acceptable fits

  • min_points (int) – Minimum number of scale points required

diagnose(scales: ndarray, statistics: ndarray, slope: float | None = None, intercept: float | None = None) → Dict[str, Any][source]

Run comprehensive diagnostic suite on power-law fit.

Parameters:

  • scales (np.ndarray) – Scale values (e.g., frequencies, windows, wavelet scales)

  • statistics (np.ndarray) – Corresponding statistics (e.g., PSD, fluctuation function)

  • slope (float, optional) – Pre-computed slope of log-log fit

  • intercept (float, optional) – Pre-computed intercept of log-log fit

Returns:

Comprehensive diagnostic results

Return type:

dict

_check_linearity(log_scales: ndarray, log_stats: ndarray, r_squared: float) → Dict[str, Any][source]

Check linearity of log-log relationship.

_analyse_residuals(log_scales: ndarray, log_stats: ndarray, slope: float, intercept: float) → Dict[str, Any][source]

Comprehensive residual analysis.

_compute_acf(data: ndarray, n_lags: int) → ndarray[source]

Compute autocorrelation function.

_assess_goodness_of_fit(log_scales: ndarray, log_stats: ndarray, slope: float, intercept: float) → Dict[str, Any][source]

Assess goodness-of-fit using multiple criteria.

_detect_breakpoints(log_scales: ndarray, log_stats: ndarray) → Dict[str, Any][source]

Detect potential breakpoints in log-log relationship.

_compute_quality_score(linearity_check: Dict[str, Any], residual_analysis: Dict[str, Any], r_squared: float) → float[source]

Compute overall quality score (0-1 scale).

_generate_warnings(linearity_check: Dict[str, Any], residual_analysis: Dict[str, Any], breakpoint_detection: Dict[str, Any]) → List[str][source]

Generate human-readable warnings based on diagnostics.

ScaleWindowSensitivityAnalyser

class lrdbenchmark.analysis.diagnostics.ScaleWindowSensitivityAnalyser(perturbation_levels: List[float] | None = None, leave_one_out: bool = True)[source]

Analyse sensitivity of H estimates to scale window selection.

__init__(perturbation_levels: List[float] | None = None, leave_one_out: bool = True)[source]

Initialise scale window sensitivity analyser.

Parameters:

  • perturbation_levels (list of float, optional) – Multiplicative perturbation factors to apply to scale bounds

  • leave_one_out (bool) – Whether to perform leave-one-out analysis

analyse(estimator, data: ndarray, base_result: Dict[str, Any], original_scales: ndarray | None = None) → Dict[str, Any][source]

Analyse sensitivity to scale window perturbations.

Parameters:

  • estimator (BaseEstimator) – Estimator instance to test

  • data (np.ndarray) – Input data

  • base_result (dict) – Baseline estimation result

  • original_scales (np.ndarray, optional) – Original scale values used

Returns:

Sensitivity analysis results

Return type:

dict

_perturb_and_estimate(estimator, data: ndarray, factor: float) → Dict[str, Any][source]

Apply perturbation and re-estimate.

_leave_one_out_analysis(estimator, data: ndarray, base_h: float, scales: ndarray) → List[Dict[str, Any]][source]

Leave-one-out influence analysis. Note: This is a placeholder; full implementation would require access to internal scale computation in each estimator.

_interpret_sensitivity(summary: Dict[str, Any]) → str[source]

Generate interpretation of sensitivity results.

StructuralBreakDetector

Detect stationarity violations that invalidate classical estimator assumptions.

class lrdbenchmark.analysis.diagnostics.StructuralBreakDetector(significance_level: float = 0.05, min_segment_length: int = 50)[source]

Detector for structural breaks in time series.

Implements multiple tests for detecting change points that would invalidate the stationarity assumptions required by classical LRD estimators.

cusum_test : Standard CUSUM test for mean shifts
recursive_cusum : Sequential/online CUSUM detection
chow_test : Test for known break point
icss_algorithm : Iterative Cumulative Sum of Squares for variance changes
detect_all : Run all tests and return comprehensive results
__init__(significance_level: float = 0.05, min_segment_length: int = 50)[source]

Initialize structural break detector.

Parameters:

  • significance_level (float) – Significance level for hypothesis tests

  • min_segment_length (int) – Minimum segment length for break detection

cusum_test(data: ndarray, normalize: bool = True) → Dict[str, Any][source]

Standard CUSUM test for detecting mean shifts.

The CUSUM (Cumulative Sum) test detects changes in the mean of a time series by monitoring cumulative deviations from the sample mean.

Parameters:

  • data (np.ndarray) – Input time series

  • normalize (bool) – Whether to normalize the CUSUM statistic

Returns:

Test results including: - statistic: Maximum absolute CUSUM value - critical_value: Critical value at significance level - break_detected: Whether a break was detected - break_index: Estimated break location (if detected) - cusum_path: Full CUSUM path for visualization

Return type:

dict

_cusum_pvalue(statistic: float) → float[source]

Approximate p-value for CUSUM statistic.

recursive_cusum(data: ndarray, window_size: int | None = None) → Dict[str, Any][source]

Recursive CUSUM for sequential/online break detection.

Monitors the process sequentially and detects when the cumulative sum exceeds threshold, suitable for online monitoring.

Parameters:

  • data (np.ndarray) – Input time series

  • window_size (int, optional) – Initial window for establishing baseline

Returns:

Detection results including break points and timing

Return type:

dict

chow_test(data: ndarray, break_index: int | None = None) → Dict[str, Any][source]

Chow test for structural break at a known or estimated point.

Tests whether regression coefficients (here, just the mean) differ before and after a specified break point.

Parameters:

  • data (np.ndarray) – Input time series

  • break_index (int, optional) – Index of hypothesized break. If None, tests at midpoint.

Returns:

Test results including F-statistic and p-value

Return type:

dict

icss_algorithm(data: ndarray, max_iterations: int = 100) → Dict[str, Any][source]

Iterative Cumulative Sum of Squares (ICSS) algorithm.

Detects multiple variance change points using the algorithm of Inclán and Tiao (1994).

Parameters:

  • data (np.ndarray) – Input time series

  • max_iterations (int) – Maximum iterations for refinement

Returns:

Detected variance change points

Return type:

dict

detect_all(data: ndarray, include_paths: bool = False) → Dict[str, Any][source]

Run all structural break tests and return comprehensive results.

Parameters:

  • data (np.ndarray) – Input time series

  • include_paths (bool) – Whether to include full paths (can be large)

Returns:

Comprehensive break detection results with warnings

Return type:

dict

Example Usage

from lrdbenchmark.analysis.diagnostics import StructuralBreakDetector

detector = StructuralBreakDetector(significance_level=0.05)

# Run all tests
result = detector.detect_all(data)

if result['any_break_detected']:
    print("⚠️ Stationarity violated!")
    for warning in result['warnings']:
        print(f"  - {warning}")

# Individual tests
cusum_result = detector.cusum_test(data)
chow_result = detector.chow_test(data, break_index=500)
icss_result = detector.icss_algorithm(data)

Utility Functions

lrdbenchmark.analysis.diagnostics.run_comprehensive_diagnostics(scales: ndarray, statistics: ndarray, estimator=None, data: ndarray | None = None, config: Dict[str, Any] | None = None) → Dict[str, Any][source]

Run complete diagnostic suite on power-law fit.

Parameters:

  • scales (np.ndarray) – Scale values

  • statistics (np.ndarray) – Corresponding statistics

  • estimator (BaseEstimator, optional) – Estimator instance for sensitivity analysis

  • data (np.ndarray, optional) – Original data for sensitivity analysis

  • config (dict, optional) – Configuration dict with diagnostic settings

Returns:

Complete diagnostic results

Return type:

dict