% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/analyze_trends_by_spatial_unit.R
\name{analyze_trends_by_spatial_unit}
\alias{analyze_trends_by_spatial_unit}
\title{Summarize Temporal Patterns and Trends by Spatial Unit}
\usage{
analyze_trends_by_spatial_unit(shapefile_path, name_field, binary_stack = NULL,
                               pattern_raster = NULL, time_decrease_raster = NULL,
                               time_increase_raster = NULL, time_steps = NULL,
                               output_dir = NULL, overwrite = FALSE,
                               create_plot = TRUE, pie_scale = 0.15,
                               verbose = TRUE)
}
\arguments{
\item{shapefile_path}{Character, sf object, or sfc object. Path to a
shapefile or directory containing one, an sf object, or an sfc geometry.
Shapefiles spatial units will be used as the units for the data summary.}

\item{name_field}{Character. Attribute field to use as spatial unit labels.}

\item{binary_stack}{\code{SpatRaster} or character. Optional stack of binary
prediction rasters across time. Required for per-unit habitat summaries
and time series plots.}

\item{pattern_raster}{\code{SpatRaster} or character. Optional pattern
classification raster from \code{\link[TemporalModelR]{analyze_temporal_patterns}}.
Required for pattern composition summaries and scatterpie map.}

\item{time_decrease_raster}{\code{SpatRaster} or character. Optional raster
of first decrease time step from \code{\link[TemporalModelR]{analyze_temporal_patterns}}.}

\item{time_increase_raster}{\code{SpatRaster} or character. Optional raster
of first increase time step from \code{\link[TemporalModelR]{analyze_temporal_patterns}}.}

\item{time_steps}{Vector. Time labels for layers in \code{binary_stack}.
Required when \code{binary_stack} or change rasters are provided.}

\item{output_dir}{Character or \code{NULL}. Directory for CSV outputs and
plots. If \code{NULL}, results are returned in memory only and no files
are written. Default is \code{NULL}.}

\item{overwrite}{Logical. If \code{TRUE}, recomputes and overwrites existing
CSVs. Default is \code{FALSE}.}

\item{create_plot}{Logical. If \code{TRUE} (default), generates and saves
plots.}

\item{pie_scale}{Numeric in (0, 1]. Largest pie's radius as a fraction of
the smaller map dimension. Default is \code{0.15}, meaning the biggest
pie spans roughly 30\% of the smaller map dimension (radius = 15\%, so
diameter = 30\%). Smaller pies scale so their area is proportional to
the unit's pixel count. The fraction is converted internally to
coordinate units, so this argument works identically across CRSes
(degrees, meters, etc.) without manual rescaling.}

\item{verbose}{Logical. If \code{TRUE} (default), prints progress
messages during processing. Includes details on raster extraction and
per-spatial-unit summaries.}
}
\value{
Invisibly returns a list containing:
\itemize{
  \item \code{overall_summary}: Pattern composition per spatial unit
    (present when \code{pattern_raster} is supplied).
  \item \code{timestep_summary}: Suitable pixel counts per unit per time step
    (present when \code{binary_stack} is supplied).
  \item \code{change_by_timestep}: Gain and loss pixel counts per unit per time
    step (present when both change rasters are supplied).
  \item \code{plots}: Named list of recorded plot objects (present when
    \code{create_plot = TRUE}).
}
}
\description{
Aggregates temporal pattern classifications and change metrics
across user-defined spatial units (e.g., states, counties, watersheds).
Returns summary tables and optionally generates simple visualizations.
}
\details{
Summarizes results from modeling and post-processing at the scale of specific
spatial blocks to allow for a nuanced look at spatiotemporal patterns.
}
\examples{
con_file <- system.file("extdata/binary/consensus_stack.tif",
                        package = "TemporalModelR")

binary_stack <- terra::rast(con_file)

study_crs <- sf::st_crs(binary_stack)

zones_sf <- rbind(
  sf::st_sf(ZONE = "West",
            geometry = sf::st_sfc(sf::st_polygon(list(
              matrix(c(0, 0, 1500, 1500, 0,
                       0, 1500, 1500, 0, 0), ncol = 2)
            )), crs = study_crs)),
  sf::st_sf(ZONE = "East",
            geometry = sf::st_sfc(sf::st_polygon(list(
              matrix(c(1500, 1500, 3000, 3000, 1500,
                       0,    1500, 1500, 0,    0),    ncol = 2)
            )), crs = study_crs))
)

time_steps <- expand.grid(
  year             = 1:15,
  season           = "Spring",
  stringsAsFactors = FALSE
)

analyze_trends_by_spatial_unit(
  shapefile_path = zones_sf,
  name_field     = "ZONE",
  binary_stack   = binary_stack,
  time_steps     = time_steps,
  create_plot    = FALSE,
  verbose        = FALSE
)
}
\seealso{
Post-processing: \code{\link{summarize_raster_outputs}},
  \code{\link[TemporalModelR]{analyze_temporal_patterns}}
}
