Input and output

jitterbug.io.data_loader

Data loading utilities for various input formats.

RTT_COLUMNS = ('values', 'rtt_value', 'rtt', 'latency') module-attribute

Accepted names for the RTT column, in order of preference. Values are milliseconds.

DataLoader

Data loader for various RTT data formats.

Supports loading from: - CSV files with epoch timestamps and RTT values - JSON files from scamper's warts outputs - InfluxDB query results - Pandas DataFrames

load_from_file(file_path, file_format=None)

Load RTT data from a file.

Parameters:

Name	Type	Description	Default
file_path	Union[str, Path]	Path to the data file.	required
file_format	Optional[str]	Format of the file ('csv' or 'json'). If None, it is inferred from the extension, then from the first line. A trailing .zst means the file is Zstandard-compressed (rtts.csv.zst) and does not count as the extension.	None

Returns:

Type	Description
RTTDataset	Loaded RTT dataset.

load_from_dataframe(df)

Load RTT data from a pandas DataFrame.

The input contract (see docs/INPUT_FORMATS.md): an epoch column with Unix seconds (UTC) and one RTT column named values, rtt_value, rtt or latency holding milliseconds; source and destination are optional. Validation happens here, once, on the whole frame:

• a missing column or a non-numeric value raises ValueError;
• rows with a missing epoch or RTT, a non-positive RTT, or an RTT above MAX_RTT_MS are dropped with a warning and counted in metadata["dropped_rows"];
• rows are sorted by epoch (stable) if they are not already; duplicate epochs are kept (validate_data reports them).

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing RTT data.	required

Returns:

Type	Description
RTTDataset	Loaded RTT dataset.

Raises:

Type	Description
ValueError	If a required column is missing, a value is not numeric, or no valid rows remain.

load_from_influxdb(url, token, org, bucket, query)

Load RTT data directly from InfluxDB.

Parameters:

Name	Type	Description	Default
url	str	InfluxDB URL.	required
token	str	InfluxDB token.	required
org	str	InfluxDB organization.	required
bucket	str	InfluxDB bucket.	required
query	str	Flux query to execute.	required

Returns:

Type	Description
RTTDataset	Loaded RTT dataset.

validate_data(dataset)

Validate RTT dataset and return quality metrics.

Parameters:

Name	Type	Description	Default
dataset	RTTDataset	Dataset to validate.	required

Returns:

Type	Description
Dict[str, any]	Validation results and quality metrics.

jitterbug.io.exporters

Result export utilities.

JSON and CSV outputs are Zstandard-compressed when the path ends in .zst (results.json.zst); see :mod:jitterbug.io.compression.

ResultExporter

Exporter for analysis results to various formats.

export_to_json(results, output_path, pretty=True)

Export results to JSON format.

Parameters:

Name	Type	Description	Default
results	CongestionInferenceResult	Analysis results to export.	required
output_path	Union[str, Path]	Path to save JSON file; compressed with Zstandard if it ends in .zst.	required
pretty	bool	Whether to format JSON with indentation.	True

export_to_csv(results, output_path)

Export results to CSV format.

Parameters:

Name	Type	Description	Default
results	CongestionInferenceResult	Analysis results to export.	required
output_path	Union[str, Path]	Path to save CSV file; compressed with Zstandard if it ends in .zst.	required

export_to_parquet(results, output_path)

Export results to Parquet format.

Parameters:

Name	Type	Description	Default
results	CongestionInferenceResult	Analysis results to export.	required
output_path	Union[str, Path]	Path to save Parquet file.	required

Raises:

Type	Description
ValueError	If output_path ends in .zst: Parquet compresses its own columns.

export_summary(results, output_path)

Export summary statistics to JSON format.

Parameters:

Name	Type	Description	Default
results	CongestionInferenceResult	Analysis results to export.	required
output_path	Union[str, Path]	Path to save summary JSON file; compressed with Zstandard if it ends in .zst.	required

reject_zstd_parquet(output_path)

Raise ValueError for *.zst Parquet output, which would compress twice.

jitterbug.io.compression

Transparent Zstandard compression for input and output files.

A path whose last suffix is .zst (rtts.csv.zst, results.json.zst) is read and written through a Zstandard stream; any other path is a plain file. The codec is the standard library's compression.zstd on Python 3.14 and later, otherwise the zstandard package (the zstd extra).

is_zstd(path)

Return whether path names a Zstandard-compressed file (last suffix .zst).

Parameters:

Name	Type	Description	Default
path	str | Path	File path.	required

Returns:

Type	Description
bool	True for *.zst, case-insensitive.

inner_suffix(path)

Return the suffix that describes the content, ignoring a trailing .zst.

Parameters:

Name	Type	Description	Default
path	str | Path	File path.	required

Returns:

Type	Description
str	Lower-case suffix, e.g. ".csv" for both rtts.csv and rtts.csv.zst; empty when there is none.

open_text(path, mode='r', newline=None)

Open a text file, through a Zstandard stream when path ends in .zst.

Parameters:

Name	Type	Description	Default
path	str | Path	File path.	required
mode	str	"r" or "w".	'r'
newline	str | None	Passed to the text layer, as in :func:open. Use "" when handing the stream to the csv module or pandas.	None

Returns:

Type	Description
IO[str]	Text stream; use it as a context manager.

Raises:

Type	Description
ValueError	If mode is not "r" or "w".
ImportError	If path ends in .zst and no Zstandard codec is available.