Internet Quality Barometer (IQB)

This repository contains the source code for the Internet Quality Barometer (IQB) library, notebook templates, and prototype. The prototype is available online at: https://iqb.mlab-staging.measurementlab.net.

About IQB

IQB (Internet Quality Barometer) is an open-source research project run by Measurement Lab (M-Lab).

IQB computes a 0-to-1 composite score (the "IQB Score") that rates Internet quality across six use cases: (1) web browsing; (2) video streaming; (3) audio streaming; (4) gaming; (5) video conferencing; (6) online backup.

Each use case defines minimum thresholds for network metrics (download and upload speed, latency, packet loss rate) weighted by importance. The input used to compute the IQB Score consists of the results collected by publicly available speedtests, such as NDT. IQB aggregates per-metric binary scores (pass/fail for each metric) into a single number. Higher scores indicate better quality for the specific use case.

In other words, IQB seeks to capture the quality available to perform activities that people use Internet for, thus using a multi-faceted definition of quality that goes beyond just using speed as the only metric.

Read more about the IQB framework in:

• M-Lab's blog post.

• The IQB framework detailed report and executive summary.

• The IQB poster at ACM IMC 2025.

Repository Architecture

• analysis: Jupyter notebooks showing how to use IQB for exploration and research. See analysis/README.md for more information.

• data: Workspace containing the default pipeline configuration, the default cache directory, and instructions for generating new data using the pipeline. See data/README.md for details.

• docs: Documentation, tutorials, design documents, and presentations. See docs/README.md for details.

• library: The IQB library containing methods for calculating the IQB score and data collection. See library/README.md for details.

• prototype: A Streamlit web application for applying and parametrizing the IQB framework in different use cases. See prototype/README.md for how to run it locally.

• .iqb: Symbolic link to data that simplifies running the pipeline on Unix-like systems.

• .python-version: declaration of the Python version that we use to develop the IQB framework.

• pyproject.toml: repository configuration declaring the uv workspace and its members.

• uv.lock: the uv lockfile declaring the dependencies used in this workspace.

Data Flow by Use Case

The IQB framework computes IQB scores from Parquet files obtained by querying BigQuery.

IQB Users

As a user of the IQB framework, you use the IQB library and more specifically the IQBCache and IQBRemoteCache classes to get the relevant Parquet files and compute the IQB score using the IQBCalculator.

scores <- [IQBCalculator] <- [IQBCache] <- localCache <- [IQBRemoteCache] <- GCS

More in detail:

1. the IQBRemoteCache downloads Parquet files from Measurement Lab GCS (Google Cloud Storage) and stores them in the local cache

2. the IQBCache reads Parquet files from the local cache (allowing for filtering) and return data structures compatible with the IQBCalculator

3. the IQBCalculator class computes the IQB scores

Directories of interest:

• library for the IQB library source code

• analysis for example usage via Jupyter notebooks

• prototype for usage in the Streamlit prototype

IQB Developers

As a developer of the IQB framework, you use the IQBPipeline class to run BigQuery queries and produce the related Parquet files. You typically do this indirectly via the iqb command line tool.

GCS <- [iqb cache push] <- parquet <- [iqb pipeline run] <- BigQuery

More in detail:

1. the iqb pipeline run command runs the IQB pipeline performing BigQuery queries and storing their results on the local disk as Parquet files

2. the iqb cache push pushes the Parquet files to GCS (Google Cloud Storage)

The iqb pipeline run command internally uses the IQBPipeline class.

Directories of interest:

• data: default configuration of the pipeline and temporary storage ahead of submitting the data to GCS

• library: implementation of the CLI and of the IQBPipeline class

Understanding the Codebase

• To learn how the data pipeline works, read the internals guide — it walks through queries, the pipeline, the remote cache, and the researcher API in sequence.

• To understand why specific technical decisions were made, see the design documents — architecture decision records covering cache design, data distribution, and more.

Quick Start

You need a supported Python version (see .python-version), uv, and git:

# Clone the repository
git clone git@github.com:m-lab/iqb.git
cd iqb

# Sync all dependencies (creates .venv automatically)
uv sync --dev

# Run the Streamlit prototype
cd prototype
uv run streamlit run Home.py

See CONTRIBUTING.md for full development environment setup, VSCode configuration, and component-specific workflows.

License

SPDX-License-Identifier: Apache-2.0