Recording Raster Resampling Quality Metrics

Part of: Data Quality Metrics as Lineage Evidence

Resampling is the raster operation that changes every cell value while leaving every property a schema check would notice. The dimensions may change, the extent may change, and neither tells you whether the values that came out are a faithful representation of the values that went in. This how-to records the metrics that do: the method, the scale factor, the value distribution shift, and the NoData accounting that reveals whether coverage was silently lost.

The reason resampling deserves its own treatment is that the choice of method is a data-quality decision disguised as a performance option. Nearest-neighbour preserves original values and destroys spatial smoothness; cubic convolution produces smooth output containing values that appear in no input cell. For a categorical layer the second is simply wrong, and nothing in the output announces which was used.

Prerequisites

  • rasterio 1.3+ or GDAL with access to the resampling parameters actually applied.
  • A lineage emitter carrying per-step metrics, per Transformation Logging Standards.
  • A declared data type per raster — categorical or continuous — recorded as a dataset attribute.
  • Agreement on which distribution statistics you compare, since they must be consistent to be comparable.

Method Is the Metric That Matters Most

Before any statistic, record which algorithm ran. It is one string, it is the field most often omitted, and it determines whether every other metric is even meaningful.

Which methods invent values that were not in the input Nearest neighbour selects an existing value; bilinear, cubic and averaging compute new values, which is invalid for categorical rasters. METHOD INVENTS VALUES? VALID FOR Nearest neighbour picks one input cell no categorical AND continuous the only safe default Bilinear weighted mean of 4 yes continuous only class 3.5 does not exist Cubic / cubic spline weighted over 16 yes, and overshoots continuous only can exceed the input range Mode no categorical downsampling

The cubic row carries a specific hazard worth recording against. Cubic convolution can produce values outside the range present in the input — an overshoot at a sharp edge — which for an elevation model means spurious peaks and for a reflectance band can mean negative values. Comparing the output’s minimum and maximum against the input’s is a one-line check that catches it, and storing both pairs makes the overshoot visible in the record rather than only at the moment of inspection.

Assert the method against the declared data type rather than trusting the caller. A categorical raster resampled bilinearly is a defect regardless of intent, and a validation that refuses the combination catches it at the moment somebody writes it. Where a pipeline handles both kinds, the data-type attribute is what drives the assertion, which is a further reason to record it on the dataset rather than infer it from the values.

Scale Factor Determines What Is Recoverable

The second field is the ratio between input and output resolution, and its sign changes what the operation means.

Upsampling — producing finer cells than the input — adds no information. Every output cell is a function of input cells that already existed, so the result is more detailed in appearance and no more accurate. Recording the scale factor makes that explicit, and a product advertising ten-metre resolution derived from thirty-metre input is misdescribed in a way the record exposes.

Downsampling discards information irreversibly, and how it discards depends on the method. Nearest-neighbour downsampling picks one cell per output and throws the rest away, so a small feature can vanish entirely; averaging blends them, so the feature survives as a diluted signal. For change detection those two produce materially different results from the same input, and only the recorded method distinguishes them.

Record the input and output cell sizes rather than only the ratio. The ratio is derivable and the absolute sizes are not, and the absolute output resolution is what a consumer needs in order to know what the data can support. Include the units, since a raster in a geographic CRS has cell sizes in degrees and the number alone is uninterpretable.

NoData Accounting Reveals Silent Coverage Loss

The metric most likely to catch a genuine problem is the simplest: how many cells held data before, and how many hold data after.

NoData spreads under interpolation A single NoData cell contaminates every output cell whose kernel overlaps it, so valid coverage shrinks at edges and around gaps. INPUT — one NoData cell valid: 11 of 12 bilinear OUTPUT — contamination spreads valid: 4 of 12 Record both counts. A large drop means the kernel is eating coverage at every gap and edge. The illustration exaggerates the ratio; the mechanism is exactly this. Cloud-masked imagery is where this bites hardest — every mask edge grows.

Cloud-masked optical imagery is the case where this matters most. A scene with scattered cloud has NoData scattered through it, and every interpolating resample grows each masked region by the kernel radius. Chaining two such operations grows it twice. A pipeline that resamples repeatedly can lose a substantial fraction of its valid coverage without any step reporting an error, and the valid-cell count is the only signal.

Record the count as an absolute number and the raster dimensions alongside it, rather than a percentage. Percentages hide the case where the output grid changed size, and having both numbers lets any ratio be computed later without ambiguity about what it was a ratio of.

Distribution Shift as a Sanity Check

Beyond counts, a small set of summary statistics before and after catches the errors that counts miss.

Minimum and maximum are the cheapest and catch overshoot directly. An output whose maximum exceeds the input’s, for any method other than one you expect to overshoot, is a defect or a NoData value being treated as data — both worth an alert.

Mean and standard deviation catch a different class. Downsampling by averaging reduces variance predictably; a variance that barely moved suggests the averaging did not happen, and one that collapsed suggests the scale factor was larger than intended. Neither is conclusive alone, and both are useful as a trend across runs of the same pipeline.

Keep the statistic set small and fixed. Computing a full histogram per band per step is expensive and produces a record nobody compares; four scalars per band are cheap, comparable, and enough to notice when something changed. Record them per band rather than per raster, since a multi-band product can have one band go wrong while the others are fine.

Where the Record Belongs and How Long It Lives

The metrics are worth nothing on their own; they earn their cost by being comparable across runs, which decides where they are stored.

Per-step metrics rolling up to a chain summary Each resample step carries its own metric block; the chain summary reports the coarsest method used and the cumulative valid-cell loss. reproject bilinear · ×1.0 valid −0.4% mosaic cubic · ×1.0 valid −1.1% downsample average · ×0.25 valid −2.3% CHAIN SUMMARY interpolating steps: 3 · coarsest effective resolution: ×0.25 cumulative valid-cell loss: 3.8% No single step looks alarming. The sum is the number a steward needs to see.

The caption is the argument for the roll-up. Each step’s loss sits comfortably inside anything a per-step threshold would flag, and the accumulated figure is the one that would make somebody reconsider the pipeline’s shape.

Keep per-step records for as long as the outputs they describe are in circulation, and the chain summaries for longer. The summaries are small, they are what reporting reads, and they are what an auditor asks for. Expiring the detail while retaining the summary is a reasonable trade once a product has been superseded.

Verification

Construct a fixture raster with a known pattern — a gradient, a single high cell, a NoData hole — and assert each metric behaves as the method predicts. Nearest-neighbour on the gradient must produce output values that all appear in the input; bilinear must produce at least one that does not. That single pair of assertions proves the method field reflects what actually ran rather than what was requested.

Test the NoData accounting with the hole fixture explicitly, asserting the valid-cell count drops under an interpolating method and does not under nearest-neighbour. This is the assertion most likely to catch a real regression later, because NoData handling is exactly what changes between library versions.

Assert that a categorical raster resampled bilinearly is refused. A validation that has never rejected the invalid combination has not been shown to work, and the combination is easy to introduce when a pipeline gains a new layer whose type nobody set.

Gotchas & edge cases

  • NoData must be declared, not inferred. A raster whose NoData value is unset has cells full of a sentinel that statistics treat as data, skewing every metric. Record the declared NoData value with the metrics so a suspicious minimum can be explained.
  • Float rasters have no exact equality. Asserting that a nearest-neighbour output value appears in the input requires a tolerance for float bands, or the test fails on representation differences rather than on real ones.
  • Overviews are not the data. Statistics computed from a pyramid level describe the overview, not the full-resolution band. Read at the base resolution or record which level was measured.
  • Warping combines resampling with reprojection. A single gdalwarp call does both, so the record needs the CRS fields from CRS and Datum Transformation Provenance as well as the resampling fields. Splitting them into two records misrepresents one operation as two.
  • Scale factor is not always uniform. A warp can change x and y resolution by different factors, particularly across a projection change. Record both axes rather than a single ratio.