% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/R-neighbourhood.R
\name{get_neighborhood_spots}
\alias{get_neighborhood_spots}
\title{Get neighborhood spots around a target cluster or point}
\usage{
get_neighborhood_spots(
  df,
  cluster = NULL,
  spot_id = NULL,
  k = 100,
  max_dist = NULL,
  inlaid_col = NULL,
  coords = c("x", "y"),
  cluster_col = "cluster"
)
}
\arguments{
\item{df}{A data.frame containing at least the columns `x`, `y`,
  cluster identifier column, and `spot_id`.
  - `x`, `y`: numeric coordinates of spots
- cluster column (name specified by `cluster_col`): cluster assignment for
each spot
  - `spot_id`: unique identifier for each spot}

\item{cluster}{The cluster label for which to analyze the neighborhood. Either
`cluster`
  or `spot_id` must be provided, but not both.}

\item{spot_id}{Character. The spot identifier to find neighbors for. Either
`cluster`
  or `spot_id` must be provided, but not both.}

\item{k}{Integer. Number of nearest neighbors to consider. Default is 100.
Larger values capture more distant neighbors. If k exceeds the number of 
spots, it will be capped at nrow(df) - 1.}

\item{max_dist}{Numeric. Maximum distance from the target to consider.
If `NULL` (default), all neighbors up to k are included without distance
filtering.}

\item{inlaid_col}{Character. Name of the column containing inlaid/annotation
values to return in the `neighborhood` column. If `NULL` (default), uses the
  `cluster_col` value. This allows counting neighborhood composition by any
  column (e.g., cell type, tissue type).}

\item{coords}{Character vector of length 2 giving the coordinate column
names.
  Default is `c("x", "y")`.}

\item{cluster_col}{Character. Name of the column containing cluster
assignments.
  Default is `"cluster"`.}
}
\value{
A data.frame with columns:
\describe{
  \item{spot_id}{Unique spot identifier.}
  \item{x}{X coordinate.}
  \item{y}{Y coordinate.}
  \item{neighborhood}{Value from `inlaid_col` (or cluster if inlaid_col is NULL) of the neighbor spot.}
  \item{cluster}{The source cluster or spot_id being analyzed.}
  \item{is_neighborhood}{Logical, always TRUE for returned rows.}
}
Rows are sorted by neighborhood and spot_id.
}
\description{
This function identifies all spots in the neighborhood of a target cluster
or a specific point using k-nearest neighbors search. It returns all neighbor
spots
that were identified, marking which ones are neighbors.
}
\details{
The function can work in two modes:
- **Cluster mode**: If `cluster` is provided, computes k-nearest neighbors for
all spots
in that cluster. Returns all neighbors found (excluding source cluster
spots).
- **Point mode**: If `spot_id` is provided, finds the k-nearest neighbors to
  specific spot.
}
\examples{
data("visium_simulated_spe", package = "Battlefield")
spe <- visium_simulated_spe
df <- data.frame(
  spot_id = colnames(spe),
  x = SpatialExperiment::spatialCoords(spe)[, 1],
  y = SpatialExperiment::spatialCoords(spe)[, 2],
  cluster = SummarizedExperiment::colData(spe)$cluster
)
# Get all neighbor spots for cluster 1
neighbors_cluster <- get_neighborhood_spots(df, cluster = 1, k = 50)
head(neighbors_cluster)

# Get neighbors for a specific point
first_spot <- df$spot_id[1]
neighbors_point <- get_neighborhood_spots(df, spot_id = first_spot, k = 10)
head(neighbors_point)

}
