📊 Statistics API

localtileserver provides a per-band statistics endpoint that returns comprehensive information about the data distribution in your raster file. This is useful for understanding data ranges, choosing appropriate vmin/vmax values, and quality-checking your data.

Python Client

Use the statistics() method on a TileClient instance:

from localtileserver import TileClient, examples

client = examples.get_landsat()

# Get statistics for all bands
stats = client.statistics()

for band_name, band_stats in stats.items():
    print(f"{band_name}:")
    print(f"  min={band_stats['min']}, max={band_stats['max']}")
    print(f"  mean={band_stats['mean']:.2f}, std={band_stats['std']:.2f}")
    print(f"  percentile_2={band_stats['percentile_2']}")
    print(f"  percentile_98={band_stats['percentile_98']}")

b1:
  min=18.0, max=138.0
  mean=46.71, std=16.29
  percentile_2=24.0
  percentile_98=86.0
b2:
  min=13.0, max=155.0
  mean=49.53, std=19.54
  percentile_2=20.0
  percentile_98=97.0
b3:
  min=9.0, max=143.0
  mean=51.79, std=21.83
  percentile_2=10.0
  percentile_98=94.0
b4:
  min=4.0, max=200.0
  mean=56.82, std=28.00
  percentile_2=5.0
  percentile_98=106.0
b5:
  min=1.0, max=147.0
  mean=58.12, std=35.74
  percentile_2=1.0
  percentile_98=108.0
b6:
  min=167.0, max=222.0
  mean=207.12, std=9.61
  percentile_2=192.0
  percentile_98=220.0
b7:
  min=0.0, max=117.0
  mean=42.15, std=27.23
  percentile_2=1.0
  percentile_98=86.0

Statistics with Expressions

You can also compute statistics on derived bands using expressions:

# Statistics for NDVI
ndvi_stats = client.statistics(expression='(b4-b3)/(b4+b3)')
for band_name, band_stats in ndvi_stats.items():
    print(f"{band_name}: min={band_stats['min']:.3f}, max={band_stats['max']:.3f}")

b1: min=-0.711, max=0.733

REST API

Statistics are available via the REST endpoint:

# Per-band statistics
GET /api/statistics?filename=geo.tif

# Statistics for specific bands
GET /api/statistics?filename=geo.tif&indexes=1,2

# Statistics for an expression
GET /api/statistics?filename=geo.tif&expression=(b4-b1)/(b4+b1)

Response Format

The statistics response is a JSON dictionary keyed by band name (e.g., b1, b2). Each band contains:

Field	Description
min	Minimum pixel value
max	Maximum pixel value
mean	Mean pixel value
std	Standard deviation
median	Median pixel value
count	Total number of pixels (including masked)
valid_pixels	Number of valid (unmasked) pixels
masked_pixels	Number of masked pixels
valid_percent	Percentage of valid pixels
percentile_2	2nd percentile value
percentile_98	98th percentile value
histogram	Histogram as [counts, bin_edges]
majority	Most common pixel value
minority	Least common pixel value
unique	Number of unique pixel values