extract_panel: Compute zonal statistics for a panel of rasters

In lightson: Download and Analyse Nighttime Lights Satellite Data

Compute zonal statistics for a panel of rasters

Description

Takes a named list of SpatRaster objects (one per time period, as returned by ntl_download() or bhuvan_raster()) and an sf or SpatVector polygon layer, and returns a tidy long-format data frame with one row per region and time period. Annual names such as "2025" produce the original four-column output. ISO-date names used by monthly and daily Black Marble additionally produce a date column.

Usage

extract_panel(rasters, polygons, fun = "mean", id_col = NULL)

Arguments

rasters	A named list of SpatRaster objects. Names should be years or ISO dates (e.g., "2020" or "2025-11-12").
polygons	An sf object or SpatVector containing the regions to summarise over.
fun	Aggregation function name passed to terra::zonal(). Default "mean". Also accepts "sum", "median", etc.
id_col	Name of the column in polygons to use as region_id. If NULL (default), the first character column is used.

Details

The polygons argument accepts any sf object: GADM, bharatviz GeoJSONs, LGD districts, or any shapefile loaded with sf::read_sf().

Value

A data frame with columns:

region_id

Character. Region identifier from polygons.

year

Integer. Year, taken from the name of each raster.

mean_radiance

Numeric. Aggregated radiance value.

n_pixels

Integer. Number of non-NA cells contributing to the stat.

Examples

r <- terra::rast(
  nrows = 10, ncols = 10, xmin = 0, xmax = 10, ymin = 0, ymax = 10,
  crs = "EPSG:4326", vals = 1:100
)
rasters <- list("2020" = r, "2021" = r * 2)
square <- function(x0) {
  sf::st_polygon(list(cbind(c(x0, x0 + 5, x0 + 5, x0, x0), c(0, 0, 10, 10, 0))))
}
regions <- sf::st_sf(
  region = c("west", "east"),
  geometry = sf::st_sfc(square(0), square(5), crs = 4326)
)
extract_panel(rasters, regions, id_col = "region")

lightson documentation built on Nov. 3, 2026, 5:07 p.m.