% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hex_zonal.R
\name{hex_zonal}
\alias{hex_zonal}
\title{Zonal Statistics for Hex Cells}
\usage{
hex_zonal(raster, grid, fun = "mean", boundary = NULL, cells = NULL)
}
\arguments{
\item{raster}{A \code{terra::SpatRaster} object.}

\item{grid}{A HexGridInfo or HexData object specifying the grid.}

\item{fun}{Summary function name: \code{"mean"} (default), \code{"sum"}, \code{"min"},
\code{"max"}, \code{"sd"}, or \code{"count"}.}

\item{boundary}{Optional sf polygon to limit the analysis extent.}

\item{cells}{Optional cell IDs. If provided, only these cells are included.}
}
\value{
A data.frame with columns \code{cell_id}, plus one column per raster
layer containing the aggregated values.
}
\description{
Computes zonal statistics by aggregating all raster pixels falling
within each hexagonal cell polygon. More accurate than \code{\link[=hex_extract]{hex_extract()}}
but slower because it requires polygon geometries.
}
\details{
Requires the \code{terra} package (in Suggests). The function:
\enumerate{
\item Generates hex polygon geometries via \code{\link[=cell_to_sf]{cell_to_sf()}}
\item Calls \code{terra::extract(raster, polygons, fun = fun)}
\item Joins results back to cell IDs
}

For point-based extraction (faster, at cell centers only), use
\code{\link[=hex_extract]{hex_extract()}} instead.
}
\examples{
\donttest{
if (requireNamespace("terra", quietly = TRUE)) {
  r <- terra::rast(nrows = 100, ncols = 100,
                   xmin = -10, xmax = 10, ymin = 40, ymax = 55)
  terra::values(r) <- runif(10000)
  names(r) <- "temperature"

  g <- hex_grid(area_km2 = 500)
  df <- data.frame(lon = c(0, 5), lat = c(45, 50))
  hd <- hexify(df, lon = "lon", lat = "lat", grid = g)
  hex_zonal(r, hd, fun = "mean")
}
}
}
\seealso{
\code{\link[=hex_extract]{hex_extract()}} for cell-center extraction,
\code{\link[=cell_to_sf]{cell_to_sf()}} for hex polygon generation
}
