Configuration

jitterbug.models.config

Configuration models using Pydantic for validation and serialization.

ChangePointDetectionConfig

Bases: BaseModel

Configuration for change point detection algorithms.

Attributes:

Name	Type	Description
algorithm	Literal['bcp', 'ruptures']	Algorithm to use for change point detection.
threshold	float	Threshold for change point detection sensitivity.
min_time_elapsed	int	Minimum time in seconds between change points.
max_change_points	Optional[int]	Maximum number of change points to detect.

JitterAnalysisConfig

Bases: BaseModel

Configuration for jitter analysis methods.

Attributes:

Name	Type	Description
method	Literal['jitter_dispersion', 'ks_test']	Method to use for jitter analysis.
threshold	float	Threshold for significance testing.
moving_average_order	int	Order of moving average filter (must be even).
moving_iqr_order	int	Order of moving IQR filter.
significance_level	float	Statistical significance level for tests.

LatencyJumpConfig

Bases: BaseModel

Configuration for latency jump detection.

Attributes:

Name	Type	Description
threshold	float	Threshold for latency jump detection.

DataProcessingConfig

Bases: BaseModel

Configuration for data processing.

Attributes:

Name	Type	Description
minimum_interval_minutes	int	Interval in minutes for computing minimum RTT values.
min_samples_per_interval	int	Minimum number of samples required per interval.
outlier_detection	bool	Whether to perform outlier detection.
outlier_threshold	float	Z-score threshold for outlier detection.

ClusteringConfig

Bases: BaseModel

Configuration for the non-sequential (clustering) analysis mode.

Each minimum-RTT interval becomes one point with two features, its minimum RTT and the interquartile range of the jitter samples inside it. The points are clustered without regard to time; the cluster with the lowest median minimum RTT is the baseline, and every other cluster is congested when its median minimum RTT exceeds the baseline by more than the latency threshold and the jitter samples of the two clusters differ: a Kolmogorov-Smirnov test is significant at jitter_analysis.significance_level and its statistic is at least min_ks_statistic.

Attributes:

Name	Type	Description
algorithm	Literal['gmm', 'kmeans', 'kmeans_silhouette']	gmm: Gaussian mixture with the number of components chosen by BIC among 1..max_clusters (one component means no congestion signal). kmeans: k-means with n_clusters clusters. kmeans_silhouette: k-means with the number of clusters in 2..max_clusters that maximizes the silhouette score.
n_clusters	int	Number of clusters for kmeans.
max_clusters	int	Largest number of clusters tried by gmm and kmeans_silhouette.
min_period_intervals	int	Temporal smoothing, in intervals: gaps of at most this many non-congested intervals inside congestion are filled, then congested runs of at most this many intervals are dropped. 0 keeps the raw per-interval labels.
random_state	int	Seed for the clustering algorithms, so results are reproducible.
latency_threshold	float | None	Minimum excess of a cluster's median minimum RTT over the baseline's (ms). None uses latency_jump.threshold, the threshold of the sequential mode.
min_ks_statistic	float	Smallest Kolmogorov-Smirnov statistic (the largest gap between the two empirical jitter distributions, 0-1) that counts as a jitter change. Clusters pool thousands of samples, so the p-value alone is significant for negligible differences; this bounds the effect size. 0 relies on the p-value only.

StreamingConfig

Bases: BaseModel

Settings of the online (streaming) mode, jitterbug.streaming.OnlineJitterbug.

The online mode reuses the sequential decision rule: minimum-RTT bins of data_processing.minimum_interval_minutes, the latency jump threshold of latency_jump.threshold, the significance level of jitter_analysis.significance_level and the device of change_point_detection.bcp_device. The fields below are specific to the Bayesian online change point detector and to the two-stage verdicts.

Attributes:

Name	Type	Description
backend	Literal['bocpd', 'window']	bocpd (default): incremental Bayesian online change point detection, one bin at a time. window: rerun the offline sequential pipeline on a trailing window of window_hours every rerun_every_bins closed bins and emit a verdict once it has been identical in stable_runs consecutive reruns. The baseline the incremental detector is compared with; heavier per bin, no new algorithm.
window_hours	float	Length of the trailing window of the window back end, in hours.
rerun_every_bins	int	Closed bins between two reruns of the window back end.
stable_runs	int	Consecutive reruns in which a change point or a verdict must be identical before the window back end emits it.
hazard_lambda	float	Expected run length in bins (constant hazard 1 / hazard_lambda).
decision	Literal['map', 'lag', 'window']	Change point rule. map (default) fires when the most probable run length drops; lag thresholds the posterior that a segment started exactly lag bins ago; window thresholds the posterior that it started within the last lag bins and places the change at the most probable run length.
lag	int	Decision delay in bins for the lag and window rules.
threshold	float	Posterior threshold for the lag and window rules.
max_run_length	int or None	Run lengths kept by the detector (bounds memory and time per bin); None keeps the exact posterior.
min_time_elapsed	int	Minimum seconds between change points. The MAP rule refines a boundary a few bins after first reporting it; one hour absorbs those refinements.
prior_alpha, prior_beta, prior_kappa	float	Normal-Gamma prior of the Student-t predictive (see online_likelihoods.StudentT).
prior_mu	float or None	Prior mean; None uses the first minimum RTT seen.
min_ks_statistic	float	Smallest Kolmogorov-Smirnov statistic that counts as a jitter change (effect-size guard, 0-1); 0 relies on the p-value only.
min_period_samples	int	Jitter samples the open period must hold before a provisional verdict. About three 15-minute bins on the paper dataset; 30 gives noisy p-values. With jitter_analysis.method: jitter_dispersion the verdict also waits for enough causal dispersion values (JitterAnalyzer.causal_dispersion_delay plus moving_average_order bins).

JitterbugConfig

Bases: BaseSettings

Main configuration class for Jitterbug.

Attributes:

Name	Type	Description
analysis_mode	Literal['sequential', 'clustering']	sequential (default) is the PAM 2022 method: change points split the series and each period is compared with the previous one. clustering groups minimum-RTT intervals by (latency, jitter) regardless of when they occur and compares each cluster with the baseline one; see ClusteringConfig.
change_point_detection	ChangePointDetectionConfig	Configuration for change point detection.
jitter_analysis	JitterAnalysisConfig	Configuration for jitter analysis.
latency_jump	LatencyJumpConfig	Configuration for latency jump detection.
data_processing	DataProcessingConfig	Configuration for data processing.
clustering	ClusteringConfig	Configuration for the clustering mode.
streaming	StreamingConfig	Configuration for the online (streaming) mode.
output_format	Literal['json', 'csv', 'parquet']	Output format for results.
verbose	bool	Whether to enable verbose logging.

from_file(config_path) classmethod

Load configuration from file.

Parameters:

Name	Type	Description	Default
config_path	Path	Path to configuration file (YAML or JSON).	required

Returns:

Type	Description
JitterbugConfig	Loaded configuration.

to_file(config_path)

Save configuration to file.

Parameters:

Name	Type	Description	Default
config_path	Path	Path to save configuration file.	required