% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/connectivity.R
\name{analyse_connectivity}
\alias{analyse_connectivity}
\title{Analyse spatial connectivity of suitable habitat cells}
\usage{
analyse_connectivity(
  result,
  min_suitability = 0.5,
  gap_m = 500,
  min_patch_cells = 3L,
  verbose = TRUE
)
}
\arguments{
\item{result}{Dataframe from \code{\link[=predict_oyster]{predict_oyster()}} with \code{lat}, \code{lon},
\code{suitability}, and \code{suitability_class} columns.}

\item{min_suitability}{Numeric. Minimum suitability score for a cell to be
included in the connectivity analysis (default 0.5, i.e. Moderate+).}

\item{gap_m}{Numeric. Maximum distance in metres between two suitable cells
for them to be considered connected (default 500 m).}

\item{min_patch_cells}{Integer. Patches smaller than this are flagged as
isolated (default 3 cells).}

\item{verbose}{Logical. Print connectivity summary (default TRUE).}
}
\value{
Input dataframe with additional columns:
\code{patch_id} (integer -- unique patch identifier; NA for non-suitable cells),
\code{patch_size} (number of cells in the patch),
\code{patch_area_km2} (approximate area based on cell density),
\code{connectivity_class} (\code{"isolated"}, \code{"small"}, \code{"moderate"}, \code{"large"}),
\code{is_hub} (logical -- TRUE for the highest-scoring cell in each patch,
useful as candidate introduction points).
}
\description{
Builds a spatial graph of cells above a suitability threshold and identifies
connected components -- contiguous patches of suitable habitat. Isolated
cells or small patches are flagged because they are at higher risk of:
\itemize{
\item \strong{Recruitment failure} -- larvae from isolated populations may be
flushed away before settling back in the patch.
\item \strong{Genetic bottlenecks} -- small isolated populations have lower allelic
diversity and reduced adaptive capacity.
\item \strong{Local extinction without recolonisation} -- if a patch is lost, there
are no connected source populations to recolonise.
}

Two cells are considered connected if they are within \code{gap_m} metres of
each other (default 500 m -- approximately the scale of larval dispersal
during a tidal cycle at moderate current speeds). Connectivity is computed
using a fast union-find (disjoint set) algorithm -- no external graph
packages required.
}
\examples{
\donttest{
result <- predict_oyster(survey, "ostrea_edulis")
result <- analyse_connectivity(result, gap_m = 500)

# Large well-connected patches are the best restoration targets
good_patches <- subset(result,
  connectivity_class == "large" & suitability_class == "High")

# Count patches
table(result$connectivity_class)

# Visualise -- patch_id maps to distinct colours in QGIS
export_geotiff(result, "connectivity.tif")
}
}
