% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/block.R
\name{aggregate_block}
\alias{aggregate_block}
\title{aggregate_block}
\usage{
aggregate_block(
  block_output,
  .fns = NULL,
  population = FALSE,
  population_year = 2025,
  residential = FALSE,
  residential_year = 2020,
  quiet = FALSE
)
}
\arguments{
\item{block_output}{list. The named list returned by \code{\link[=generate_block]{generate_block()}},
containing \verb{$blocks} (sf polygons) and \verb{$buildings} (sf with \code{block_id}).}

\item{.fns}{named list. Optional overrides mapping column names to aggregation
functions, e.g. \code{list(vol = max, Height = median)}. Any column not named
here uses the built-in default (sum or mean as described above).}

\item{population}{logical. If \code{TRUE}, fetch GHSL population at block level
and add a \code{pop_total} column. Default \code{FALSE}.}

\item{population_year}{integer. GHSL population year to use when
\code{population = TRUE}. One of 1975, 1980, ..., 2025, 2030. Default \code{2025}.}

\item{residential}{logical. If \code{TRUE}, fetch GHS built-up surface rasters at
block level and compute \code{res_prop} (residential built-up surface fraction
per block). Default \code{FALSE}. Note: per-building \code{res} flags are excluded
from block-level aggregation - use this parameter for block-level
residential proportion instead.}

\item{residential_year}{integer. GHS built-up surface year to use when
\code{residential = TRUE}. One of 1975, 1980, ..., 2020, 2025, 2030. Default
\code{2020}.}

\item{quiet}{logical. If \code{TRUE}, suppress cli messages. Default \code{FALSE}.}
}
\value{
The \code{blocks} sf object from \code{block_output} with one column per
aggregated metric, plus \code{n_buildings} and \code{coverage_ratio}. When
\code{population = TRUE}, also includes \code{pop_total}. When \code{residential = TRUE},
also includes \code{res_prop}.
}
\description{
Aggregate building-level metrics to block level using the output
of \code{\link[=generate_block]{generate_block()}}. Additive quantities (areas, volumes, population) are
summed by default; per-building indices (shape metrics, elongation ratios,
etc.) are averaged. Both defaults can be overridden per column via \code{.fns}.
Two derived metrics are always added: \code{n_buildings} (count of buildings per
block) and \code{coverage_ratio} (total building footprint area / block area).
}
