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.

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.
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