Summarizing Raster Statistics for LLM Prompts

import logging
from collections import Counter
from dataclasses import dataclass
from typing import Mapping, Sequence

log = logging.getLogger("raster_summary")


@dataclass(frozen=True)
class Statement:
    text: str
    classes: tuple[tuple[str, float], ...]
    coverage: float
    cells: int


def digits_for(cells: int) -> int:
    """Decimal places a proportion from this many cells can honestly carry."""
    if cells < 100:
        return 0
    if cells < 10_000:
        return 1
    return 2


def proportions(values: Sequence[int], cells: int) -> list[tuple[int, float]]:
    """Class proportions, rounded to what the sample supports."""
    if not values:
        return []
    digits = digits_for(cells)
    counts = Counter(int(v) for v in values)
    total = sum(counts.values())
    return [(cls, round(100.0 * n / total, digits)) for cls, n in counts.most_common()]


def to_statement(name: str, values: Sequence[int], labels: Mapping[int, str],
                 pixel_size_m: float, captured_year: int | None,
                 coverage: float, top_n: int = 4) -> Statement:
    """One sentence a model can quote, with nothing implied that was not measured."""
    cells = len(values)
    if cells == 0:
        return Statement(f"{name}: no usable raster values within the shape.", (), coverage, 0)

    props = proportions(values, cells)
    named = tuple((labels.get(cls, f"class {cls}"), pct) for cls, pct in props[:top_n])
    body = ", ".join(f"{label} {pct:g}%" for label, pct in named)
    if len(props) > top_n:
        remainder = round(sum(p for _, p in props[top_n:]), digits_for(cells))
        body += f", other classes {remainder:g}%"

    date = f", captured {captured_year}" if captured_year else ""
    cover = "" if coverage > 0.98 else f", from {coverage * 100:.0f}% of the shape"
    text = f"{name}: {body} (from {pixel_size_m:g} m data{date}{cover})."
    if coverage <= 0.5:
        log.info("%s summarised from only %.0f%% coverage", name, coverage * 100)
    return Statement(text, named, coverage, cells)

import statistics


def continuous_statement(name: str, values: Sequence[float], unit: str,
                         pixel_size_m: float, captured_year: int | None,
                         coverage: float) -> Statement:
    """Median and range, not the mean — edge pixels move a mean and not a median."""
    if not values:
        return Statement(f"{name}: no usable values within the shape.", (), coverage, 0)
    ordered = sorted(values)
    median = statistics.median(ordered)
    lo, hi = ordered[int(0.05 * (len(ordered) - 1))], ordered[int(0.95 * (len(ordered) - 1))]
    date = f", captured {captured_year}" if captured_year else ""
    cover = "" if coverage > 0.98 else f", from {coverage * 100:.0f}% of the shape"
    text = (f"{name}: median {median:.1f} {unit}, most values between {lo:.1f} and "
            f"{hi:.1f} {unit} (from {pixel_size_m:g} m data{date}{cover}).")
    return Statement(text, (), coverage, len(values))

def test_proportions_sum_to_a_hundred_with_the_remainder():
    values = [1] * 50 + [2] * 30 + [3] * 10 + [4] * 6 + [5] * 4
    st = to_statement("cover", values, LABELS, 10.0, 2023, 1.0, top_n=3)
    assert "other classes" in st.text


def test_precision_matches_the_sample_size():
    small = to_statement("cover", [1] * 30 + [2] * 10, LABELS, 30.0, 2023, 1.0)
    assert "." not in small.text.split("%")[0].split()[-1]


def test_low_coverage_is_stated():
    st = to_statement("cover", [1] * 100, LABELS, 10.0, 2023, coverage=0.62)
    assert "62% of the shape" in st.text


def test_empty_values_produce_a_refusal_not_a_zero():
    st = to_statement("cover", [], LABELS, 10.0, 2023, 1.0)
    assert "no usable raster values" in st.text and st.classes == ()


def test_continuous_uses_median_not_mean():
    values = [10.0] * 99 + [10_000.0]              # one outlier from an adjacent surface
    st = continuous_statement("elevation", values, "m", 10.0, 2023, 1.0)
    assert "median 10.0" in st.text