Data models¶
jitterbug.models.rtt_data
¶
RTT data models using Pydantic for validation and serialization.
MAX_RTT_MS = 10000.0
module-attribute
¶
Largest RTT accepted, in milliseconds (10 s); larger values are treated as bad samples.
RTTMeasurement
¶
Bases: BaseModel
Represents a single RTT measurement.
Attributes:
| Name | Type | Description |
|---|---|---|
timestamp |
datetime
|
When the measurement was taken. |
epoch |
float
|
Unix timestamp of the measurement. |
rtt_value |
float
|
Round-trip time value in milliseconds. |
source |
Optional[str]
|
Source identifier or IP address. |
destination |
Optional[str]
|
Destination identifier or IP address. |
RTTDataset
¶
Bases: BaseModel
Collection of RTT measurements with validation and processing capabilities.
Attributes:
| Name | Type | Description |
|---|---|---|
measurements |
List[RTTMeasurement]
|
List of RTT measurements. |
metadata |
dict
|
Additional metadata about the dataset. |
validate_measurements_sorted(v)
classmethod
¶
Ensure measurements are sorted by timestamp.
to_arrays()
¶
Convert measurements to numpy arrays.
Returns:
| Type | Description |
|---|---|
tuple[ndarray, ndarray]
|
Tuple of (epochs, rtt_values) as numpy arrays. |
to_dataframe()
¶
Convert measurements to pandas DataFrame.
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with columns: timestamp, epoch, rtt_value, source, destination. |
compute_minimum_intervals(interval_minutes=15)
¶
Compute minimum RTT values over specified intervals.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
interval_minutes
|
int
|
Interval size in minutes for computing minimums. |
15
|
Returns:
| Type | Description |
|---|---|
MinimumRTTDataset
|
Dataset containing minimum RTT values for each interval. |
get_time_range()
¶
Get the time range of measurements.
Returns:
| Type | Description |
|---|---|
tuple[datetime, datetime]
|
Start and end timestamps of the dataset. |
MinimumRTTDataset
¶
Bases: RTTDataset
Dataset containing minimum RTT values computed over intervals.
Attributes:
| Name | Type | Description |
|---|---|---|
measurements |
List[RTTMeasurement]
|
List of minimum RTT measurements. |
interval_minutes |
int
|
Interval size in minutes used for computing minimums. |
jitterbug.models.analysis
¶
Analysis result models using Pydantic for validation and serialization.
ChangePoint
¶
Bases: BaseModel
Represents a detected change point in the time series.
Attributes:
| Name | Type | Description |
|---|---|---|
timestamp |
datetime
|
When the change point occurred. |
epoch |
float
|
Unix timestamp of the change point. |
confidence |
float
|
Confidence score of the change point detection. |
algorithm |
str
|
Algorithm used to detect the change point. |
LatencyJump
¶
Bases: BaseModel
Represents a detected latency jump between two time periods.
Attributes:
| Name | Type | Description |
|---|---|---|
start_timestamp |
datetime
|
Start of the period. |
end_timestamp |
datetime
|
End of the period. |
start_epoch |
float
|
Unix timestamp of period start. |
end_epoch |
float
|
Unix timestamp of period end. |
has_jump |
bool
|
Whether a significant latency jump was detected. |
magnitude |
float
|
Magnitude of the jump in RTT units. |
threshold |
float
|
Threshold used for jump detection. |
JitterAnalysis
¶
Bases: BaseModel
Represents results of jitter analysis.
Attributes:
| Name | Type | Description |
|---|---|---|
start_timestamp |
datetime
|
Start of the analysis period. |
end_timestamp |
datetime
|
End of the analysis period. |
start_epoch |
float
|
Unix timestamp of period start. |
end_epoch |
float
|
Unix timestamp of period end. |
has_significant_jitter |
bool
|
Whether significant jitter was detected. |
jitter_metric |
float
|
Computed jitter metric value. |
method |
Literal['jitter_dispersion', 'ks_test']
|
Method used for jitter analysis. |
threshold |
float
|
Threshold used for significance testing. |
p_value |
Optional[float]
|
P-value if statistical test was used. |
CongestionInference
¶
Bases: BaseModel
Represents the final congestion inference for a time period.
Attributes:
| Name | Type | Description |
|---|---|---|
start_timestamp |
datetime
|
Start of the congestion period. |
end_timestamp |
datetime
|
End of the congestion period. |
start_epoch |
float
|
Unix timestamp of period start. |
end_epoch |
float
|
Unix timestamp of period end. |
is_congested |
bool
|
Whether congestion was inferred. |
confidence |
float
|
Confidence in the congestion inference. |
latency_jump |
Optional[LatencyJump]
|
Associated latency jump analysis. |
jitter_analysis |
Optional[JitterAnalysis]
|
Associated jitter analysis. |
to_dict()
¶
Convert to dictionary for backward compatibility.
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary with keys: starts, ends, congestion. |
CongestionInferenceResult
¶
Bases: BaseModel
Container for multiple congestion inference results.
Attributes:
| Name | Type | Description |
|---|---|---|
inferences |
List[CongestionInference]
|
List of congestion inferences. |
metadata |
dict
|
Additional metadata about the analysis. |
to_dataframe()
¶
Convert to pandas DataFrame for backward compatibility.
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with columns: starts, ends, congestion. |
get_congested_periods()
¶
Get only the periods identified as congested.
Returns:
| Type | Description |
|---|---|
List[CongestionInference]
|
List of congested periods. |
get_total_congestion_duration()
¶
Get total duration of congestion in seconds.
Returns:
| Type | Description |
|---|---|
float
|
Total congestion duration in seconds. |