% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/R-neighbourhood.R
\name{count_neighborhood}
\alias{count_neighborhood}
\title{Count annotated spot types in the neighborhood of a cluster or point}
\usage{
count_neighborhood(
  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 (optional, required for detailed
analysis)}

\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.}

\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 count in neighborhoods. 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{neighborhood}{Cluster label or inlaid value (from neighboring spots).}
  \item{count}{Number of times this cluster/type appears in the neighborhood.}
  \item{proportion}{Proportion of this cluster/type relative to all neighbors.}
}
Rows are sorted by count in descending order.
}
\description{
This function computes summary statistics of cluster types in the
neighborhood
of a target cluster or a specific point. It uses [get_neighborhood_spots()]
internally
to identify neighbors, then counts how many belong to each cluster type.
}
\details{
This function wraps [get_neighborhood_spots()] and summarizes the results by
counting spots from each neighboring cluster or inlaid type. In cluster mode, the source
cluster
itself is excluded from the counts. In point mode, all neighboring clusters
are counted.

The result shows the composition of the neighborhood: how many spots of each
cluster
type surround the target.
}
\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
)
# Count cluster types in neighborhood of cluster 1
neighbor_counts <- count_neighborhood(df, cluster = 1, k = 50)
neighbor_counts

# Count cluster types around a specific point
first_spot <- df$spot_id[1]
point_neighbors <- count_neighborhood(df, spot_id = first_spot, k = 10)
point_neighbors

}
