diff --git a/kll_sketch/pyproject.toml b/kll_sketch/pyproject.toml index 63d8009..7d66c00 100644 --- a/kll_sketch/pyproject.toml +++ b/kll_sketch/pyproject.toml @@ -24,3 +24,25 @@ classifiers = [ [project.urls] Homepage = "https://github.com/yourname/kll_sketch" Repository = "https://github.com/yourname/kll_sketch" + +[project.optional-dependencies] +test = [ + "pytest>=7.4", + "hypothesis>=6.88", + "pytest-cov>=4.1", +] + +[tool.pytest.ini_options] +addopts = "--strict-config --strict-markers --cov=kll_sketch --cov-report=term-missing" +testpaths = ["kll_sketch/tests"] +filterwarnings = [ + "error", +] + +[tool.coverage.run] +branch = true +source = ["kll_sketch"] + +[tool.coverage.report] +precision = 2 +show_missing = true diff --git a/kll_sketch/tests/test_kll.py b/kll_sketch/tests/test_kll.py index cee00a2..f22cfdd 100644 --- a/kll_sketch/tests/test_kll.py +++ b/kll_sketch/tests/test_kll.py @@ -1,19 +1,169 @@ +"""Deterministic regression tests for :mod:`kll_sketch`.""" +from __future__ import annotations + +import bisect +import math import random +from typing import Iterable + +import pytest + from kll_sketch import KLL -def test_basic_quantiles(): + +def _truth_quantile(xs: Iterable[float], q: float) -> float: + ordered = sorted(xs) + if not ordered: + raise ValueError("empty iterable") + idx = int(q * (len(ordered) - 1)) + return ordered[idx] + + +def test_basic_quantiles_regression() -> None: + """The sketch stays within a tight absolute error on a pseudo-random stream.""" rng = random.Random(1) - xs = [rng.random() for _ in range(50_000)] - srt = sorted(xs) - sk = KLL(capacity=200); sk.extend(xs) - for q in [0.01,0.1,0.25,0.5,0.75,0.9,0.99]: - est = sk.quantile(q); tru = srt[int(q*(len(xs)-1))] - assert abs(est - tru) <= 0.02 + xs = [rng.random() for _ in range(20_000)] + truth = sorted(xs) + + sketch = KLL(capacity=256) + sketch.extend(xs) + + # Deterministic checkpoints chosen to exercise both tails and the median. + for q in [0.01, 0.1, 0.25, 0.5, 0.75, 0.9, 0.99]: + estimate = sketch.quantile(q) + reference = truth[int(q * (len(xs) - 1))] + assert abs(estimate - reference) <= 0.015 + + +@pytest.mark.parametrize("capacity", [64, 128, 256]) +def test_quantile_rank_consistency(capacity: int) -> None: + """Quantile answers are compatible with the public ``rank`` helper.""" + rng = random.Random(capacity) + xs = [rng.uniform(-5.0, 5.0) for _ in range(2_000)] + + sketch = KLL(capacity=capacity) + sketch.extend(xs) + + for q in [0.0, 0.25, 0.5, 0.75, 1.0]: + estimate = sketch.quantile(q) + approx_rank = sketch.rank(estimate) + target_rank = q * sketch.size() + tolerance = max(5.0, 0.05 * sketch.size()) + assert abs(approx_rank - target_rank) <= tolerance + + +def test_rank_and_cdf_are_monotone() -> None: + rng = random.Random(7) + xs = sorted(rng.uniform(-1.0, 1.0) for _ in range(500)) + + sketch = KLL(capacity=200) + sketch.extend(xs) + + last_rank = -1.0 + for x in xs: + rank = sketch.rank(x) + assert rank >= last_rank + last_rank = rank + + cdf_values = sketch.cdf(xs) + assert all(0.0 <= value <= 1.0 for value in cdf_values) + assert cdf_values == sorted(cdf_values) -def test_weight_conservation(): + +def test_weight_conservation() -> None: rng = random.Random(0) - sk = KLL(capacity=64, rng_seed=777) - xs = [rng.random() for _ in range(200_000)] - sk.extend(xs) - vals, wts = sk._materialize_aligned() - assert abs(sum(wts) - sk.size()) < 1e-9 + sketch = KLL(capacity=64, rng_seed=777) + xs = [rng.random() for _ in range(50_000)] + sketch.extend(xs) + vals, wts = sketch._materialize_aligned() + assert len(vals) == len(wts) + assert abs(sum(wts) - sketch.size()) < 1e-9 + + +def test_merge_matches_single_stream() -> None: + rng = random.Random(321) + left = [rng.random() for _ in range(5_000)] + right = [rng.random() for _ in range(5_000)] + + merged = KLL(capacity=200) + merged.extend(left) + merged.extend(right) + + a = KLL(capacity=200) + b = KLL(capacity=200) + a.extend(left) + b.extend(right) + a.merge(b) + + checkpoints = [0.01, 0.1, 0.5, 0.9, 0.99] + for q in checkpoints: + assert math.isclose(a.quantile(q), merged.quantile(q), rel_tol=0.05, abs_tol=0.02) + + +@pytest.mark.parametrize( + "sample", + [ + [], + [0.0], + [0.0, 0.0, 0.0], + [-1.5, 0.0, 1.5], + [float(i) for i in range(10)], + ], +) +def test_serialization_roundtrip(sample: list[float]) -> None: + sketch = KLL(capacity=64) + sketch.extend(sample) + + restored = KLL.from_bytes(sketch.to_bytes()) + assert restored.size() == sketch.size() + assert restored._levels == sketch._levels + if sketch.size(): + assert restored.quantile(0.5) == pytest.approx(sketch.quantile(0.5)) + else: + with pytest.raises(ValueError): + restored.quantile(0.5) + + +def test_invalid_inputs_raise() -> None: + sketch = KLL(capacity=64) + with pytest.raises(ValueError): + sketch.add(float("nan")) + with pytest.raises(ValueError): + sketch.add(float("inf")) + with pytest.raises(ValueError): + sketch.quantile(-0.01) + with pytest.raises(ValueError): + sketch.quantile(1.5) + with pytest.raises(ValueError): + sketch.quantile(0.5) # empty sketch + + +@pytest.mark.parametrize("q", [0.0, 0.25, 0.5, 0.75, 1.0]) +@pytest.mark.parametrize("values", [[1.0], [1.0, 2.0, 3.0], [5.0] * 10]) +def test_quantile_matches_truth_for_small_inputs(values: list[float], q: float) -> None: + sketch = KLL(capacity=64) + sketch.extend(values) + truth = _truth_quantile(values, q) + estimate = sketch.quantile(q) + assert estimate == pytest.approx(truth, abs=1.0) + if values: + assert min(values) <= estimate <= max(values) + rank_estimate = sketch.rank(truth) + assert 0.0 <= rank_estimate <= len(values) + + +def test_rank_brackets_quantile() -> None: + rng = random.Random(99) + xs = [rng.uniform(-10, 10) for _ in range(3_000)] + + sketch = KLL(capacity=128) + sketch.extend(xs) + + for q in [0.0, 0.1, 0.5, 0.9, 1.0]: + estimate = sketch.quantile(q) + ordered = sorted(xs) + lower = bisect.bisect_left(ordered, estimate) + upper = bisect.bisect_right(ordered, estimate) + target_rank = q * (len(xs) - 1) + assert lower <= target_rank + 200 + assert upper >= target_rank - 200 diff --git a/kll_sketch/tests/test_properties.py b/kll_sketch/tests/test_properties.py new file mode 100644 index 0000000..03c89be --- /dev/null +++ b/kll_sketch/tests/test_properties.py @@ -0,0 +1,103 @@ +"""Property-based tests exercising probabilistic guarantees of :mod:`kll_sketch`.""" +from __future__ import annotations + +import bisect +from typing import Sequence + +import math + +import pytest + +hypothesis = pytest.importorskip("hypothesis") +st = hypothesis.strategies +given = hypothesis.given +settings = hypothesis.settings + +from kll_sketch import KLL + + +def _sorted_list(seq: Sequence[float]) -> list[float]: + ordered = list(seq) + ordered.sort() + return ordered + + +@given( + st.lists( + st.floats(min_value=-1e6, max_value=1e6, allow_nan=False, allow_infinity=False), + min_size=1, + max_size=2_000, + ), + st.floats(min_value=0.0, max_value=1.0), +) +@settings(max_examples=75, deadline=None) +def test_quantile_rank_error_is_bounded(xs: list[float], q: float) -> None: + sketch = KLL(capacity=256) + sketch.extend(xs) + + estimate = sketch.quantile(q) + ordered = _sorted_list(xs) + target_rank = q * (len(xs) - 1) + + # Compute the realised rank interval for the estimate in the truth data. + left = bisect.bisect_left(ordered, estimate) + right = bisect.bisect_right(ordered, estimate) + + # Allow a tolerance proportional to 1/k (here ~0.004) plus a small constant + # for discrete datasets. The assert keeps the property coarse but useful. + slack = max(3.0, 0.04 * len(xs)) + assert left <= target_rank + slack + assert right >= target_rank - slack + + +@given( + st.lists( + st.floats(min_value=-1e3, max_value=1e3, allow_nan=False, allow_infinity=False), + min_size=0, + max_size=1_000, + ), + st.lists( + st.floats(min_value=-1e3, max_value=1e3, allow_nan=False, allow_infinity=False), + min_size=0, + max_size=1_000, + ), +) +@settings(max_examples=60, deadline=None) +def test_merge_matches_extending(xs: list[float], ys: list[float]) -> None: + combined = xs + ys + + serial = KLL(capacity=128) + serial.extend(combined) + + a = KLL(capacity=128) + b = KLL(capacity=128) + a.extend(xs) + b.extend(ys) + a.merge(b) + + for q in [0.0, 0.1, 0.5, 0.9, 1.0]: + assert math.isclose(a.quantile(q), serial.quantile(q), rel_tol=0.05, abs_tol=0.05) + + +@given( + st.lists( + st.floats(min_value=-1e4, max_value=1e4, allow_nan=False, allow_infinity=False), + min_size=0, + max_size=1_500, + ) +) +@settings(max_examples=60, deadline=None) +def test_serialization_roundtrip_matches_levels(xs: list[float]) -> None: + sketch = KLL(capacity=200) + sketch.extend(xs) + payload = sketch.to_bytes() + restored = KLL.from_bytes(payload) + + assert restored.size() == sketch.size() + assert restored._levels == sketch._levels + + if xs: + for q in [0.0, 0.25, 0.5, 0.75, 1.0]: + restored_q = restored.quantile(q) + sketch_q = sketch.quantile(q) + assert math.isclose(restored_q, sketch_q, rel_tol=1e-9, abs_tol=1e-9)