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, <warith.harchaoui@deraison.ai>

class elbow_helper.config.RobustKneeConfig(min_samples=20, 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), min_spearman_abs=0.6, max_direction_violation_rate=0.25, boundary_margin=0.1, 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_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, 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)

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

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

  • min_spearman_abs (float)

  • max_direction_violation_rate (float)

  • boundary_margin (float)

  • 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_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)

  • random_seed (int | None)

bootstrap_replicates: int = 100
boundary_margin: float = 0.1
cluster_tolerance: float = 0.06
cv_folds: int = 5
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
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