Latency and jitter analysis

jitterbug.analysis.latency_jump_analyzer

Latency jump analysis implementation.

LatencyJumpAnalyzer

Analyzer for detecting significant latency jumps.

Identifies periods where the baseline latency increases significantly compared to the previous period.

Parameters:

Name	Type	Description	Default
config	LatencyJumpConfig	Configuration for latency jump analysis.	required

analyze(dataset, change_points)

Analyze latency jumps between change points.

Parameters:

Name	Type	Description	Default
dataset	MinimumRTTDataset	Dataset containing minimum RTT values.	required
change_points	List[ChangePoint]	List of detected change points.	required

Returns:

Type	Description
List[LatencyJump]	List of latency jump analysis results.

get_jump_statistics(latency_jumps)

Calculate statistics for latency jumps.

Parameters:

Name	Type	Description	Default
latency_jumps	List[LatencyJump]	List of latency jump results.	required

Returns:

Type	Description
dict	Dictionary containing jump statistics.

jitterbug.analysis.jitter_analyzer

Jitter analysis implementation.

JitterAnalyzer

Analyzer for jitter-based congestion detection.

Supports two methods: 1. Jitter dispersion analysis 2. Kolmogorov-Smirnov test

Parameters:

Name	Type	Description	Default
config	JitterAnalysisConfig	Configuration for jitter analysis.	required

causal_dispersion_lag property

Jitter samples consumed before the causal dispersion series yields its first value.

The trailing IQR window holds 2 * moving_iqr_order + 1 jitter samples and the trailing average moving_average_order IQR values, so the first dispersion value exists at jitter index 2 * moving_iqr_order + moving_average_order - 1, and the value at index t summarizes jitter samples t - lag .. t.

causal_dispersion_delay property

Samples by which the causal dispersion series lags the offline (centered) one.

analyze_jitter_dispersion(dataset, change_points)

Analyze jitter using dispersion method.

Parameters:

Name	Type	Description	Default
dataset	MinimumRTTDataset	Dataset containing minimum RTT values.	required
change_points	List[ChangePoint]	List of detected change points.	required

Returns:

Type	Description
List[JitterAnalysis]	List of jitter analysis results.

analyze_ks_test(dataset, change_points)

Analyze jitter using Kolmogorov-Smirnov test.

Parameters:

Name	Type	Description	Default
dataset	RTTDataset	Dataset containing RTT measurements.	required
change_points	List[ChangePoint]	List of detected change points.	required

Returns:

Type	Description
List[JitterAnalysis]	List of jitter analysis results.

compute_causal_jitter_dispersion(epochs, rtt_values)

Jitter dispersion with trailing filters, for the online mode.

Same filters and window lengths as _compute_jitter_dispersion (moving IQR of 2 * moving_iqr_order + 1 samples, then moving average of moving_average_order values), but each window ends at the sample it is assigned to instead of being centered on it, so a value never depends on later samples. The values are the offline ones; each is assigned to the last sample of its window instead of the (rounded) middle, so the series is the offline one delayed by causal_dispersion_delay samples (6 bins, 1.5 h, by default), and the threshold keeps its meaning.

Parameters:

Name	Type	Description	Default
epochs	ndarray	Epochs of the minimum-RTT series.	required
rtt_values	ndarray	Minimum RTT per bin.	required

Returns:

Type	Description
tuple[ndarray, ndarray]	(epochs, dispersion): the epoch of the last sample each value depends on, and the dispersion. Empty when fewer than causal_dispersion_lag + 2 samples are available.

jitterbug.analysis.congestion_inference_analyzer

Congestion inference analysis implementation.

CongestionInferenceAnalyzer

Analyzer for inferring congestion based on latency jumps and jitter analysis.

Combines results from latency jump detection and jitter analysis to make final congestion inferences.

infer(latency_jumps, jitter_analyses)

Infer congestion periods based on latency jumps and jitter analysis.

Uses the original v1 stateful congestion inference logic: - Congestion = True when BOTH latency jump AND jitter are detected - Congestion = False when there's NO latency jump (regardless of jitter) - Maintains congestion state between periods

Parameters:

Name	Type	Description	Default
latency_jumps	List[LatencyJump]	List of latency jump analysis results.	required
jitter_analyses	List[JitterAnalysis]	List of jitter analysis results.	required

Returns:

Type	Description
List[CongestionInference]	List of congestion inference results.

get_inference_statistics(inferences)

Calculate statistics for congestion inferences.

Parameters:

Name	Type	Description	Default
inferences	List[CongestionInference]	List of congestion inference results.	required

Returns:

Type	Description
dict	Dictionary containing inference statistics.

jitterbug.analysis.clustering_analyzer

Non-sequential congestion inference: cluster minimum-RTT intervals by (latency, jitter).

The sequential method (PAM 2022) splits the series at change points and compares each period with the one before it. This mode drops the time order: every minimum-RTT interval is a point with two features (its minimum RTT and the interquartile range of the jitter samples inside it), the points are clustered, and each cluster is compared with the baseline cluster (lowest median minimum RTT), no matter whether their intervals are adjacent in time. A cluster is congested when both signals of the paper hold: its median minimum RTT exceeds the baseline's by more than the latency threshold, and the raw jitter samples of the two clusters differ (a significant Kolmogorov-Smirnov test whose statistic reaches a minimum effect size). Consecutive intervals with the same verdict are merged into periods, after an optional temporal smoothing, so the output has the same shape as the sequential mode.

IntervalFeatures dataclass

Minimum-RTT intervals with the features used for clustering.

Attributes:

Name	Type	Description
starts	ndarray	Start of each interval (epoch seconds, UTC), sorted.
min_rtt	ndarray	Minimum RTT of each interval (ms).
jitter_iqr	ndarray	Interquartile range of the jitter samples of each interval (ms).
jitter	list[ndarray]	Raw jitter samples (differences of consecutive RTTs) of each interval.
interval_seconds	float	Interval length in seconds.
skipped	int	Non-empty intervals left out because they have fewer than two jitter samples.

ClusterSummary dataclass

Statistics and verdict for one cluster.

Attributes:

Name	Type	Description
cluster	int	Cluster index; clusters are numbered by increasing median minimum RTT, so 0 is always the baseline.
size	int	Number of intervals in the cluster.
median_min_rtt	float	Median minimum RTT of its intervals (ms).
median_jitter_iqr	float	Median jitter IQR of its intervals (ms).
latency_jump	float	median_min_rtt minus the baseline's (ms).
ks_statistic	float | None	Kolmogorov-Smirnov statistic against the baseline's jitter (None for the baseline).
p_value	float | None	p-value of that test (None for the baseline).
is_congested	bool	Whether the cluster is classified as congested.

ClusteringResult dataclass

Output of :meth:ClusteringCongestionAnalyzer.analyze.

Attributes:

Name	Type	Description
inferences	list[CongestionInference]	Periods of consecutive intervals with the same verdict, in time order.
clusters	list[ClusterSummary]	One summary per cluster, baseline first.
labels	ndarray	Cluster of each interval.
selection_scores	dict[int, float]	Model-selection score per number of clusters tried (BIC for gmm, lower is better; silhouette for kmeans_silhouette, higher is better); empty for kmeans.
intervals	int	Intervals clustered.
intervals_skipped	int	Non-empty intervals left out for having fewer than two jitter samples.

metadata(algorithm)

Return a JSON-serializable summary for CongestionInferenceResult.metadata.

ClusteringCongestionAnalyzer

Infer congestion by clustering minimum-RTT intervals (non-sequential mode).

Parameters:

Name	Type	Description	Default
config	ClusteringConfig	Clustering options.	required
latency_threshold	float	Minimum excess of a cluster's median minimum RTT over the baseline's (ms), from clustering.latency_threshold or else latency_jump.threshold.	required
significance_level	float	Significance level of the KS test, from jitter_analysis.significance_level.	required
interval_minutes	int	Minimum-RTT interval length, from data_processing.minimum_interval_minutes.	required

analyze(rtt_data)

Cluster the intervals of rtt_data and classify each cluster.

Parameters:

Name	Type	Description	Default
rtt_data	RTTDataset	Raw RTT measurements.	required

Returns:

Type	Description
ClusteringResult	Periods, per-cluster summaries and model-selection scores. With fewer than two usable intervals the result is empty.

Raises:

Type	Description
ImportError	If scikit-learn is not installed.

compute_interval_features(rtt_data, interval_minutes)

Bin raw RTTs into minimum-RTT intervals and compute the clustering features.

The bins are the same as RTTDataset.compute_minimum_intervals. Jitter is the difference between consecutive RTTs, assigned to the interval of the later sample.

Parameters:

Name	Type	Description	Default
rtt_data	RTTDataset	Raw RTT measurements.	required
interval_minutes	int	Interval length in minutes.	required

Returns:

Type	Description
IntervalFeatures	Intervals with at least two jitter samples, sorted by start time.

smooth_labels(congested, starts, step, window)

Remove short gaps and short bursts from per-interval congestion labels.

Within each block of contiguous intervals, runs of at most window non-congested intervals that lie between congested ones are relabeled congested; then congested runs of at most window intervals are relabeled non-congested. A missing interval (a gap in the data) always ends a block.

Parameters:

Name	Type	Description	Default
congested	ndarray	Boolean label per interval, in time order.	required
starts	ndarray	Interval start times (epoch seconds), same order.	required
step	float	Interval length in seconds.	required
window	int	Largest run length to fill or drop; 0 returns a copy of congested.	required

Returns:

Type	Description
ndarray	Smoothed boolean labels.