% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/analyze_temporal_patterns.R
\name{analyze_temporal_patterns}
\alias{analyze_temporal_patterns}
\title{Analyze Temporal Patterns in Binary Raster Time Series}
\usage{
analyze_temporal_patterns(
  binary_stack,
  summary_raster,
  time_steps,
  fastcpd_params = list(),
  output_dir = NULL,
  n_tiles_x = 1,
  n_tiles_y = 1,
  alpha = 0.05,
  spatial_autocorrelation = TRUE,
  verbose = TRUE,
  estimate_time = TRUE,
  overwrite = FALSE
)
}
\arguments{
\item{binary_stack}{RasterStack, RasterBrick, or character. Stack of binary
raster layers across time, or path to directory containing binary rasters.
Typically from \code{\link{summarize_raster_outputs}}.}

\item{summary_raster}{RasterLayer. Per-pixel proportion of time periods where
a pixel is suitable. From \code{\link{summarize_raster_outputs}}.}

\item{time_steps}{Integer vector. Time labels corresponding to raster layers
(same length as number of layers).}

\item{fastcpd_params}{List. Named list of parameters passed to fastcpd
changepoint detection function. Default is empty list. Supports parameterization
from \code{\link[fastcpd]{fastcpd_binomial}}.}

\item{output_dir}{Character. Optional. Output directory for pattern rasters.
When \code{NULL} (default), rasters are written to temporary files and not
saved persistently. Provide a path to write named output files to disk.}

\item{n_tiles_x}{Integer. Number of tiles in the x direction for tiled
processing. Default is \code{1}. Increase to reduce peak memory use for
large rasters and prevent crashes.}

\item{n_tiles_y}{Integer. Number of tiles in the y direction for tiled
processing. Default is \code{1}. Increase to reduce peak memory use for
large rasters and prevent crashes.}

\item{alpha}{Numeric. Significance level for changepoint detection. Default
is \code{0.05}.}

\item{spatial_autocorrelation}{Logical. If \code{TRUE} (default), includes a
neighbor variable in the changepoint analysis to account for spatial
autocorrelation.}

\item{verbose}{Logical. If \code{TRUE} (default), prints progress
messages during processing.}

\item{estimate_time}{Logical. If \code{TRUE} (default), estimates runtime from
a sample of pixels before full processing begins. If \code{FALSE}, proceeds
directly to processing without a time estimate.}

\item{overwrite}{Logical. If \code{TRUE}, overwrites existing output files.
If \code{FALSE} (default), existing files are skipped.}
}
\value{
Invisibly returns a list containing:
\itemize{
  \item \code{pattern}: \code{SpatRaster} classifying pixels as integer
    values 1-6, corresponding to "Never Suitable", "Always Suitable",
    "No Pattern", "Increasing Suitability", "Decreasing Suitability",
    or "Fluctuating".
  \item \code{time_decrease}: \code{SpatRaster} showing the time step of
    first significant decrease for pixels classified as decreasing.
  \item \code{time_increase}: \code{SpatRaster} showing the time step of
    first significant increase for pixels classified as increasing.
}
}
\description{
Postprocessing function that applies changepoint detection methods to
identify temporal trends in habitat suitability across consecutive
predictions. Classifies pixels as stable, increasing in quality, or
decreasing in quality, and identifies time periods of significant change.
}
\details{
Applies changepoint detection using fastcpd to identify significant temporal
shifts in spatial suitability. Accounts for spatial and temporal
autocorrelation when \code{spatial_autocorrelation = TRUE}. The
\code{fastcpd_params} list allows customization of the changepoint detection
algorithm, and is passed through to \code{\link[fastcpd]{fastcpd.binomial}}
(e.g. \code{list(cost_adjustment = "BIC", trim = 0.025)}).

Pattern classifications enable identification of expanding, contracting, or
stable g-space distributions over time or site level assessments of directional
change in suitability.

Classification assumes consecutive rasters. Time periods
shorter than ~15 time steps may be too short to classify increases or decreases.
}
\examples{
\donttest{
  con_file <- system.file("extdata/binary/consensus_stack.tif",
                          package = "TemporalModelR")

  frq_file <- system.file("extdata/binary/frequency_raster.tif",
                          package = "TemporalModelR")

  binary_stack   <- terra::rast(con_file)

  summary_raster <- terra::rast(frq_file)

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

  analyze_temporal_patterns(
    binary_stack            = binary_stack,
    summary_raster          = summary_raster,
    time_steps              = time_steps,
    output_dir              = tempdir(),
    spatial_autocorrelation = FALSE,
    overwrite               = TRUE,
    estimate_time           = FALSE,
    verbose                 = FALSE
  )
}
}
\seealso{
Postprocessing: \code{\link{summarize_raster_outputs}}

External: \code{\link[fastcpd]{fastcpd}}
}
