% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatiotemporal_rarefaction.R
\name{spatiotemporal_rarefaction}
\alias{spatiotemporal_rarefaction}
\title{Spatiotemporal Rarefaction of Species Occurrence Data}
\usage{
spatiotemporal_rarefaction(points_sp, output_dir, reference_raster,
                           time_cols = NULL, xcol = NULL, ycol = NULL,
                           points_crs = NULL, output_prefix = "Pts_Database",
                           verbose = TRUE)
}
\arguments{
\item{points_sp}{Input point data. Accepts an sf object, data frame,
SpatialPointsDataFrame, or file path to a \code{.csv}, \code{.shp},
\code{.geojson}, or \code{.gpkg} file.}

\item{output_dir}{Character. Directory where output CSV files will be saved.}

\item{reference_raster}{Character, SpatRaster, or RasterLayer. Raster used
to define pixel boundaries for rarefaction. Accepts a file path,
RasterLayer, or SpatRaster.}

\item{time_cols}{Character vector. Column names in \code{points_sp} defining
temporal grouping for spatiotemporal rarefaction. When \code{NULL}
(default), only spatial rarefaction is performed.}

\item{xcol}{Character. Name of the x-coordinate column. Required when
\code{points_sp} is a CSV file or data frame.}

\item{ycol}{Character. Name of the y-coordinate column. Required when
\code{points_sp} is a CSV file or data frame.}

\item{points_crs}{Character or CRS object. CRS of the input points.
Required when \code{points_sp} is a CSV file or data frame.}

\item{output_prefix}{Character. Prefix for output file names. Default is
\code{"Pts_Database"}. Output files are named
\code{<output_prefix>_OnePerPix.csv} and, when \code{time_cols} are
provided, \code{<output_prefix>_OnePerPixPerTimeStep.csv}.}

\item{verbose}{Logical. If \code{TRUE} (default), prints progress
messages during processing. Includes file loading, missing-data removal
counts, rarefaction summaries, and a final comparison of spatial
vs spatiotemporal point counts.}
}
\value{
Invisibly returns a list containing:
\itemize{
  \item \code{input_points}: Integer. Number of input points after CRS
    alignment and removal of rows with missing time column values.
  \item \code{spatial_points}: Integer. Number of points retained after
    spatial-only rarefaction (one per pixel).
  \item \code{spatiotemporal_points}: Integer. Number of points retained
    after spatiotemporal rarefaction (one per pixel per time combination).
    \code{NA} when \code{time_cols} is not provided.
  \item \code{time_cols_used}: Character vector of time columns used.
    \code{NULL} when \code{time_cols} is not provided.
  \item \code{spatial_table}: Data frame of spatially rarefied points with
    columns \code{pixel_id}, \code{X}, \code{Y}, and any \code{time_cols}.
  \item \code{spatiotemporal_table}: Data frame of spatiotemporally rarefied
    points with columns \code{pixel_id}, \code{X}, \code{Y}, and
    \code{time_cols}. \code{NULL} when \code{time_cols} is not provided.
  \item \code{files_created}: Named list of file paths written. Always
    contains \code{$spatial}; additionally contains
    \code{$spatiotemporal} when \code{time_cols} are provided.
}
}
\description{
Preprocessing function that rarefies species occurrence data to one point per
raster pixel, optionally accounting for temporal components. Reduces sampling
bias and spatial autocorrelation in occurrence datasets.
}
\details{
The function assigns each point to a raster pixel using the resolution and
extent of \code{reference_raster}, then performs:
\itemize{
  \item Spatial rarefaction: retains one point per pixel, written to
    \code{<output_prefix>_OnePerPix.csv}.
  \item Spatiotemporal rarefaction (when \code{time_cols} are provided):
    retains one point per pixel per unique combination of time column values,
    written to \code{<output_prefix>_OnePerPixPerTimeStep.csv}.
}

Output CSV files are suitable as direct input to
\code{\link{temporally_explicit_extraction}}.
}
\examples{
pts_file <- system.file(
  "extdata/points/synthetic_occurrence_points.csv",
  package = "TemporalModelR"
)

ref_file <- system.file("extdata/rasters_raw/elevation.tif",
                        package = "TemporalModelR")

out_dir  <- file.path(tempdir(), "rarefied")

spatiotemporal_rarefaction(
  points_sp        = pts_file,
  output_dir       = out_dir,
  reference_raster = ref_file,
  time_cols        = c("year", "season"),
  xcol             = "x",
  ycol             = "y",
  points_crs       = terra::crs(terra::rast(ref_file)),
  verbose          = FALSE
)
}
\seealso{
Preprocessing: \code{\link{temporally_explicit_extraction}},
  \code{\link{spatiotemporal_partition}}
}
