value_distribution

value_distribution ¤

ValueDistributionEvents ¤

ValueDistributionEvents(
    dataframe: DataFrame,
    signal_uuid: str,
    *,
    event_uuid: str = "quality:distribution",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Quality: Value Distribution Analysis

Answer the question "is my process behaving normally?" by examining the statistical distribution of a numeric signal over time.

Methods: - detect_mode_changes: Detect shifts between distinct operating modes. - detect_bimodal: Test whether the signal has a bimodal distribution. - normality_windows: Flag time windows with non-normal distributions. - percentile_tracking: Track selected percentiles over time windows.

detect_mode_changes ¤

detect_mode_changes(
    window: str = "1h",
    n_modes: int = 2,
    min_separation: float = 1.0,
) -> pd.DataFrame

Detect shifts between distinct operating modes.

Splits the signal into time windows, computes the histogram peaks (modes) in each window, and flags when the dominant mode shifts.

Parameters:

Name	Type	Description	Default
`window`	`str`	Time window for analysis.	`'1h'`
`n_modes`	`int`	Maximum number of modes to look for per window.	`2`
`min_separation`	`float`	Minimum separation between modes in units of the signal's standard deviation to count as distinct.	`1.0`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: window_start, dominant_mode,
`DataFrame`	n_modes_detected, mode_values, mode_changed.

detect_bimodal ¤

detect_bimodal(min_samples: int = 30) -> pd.DataFrame

Test whether the overall signal distribution is bimodal.

Uses Hartigan's dip test statistic approximated via the sorted data's inter-mode gap relative to overall range. A simpler, dependency-free alternative to the full dip test.

Parameters:

Name	Type	Description	Default
`min_samples`	`int`	Minimum sample count required to run the test.	`30`

Returns:

Type	Description
`DataFrame`	Single-row DataFrame with columns: is_bimodal, dip_score,
`DataFrame`	n_samples, mode_1, mode_2, valley.

normality_windows ¤

normality_windows(
    freq: str = "1h",
    alpha: float = 0.05,
    min_samples: int = 20,
) -> pd.DataFrame

Flag time windows whose values are not normally distributed.

Uses the Shapiro-Wilk test per window.

Parameters:

Name	Type	Description	Default
`freq`	`str`	Resample frequency.	`'1h'`
`alpha`	`float`	Significance level for the normality test.	`0.05`
`min_samples`	`int`	Minimum samples per window to run the test.	`20`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: window_start, n_samples, is_normal,
`DataFrame`	p_value, skewness, kurtosis.

percentile_tracking ¤

percentile_tracking(
    percentiles: Sequence[float] = (5, 25, 50, 75, 95),
    freq: str = "1h",
) -> pd.DataFrame

Track selected percentiles over time windows.

Useful for spotting distribution spread changes even when the mean stays constant.

Parameters:

Name	Type	Description	Default
`percentiles`	`Sequence[float]`	Percentile values to track (0-100).	`(5, 25, 50, 75, 95)`
`freq`	`str`	Resample frequency.	`'1h'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: window_start, n_samples, plus one
`DataFrame`	column per percentile (e.g. `p5`, `p95`).