diff --git a/packages/flint-py/flint/core/resolve_semantics.py b/packages/flint-py/flint/core/resolve_semantics.py index cb1fed30..92744431 100644 --- a/packages/flint-py/flint/core/resolve_semantics.py +++ b/packages/flint-py/flint/core/resolve_semantics.py @@ -309,6 +309,53 @@ def _js_number_to_string(v: float) -> str: # Public API: resolve_channel_semantics # --------------------------------------------------------------------------- +def _semantic_type(raw_annotation: Any, field_name: str, field_values: list[Any]) -> str: + if isinstance(raw_annotation, str): + supplied = raw_annotation or "" + elif isinstance(raw_annotation, dict): + supplied = raw_annotation.get("semanticType") or "" + else: + supplied = "" + return supplied or infer_implicit_semantic_type(field_name, field_values) + + +def _channel_type( + encoding: dict, channel: str, data: list, field_name: str, + field_values: list, semantic_type: str, +) -> str: + resolved = resolve_encoding_type(semantic_type, field_values, channel, data, field_name)["vlType"] + if encoding.get("type"): + resolved = encoding["type"] + elif channel in ("column", "row") and resolved not in ("nominal", "ordinal"): + resolved = "nominal" + + if resolved == "quantitative": + sample_values = [r.get(field_name) for r in data[:15] if r.get(field_name) is not None] + iso_re = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$") + if sample_values and all(iso_re.match(str(v).strip()) for v in sample_values): + resolved = "temporal" + return resolved + + +def _resolve_channel_types( + encodings: dict[str, dict[str, Any]], data: list[dict[str, Any]], + semantic_types: dict[str, Any], +) -> dict[str, str]: + """Resolve only types needed before encoding actions are applied.""" + result = {} + for channel, encoding in encodings.items(): + if encoding.get("type"): + continue + field_name = encoding.get("field") + if encoding.get("aggregate") and (field_name or encoding["aggregate"] == "count"): + result[channel] = "quantitative" + elif field_name: + values = [row.get(field_name) for row in data] + semantic_type = _semantic_type(semantic_types.get(field_name), field_name, values) + result[channel] = _channel_type(encoding, channel, data, field_name, values, semantic_type) + return result + + def resolve_channel_semantics( encodings: dict[str, dict[str, Any]], data: list[dict[str, Any]], @@ -336,33 +383,9 @@ def resolve_channel_semantics( continue raw_annotation = semantic_types.get(field_name) - if isinstance(raw_annotation, str): - supplied_semantic_type = raw_annotation or "" - elif isinstance(raw_annotation, dict): - supplied_semantic_type = raw_annotation.get("semanticType") or "" - else: - supplied_semantic_type = "" field_values = [r.get(field_name) for r in data] - semantic_type = supplied_semantic_type or infer_implicit_semantic_type(field_name, field_values) - - type_decision = resolve_encoding_type( - semantic_type, field_values, channel, data, field_name, - ) - - resolved_type = type_decision["vlType"] - if encoding.get("type"): - resolved_type = encoding["type"] - elif channel in ("column", "row"): - if resolved_type not in ("nominal", "ordinal"): - resolved_type = "nominal" - - if resolved_type == "quantitative": - sample_values = [ - r.get(field_name) for r in data[:15] if r.get(field_name) is not None - ] - iso_re = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$") - if sample_values and all(iso_re.match(str(v).strip()) for v in sample_values): - resolved_type = "temporal" + semantic_type = _semantic_type(raw_annotation, field_name, field_values) + resolved_type = _channel_type(encoding, channel, data, field_name, field_values, semantic_type) fc = resolve_field_semantics(raw_annotation or semantic_type, field_name, field_values) annotation = fc["semanticAnnotation"] diff --git a/packages/flint-py/flint/vegalite/assemble.py b/packages/flint-py/flint/vegalite/assemble.py index da6b4a42..90772f2c 100644 --- a/packages/flint-py/flint/vegalite/assemble.py +++ b/packages/flint-py/flint/vegalite/assemble.py @@ -8,7 +8,7 @@ from typing import Any, Optional from ..core.semantic_types import infer_vis_category, compute_zero_decision -from ..core.resolve_semantics import resolve_channel_semantics, convert_temporal_data +from ..core.resolve_semantics import _resolve_channel_types, resolve_channel_semantics, convert_temporal_data from ..core.field_semantics import to_type_string from ..core.filter_overflow import filter_overflow from ..core.encoding_overrides import apply_encoding_overrides @@ -135,20 +135,18 @@ def assemble_vegalite(input_doc: dict) -> dict: # Some actions (e.g. Sort) must know each channel's resolved encoding TYPE # to decide which position axis is the discrete category and which is the # measure. The host leaves `type` unset ("auto") for most encodings, so we - # run a preliminary semantics pass to fill in the inferred types, compose + # resolve preliminary types, compose # the overrides onto the type-enriched encodings, then re-resolve semantics # on the result below (so that, e.g., a value-sort correctly suppresses the # field's canonical ordinal ordering). converted_data = convert_temporal_data(data, semantic_types) - prelim_semantics = resolve_channel_semantics( - raw_encodings, data, semantic_types, converted_data, - ) + prelim_types = _resolve_channel_types(raw_encodings, data, semantic_types) typed_raw_encodings: dict = {} for ch, enc in raw_encodings.items(): if enc.get("type"): typed_raw_encodings[ch] = enc else: - typed_raw_encodings[ch] = {**enc, "type": (prelim_semantics.get(ch) or {}).get("type")} + typed_raw_encodings[ch] = {**enc, "type": prelim_types.get(ch)} # Axis dtype override (`xAxisType` / `yAxisType` properties): the user can # force a position channel's interpretation between a continuous time scale diff --git a/packages/flint-py/tests/unit/test_preliminary_types.py b/packages/flint-py/tests/unit/test_preliminary_types.py new file mode 100644 index 00000000..42ae2750 --- /dev/null +++ b/packages/flint-py/tests/unit/test_preliminary_types.py @@ -0,0 +1,83 @@ +import copy +import importlib + +import pytest + +from flint.core.resolve_semantics import _resolve_channel_types, resolve_channel_semantics + + +assemble = importlib.import_module("flint.vegalite.assemble") + +ROWS = [ + {"category": "B", "value": 2, "year": 2020, "when": "2020-01-01T00:00:00Z"}, + {"category": "A", "value": 5, "year": 2021, "when": "2021-01-01T00:00:00Z"}, +] +TYPES = {"category": {"semanticType": "Category", "sortOrder": ["B", "A"]}, "value": "Quantity"} + + +def test_preliminary_types_match_full_semantics(): + encodings = { + "x": {"field": "year"}, + "y": {"field": "value", "aggregate": "sum"}, + "color": {"field": "category"}, + "column": {"field": "value"}, + "row": {"field": "when", "type": "quantitative"}, + "size": {"aggregate": "count"}, + "shape": {"value": "circle"}, + } + full = resolve_channel_semantics(encodings, ROWS, TYPES) + types = _resolve_channel_types(encodings, ROWS, TYPES) + for channel, encoding in encodings.items(): + if not encoding.get("type"): + assert types.get(channel) == (full.get(channel) or {}).get("type") + assert types["column"] == "nominal" + assert types["size"] == "quantitative" + + +def test_iso_dates_and_missing_fields_match_full_semantics(): + encodings = { + "x": {"field": "when"}, + "y": {"field": "value"}, + "column": {"field": "when"}, + "size": {"aggregate": "count"}, + "shape": {}, + } + full = resolve_channel_semantics(encodings, ROWS, {"when": "Quantity", "value": "Quantity"}) + types = _resolve_channel_types(encodings, ROWS, {"when": "Quantity", "value": "Quantity"}) + assert types == {ch: cs["type"] for ch, cs in full.items()} + assert types["x"] == "temporal" + assert types["column"] == "nominal" + + +@pytest.mark.parametrize( + "encodings,properties", + [ + ({"x": "category", "y": "value", "color": "category"}, {"sort": "value-desc"}), + ({"y": "category", "x": {"aggregate": "count"}}, {"sort": "value-desc"}), + ({"x": {"field": "category", "type": "ordinal"}, "y": "value"}, {"sort": "value-desc"}), + ({"x": "year", "y": "value", "column": "year"}, {"xAxisType": "nominal", "sort": "value-desc"}), + ({"y": "year", "x": "value"}, {"yAxisType": "nominal", "sort": "value-desc"}), + ({"x": "when", "y": "value", "color": "category"}, {"sort": "value-desc"}), + ], +) +def test_assembly_matches_full_preliminary_pass(monkeypatch, encodings, properties): + doc = { + "data": {"values": ROWS}, + "semantic_types": TYPES, + "chart_spec": { + "chartType": "Bar Chart", "encodings": encodings, + "chartProperties": properties, "baseSize": {"width": 600, "height": 400}, + }, + } + optimized = assemble.assemble_vegalite(copy.deepcopy(doc)) + + def full_types(raw, data, semantic_types): + full = resolve_channel_semantics(raw, data, semantic_types) + return {ch: cs["type"] for ch, cs in full.items()} + + monkeypatch.setattr(assemble, "_resolve_channel_types", full_types) + assert optimized == assemble.assemble_vegalite(copy.deepcopy(doc)) + if properties.get("xAxisType") == "nominal": + assert optimized["encoding"]["x"]["sort"] == "-y" + if properties.get("yAxisType") == "nominal": + assert optimized["encoding"]["y"]["sort"] == "-x" diff --git a/packages/flint-py/tools/benchmark-results/preliminary-types.json b/packages/flint-py/tools/benchmark-results/preliminary-types.json new file mode 100644 index 00000000..13633cca --- /dev/null +++ b/packages/flint-py/tools/benchmark-results/preliminary-types.json @@ -0,0 +1,114 @@ +{ + "python": "3.12.3 (main, Aug 31 2026, 10:18:26) [GCC 13.3.0]", + "platform": "Linux-6.12.8+-x86_64-with-glibc2.39", + "baseline_revision": "a794557384adcc3293a77043f6b9aff1c33d152c", + "baseline_assemble_sha256": "accb132bcb06c9c2f6d5425b665edc95bc41df43aa7c7890e531e58b039fc7b6", + "baseline_semantics_sha256": "d21f1746fc86ee3afcd6526e6f6e9e4b3ac6237f7e9e413c726183cb3a28d4df", + "change_assemble_sha256": "094ee38e9ff497f7a1d64e886a8df55e18e6e679851931c1b79df233b8fdfe90", + "change_semantics_sha256": "ab98673a7bf5e6f5217afdce12ceb65459135f72084867ed573de81f0bee8da1", + "fixtures": { + "1000": { + "fixture_sha256": "89d6dd2d09de03d573661bbcf9a58e233e408ba2523aa7e251379373ebb723cb", + "output_sha256": "5133b184f30d68acc3aae01aa2dcdeb3df4819a5fa42fcb7abef11d16460b1b7", + "samples": [ + { + "round": 1, + "version": "baseline", + "seconds": 0.0161830000001828, + "peak_bytes": 332705 + }, + { + "round": 1, + "version": "change", + "seconds": 0.013857526000037979, + "peak_bytes": 330191 + }, + { + "round": 2, + "version": "change", + "seconds": 0.01339831299992511, + "peak_bytes": 330191 + }, + { + "round": 2, + "version": "baseline", + "seconds": 0.016444218000060573, + "peak_bytes": 332705 + }, + { + "round": 3, + "version": "baseline", + "seconds": 0.016307415000028413, + "peak_bytes": 332705 + }, + { + "round": 3, + "version": "change", + "seconds": 0.012800691999927949, + "peak_bytes": 330191 + } + ], + "median_seconds": { + "baseline": 0.016307415000028413, + "change": 0.01339831299992511 + }, + "median_peak_bytes": { + "baseline": 332705, + "change": 330191 + } + }, + "10000": { + "fixture_sha256": "b4b379fb709d0044270563ddd45a0df184d5a630d677d152fc086701963a38dd", + "output_sha256": "e6eb52df97e21244b529e863ed4fea25f3391a88b8fd6ab30a7e603284d08e5c", + "samples": [ + { + "round": 1, + "version": "baseline", + "seconds": 0.15185693099988384, + "peak_bytes": 2968192 + }, + { + "round": 1, + "version": "change", + "seconds": 0.12157827100008944, + "peak_bytes": 2968192 + }, + { + "round": 2, + "version": "change", + "seconds": 0.12095029600004636, + "peak_bytes": 2968192 + }, + { + "round": 2, + "version": "baseline", + "seconds": 0.15269938599999477, + "peak_bytes": 2968192 + }, + { + "round": 3, + "version": "baseline", + "seconds": 0.15294669400009298, + "peak_bytes": 2968192 + }, + { + "round": 3, + "version": "change", + "seconds": 0.12123961699990105, + "peak_bytes": 2968192 + } + ], + "median_seconds": { + "baseline": 0.15269938599999477, + "change": 0.12123961699990105 + }, + "median_peak_bytes": { + "baseline": 2968192, + "change": 2968192 + } + } + }, + "change_revision": "a42b6b20332f8469ad8a0be138a2f06c13dec2c6", + "python_dateutil": "2.9.0.post0", + "capture_note": "Samples captured with an equivalent harness loading git-show baseline files; runtime and change revision metadata added afterward. Reproducer loads the same source directly from git." +} diff --git a/packages/flint-py/tools/benchmark_preliminary_types.py b/packages/flint-py/tools/benchmark_preliminary_types.py new file mode 100755 index 00000000..cce58f7a --- /dev/null +++ b/packages/flint-py/tools/benchmark_preliminary_types.py @@ -0,0 +1,146 @@ +#!/usr/bin/env python3 +"""Benchmark preliminary type resolution; run under the shared perf-measure flock. + +Run from the repository root with the Python package installed. --compare-fixtures +compares all shared fixture outputs against the baseline instead of benchmarking. +The baseline sources are loaded directly from git, without changing the checkout. +""" +import argparse +import copy +import gc +import hashlib +import importlib.metadata +import json +import platform +import statistics +import subprocess +import sys +import time +import tracemalloc +import types +from pathlib import Path + +import flint.core.resolve_semantics as current_semantics +from flint.vegalite.assemble import assemble_vegalite + + +BASELINE = "a794557384adcc3293a77043f6b9aff1c33d152c" +ROOT = Path(__file__).resolve().parents[3] + + +def baseline_module(name, path): + source = subprocess.check_output( + ["git", "show", f"{BASELINE}:{path}"], cwd=ROOT, + ) + module = types.ModuleType(name) + module.__package__ = name.rpartition(".")[0] + exec(compile(source, f"{BASELINE}:{path}", "exec"), module.__dict__) + return module, hashlib.sha256(source).hexdigest() + + +baseline, baseline_assemble_hash = baseline_module( + "flint.vegalite._baseline_assemble", "packages/flint-py/flint/vegalite/assemble.py", +) +semantics, baseline_semantics_hash = baseline_module( + "flint.core._baseline_resolve_semantics", "packages/flint-py/flint/core/resolve_semantics.py", +) +baseline.resolve_channel_semantics = semantics.resolve_channel_semantics +baseline.convert_temporal_data = semantics.convert_temporal_data +functions = {"baseline": baseline.assemble_vegalite, "change": assemble_vegalite} + + +def fixture(n): + return { + "data": {"values": [ + {"x": i % 997 + 0.25, "y": (i * 13) % 991 + 0.5, + "group": f"group-{i % 20}", "unusedYear": 2000 + i % 24} + for i in range(n) + ]}, + "semantic_types": {"x": "Quantity", "y": "Quantity", "group": "Category", "unusedYear": "Year"}, + "chart_spec": { + "chartType": "Scatter Plot", + "encodings": {"x": "x", "y": "y", "color": "group"}, + "baseSize": {"width": 600, "height": 400}, + }, + } + + +def digest(value): + return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest() + + +def compare_fixtures(): + def result(fn, doc): + try: + return ("value", fn(copy.deepcopy(doc))) + except Exception as exc: + return ("exception", type(exc).__name__, str(exc)) + + different = [] + count = 0 + for path in sorted((ROOT / "shared/test-data").glob("*/input.json")): + if not (path.parent / "expected.json").exists(): + continue + doc = json.loads(path.read_text())["input"] + if result(functions["baseline"], doc) != result(functions["change"], doc): + different.append(path.parent.name) + count += 1 + print(json.dumps({"fixtures": count, "different": different}, indent=2)) + if different or not count: + raise SystemExit(1) + + +def benchmark(): + results = { + "python": sys.version, "platform": platform.platform(), + "python_dateutil": importlib.metadata.version("python-dateutil"), + "baseline_revision": BASELINE, + "change_revision": subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=ROOT, text=True).strip(), + "baseline_assemble_sha256": baseline_assemble_hash, + "baseline_semantics_sha256": baseline_semantics_hash, + "change_assemble_sha256": hashlib.sha256(Path(assemble_vegalite.__code__.co_filename).read_bytes()).hexdigest(), + "change_semantics_sha256": hashlib.sha256(Path(current_semantics.__file__).read_bytes()).hexdigest(), + "fixtures": {}, + } + for n in (1000, 10000): + doc = fixture(n) + fixture_hash = digest(doc) + expected = functions["baseline"](doc) + assert expected == functions["change"](doc) + samples = [] + for round_no in range(3): + order = ("baseline", "change") if round_no % 2 == 0 else ("change", "baseline") + for label in order: + func = functions[label] + gc.collect() + started = time.perf_counter() + result = func(doc) + elapsed = time.perf_counter() - started + assert result == expected + del result + gc.collect() + tracemalloc.start() + result = func(doc) + _, peak = tracemalloc.get_traced_memory() + tracemalloc.stop() + assert result == expected + samples.append({"round": round_no + 1, "version": label, "seconds": elapsed, "peak_bytes": peak}) + results["fixtures"][str(n)] = { + "fixture_sha256": fixture_hash, "output_sha256": digest(expected), "samples": samples, + "median_seconds": { + label: statistics.median(s["seconds"] for s in samples if s["version"] == label) + for label in functions + }, + "median_peak_bytes": { + label: statistics.median(s["peak_bytes"] for s in samples if s["version"] == label) + for label in functions + }, + } + print(json.dumps(results, indent=2)) + + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--compare-fixtures", action="store_true") + args = parser.parse_args() + compare_fixtures() if args.compare_fixtures else benchmark()