elbow_helper.config module

Configuration for the robust knee detector.

All positional thresholds are expressed in normalized x-range units (the x-axis is scaled to [0, 1] during preprocessing), so they are independent of the absolute scale of the caller’s data.

The defaults follow the “first practical prototype” scope: modest replicate counts so the full pipeline runs in seconds. For validation-grade runs raise bootstrap_replicates to 500 and null_replicates to 1000.

Author

Warith Harchaoui, <warithmetics@deraison.ai>

class elbow_helper.config.RobustKneeConfig(min_samples=20, despike_window=3, positional_floor_samples=2.0, smoothing_fractions=(0.0, 0.02, 0.03, 0.05, 0.08, 0.12, 0.18, 0.25), sensitivity_fractions=(0.0, 0.01, 0.02, 0.05), fine_scale_span=0, min_spearman_abs=0.6, max_direction_violation_rate=0.25, boundary_margin=0.03, boundary_min_samples=5, min_side_points=5, min_prominence=0.05, min_noise_prominence_ratio=4.0, cluster_tolerance=0.06, min_consecutive_scales=3, min_sensitivity_support=0.7, max_cluster_mad=0.03, max_neighbor_shift=0.07, secondary_support_frac=0.3, min_dominance_ratio=2.0, slope_left_window=(0.15, 0.03), slope_right_window=(0.03, 0.15), min_slope_contrast=0.3, min_cv_improvement=0.1, min_bic_improvement=10.0, cv_folds=5, bootstrap_signal_window=5, bootstrap_replicates=100, min_bootstrap_detection_rate=0.9, max_ci90_width=0.1, min_primary_cluster_rate=0.8, max_secondary_cluster_rate=0.15, max_bootstrap_median_shift=0.03, null_replicates=200, max_null_p_value=0.01, language='en', random_seed=None)[source]

Bases: object

Immutable bundle of thresholds and search settings.

Use with_() to derive a tweaked copy (the dataclass is frozen).

Parameters:

  • min_samples (int)

  • despike_window (int)

  • positional_floor_samples (float)

  • smoothing_fractions (Tuple[float, ...])

  • sensitivity_fractions (Tuple[float, ...])

  • fine_scale_span (int)

  • min_spearman_abs (float)

  • max_direction_violation_rate (float)

  • boundary_margin (float)

  • boundary_min_samples (int)

  • min_side_points (int)

  • min_prominence (float)

  • min_noise_prominence_ratio (float)

  • cluster_tolerance (float)

  • min_consecutive_scales (int)

  • min_sensitivity_support (float)

  • max_cluster_mad (float)

  • max_neighbor_shift (float)

  • secondary_support_frac (float)

  • min_dominance_ratio (float)

  • slope_left_window (Tuple[float, float])

  • slope_right_window (Tuple[float, float])

  • min_slope_contrast (float)

  • min_cv_improvement (float)

  • min_bic_improvement (float)

  • cv_folds (int)

  • bootstrap_signal_window (int)

  • bootstrap_replicates (int)

  • min_bootstrap_detection_rate (float)

  • max_ci90_width (float)

  • min_primary_cluster_rate (float)

  • max_secondary_cluster_rate (float)

  • max_bootstrap_median_shift (float)

  • null_replicates (int)

  • max_null_p_value (float)

  • language (str)

  • random_seed (int | None)

bootstrap_replicates: int = 100
bootstrap_signal_window: int = 5
boundary_margin: float = 0.03
boundary_min_samples: int = 5
cluster_tolerance: float = 0.06
cv_folds: int = 5
despike_window: int = 3
fine_scale_span: int = 0
language: str = 'en'
max_bootstrap_median_shift: float = 0.03
max_ci90_width: float = 0.1
max_cluster_mad: float = 0.03
max_direction_violation_rate: float = 0.25
max_neighbor_shift: float = 0.07
max_null_p_value: float = 0.01
max_secondary_cluster_rate: float = 0.15
min_bic_improvement: float = 10.0
min_bootstrap_detection_rate: float = 0.9
min_consecutive_scales: int = 3
min_cv_improvement: float = 0.1
min_dominance_ratio: float = 2.0
min_noise_prominence_ratio: float = 4.0
min_primary_cluster_rate: float = 0.8
min_prominence: float = 0.05
min_samples: int = 20
min_sensitivity_support: float = 0.7
min_side_points: int = 5
min_slope_contrast: float = 0.3
min_spearman_abs: float = 0.6
null_replicates: int = 200
positional(threshold, n, samples=None)[source]

Widen a positional threshold to at least the x sampling resolution.

Thresholds on normalized x are written as curve fractions, but the quantity they bound is quantized at the sample spacing h = 1 / (n - 1): on a 49-point curve a single sample is already 0.021 of the range, so a 0.03 tolerance leaves no room for the one-to-two-sample jitter the locator inevitably has. This returns the threshold widened to samples * h whenever the grid is coarser than the constant, and leaves it untouched on finely sampled curves.

Parameters:

  • threshold (float) – The configured tolerance, in normalized x units.

  • n (int) – Number of samples on the curve.

  • samples (float, optional) – Number of sample spacings to floor at. Defaults to positional_floor_samples.

Returns:

max(threshold, samples / (n - 1)).

Return type:

float

positional_floor_samples: float = 2.0
random_seed: int | None = None
secondary_support_frac: float = 0.3
sensitivity_fractions: Tuple[float, ...] = (0.0, 0.01, 0.02, 0.05)
slope_left_window: Tuple[float, float] = (0.15, 0.03)
slope_right_window: Tuple[float, float] = (0.03, 0.15)
smoothing_fractions: Tuple[float, ...] = (0.0, 0.02, 0.03, 0.05, 0.08, 0.12, 0.18, 0.25)
with_(**changes)[source]

Return a copy of this config with changes applied.

Parameters:

**changes – Field overrides, e.g. config.with_(bootstrap_replicates=500).

Returns:

A new, independent configuration.

Return type:

RobustKneeConfig

class elbow_helper.config.RobustKneesConfig(min_samples=20, k_max=4, min_seg_fraction=0.08, fwer_alpha=0.05, fwer_permutations=200, require_fwer_confirmation=True, random_seed=None)[source]

Bases: object

Immutable settings for elbow_helper.robust_knees() (plural).

The multi-knee search ships the combination validated in research/multiknee/RESULTS.md: dynamic-program search, the subtractive-sign modified BIC as the selection criterion, and a Bonferroni-gated sequential permutation test layered on top by default, matching this package’s design priority of minimising false-positive knees. Use with_() to derive a tweaked copy.

Parameters:

  • min_samples (int)

  • k_max (int)

  • min_seg_fraction (float)

  • fwer_alpha (float)

  • fwer_permutations (int)

  • require_fwer_confirmation (bool)

  • random_seed (int | None)

fwer_alpha: float = 0.05
fwer_permutations: int = 200
k_max: int = 4
min_samples: int = 20
min_seg_fraction: float = 0.08
random_seed: int | None = None
require_fwer_confirmation: bool = True
with_(**changes)[source]

Return a copy of this config with changes applied.

Return type:

RobustKneesConfig