% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/R-grid.R
\name{get_neighborhood_params}
\alias{get_neighborhood_params}
\title{Suggest neighborhood parameters based on detected grid type}
\usage{
get_neighborhood_params(
  df,
  coords = c("x", "y"),
  square_connectivity = c(4, 8),
  tolerance = 0.1,
  verbose = TRUE
)
}
\arguments{
\item{df}{A data.frame containing spatial coordinates.}

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

\item{square_connectivity}{Integer-like choice for square grids: `4` (Von
Neumann)
  or `8` (Moore). Default is `c(4, 8)` which selects the first value (`4`).}

\item{tolerance}{Numeric. Passed to [detect_grid_type()] to match
characteristic
  ratios (sqrt(2) / sqrt(3)). Default is 0.1.}

\item{verbose}{Logical. If `TRUE`, prints diagnostic messages. Default is
`TRUE`.}
}
\value{
A named list with neighborhood parameters: `grid_type`,
`connectivity`,
`radius`, `k`, and `comment`.
}
\description{
This helper detects the spatial grid type (square vs hexagonal) and returns
recommended neighborhood parameters for building local adjacency / neighbor
queries (e.g., for border detection or spatial graphs).
}
\details{
It relies on [detect_grid_type()] to estimate the grid step size and grid
geometry, then chooses typical parameters:
\itemize{
  \item **Hexagonal (Visium)**: 6-neighborhood, radius ~ step
  \item **Square (Visium HD)**: 4- or 8-neighborhood, radius ~ step (4) or
  ~ sqrt(2)*step (8)
}


Returned values:
\describe{
\item{grid_type}{Detected grid type: `"hexagonal"`, `"square"`, or
`"unknown"`.}
\item{connectivity}{Nominal grid connectivity (6 for hex, 4 or 8 for
square).}
  \item{r}{Recommended distance threshold (radius) to define adjacency.}
  \item{k_max}{A suggested upper bound for kNN queries (used as a safe cap).}
  \item{comment}{Human-readable description of the choice.}
}

Notes:
\itemize{
\item `radius` is set to `1.01 * step` (or `1.01 * sqrt(2) * step` for
#' 8-connectivity)
  to be slightly permissive under small numerical noise.
  \item `k` is deliberately larger than the nominal connectivity to make sure
  enough candidates are retrieved before applying distance-based filtering.
}
}
\examples{
# Square grid example
sq <- expand.grid(x = 0:9, y = 0:9)
get_neighborhood_params(sq, square_connectivity = 4, verbose = FALSE)

# Hexagonal grid example
nx <- 10; ny <- 10
hex <- expand.grid(i = 0:(nx-1), j = 0:(ny-1))
hex$x <- hex$i + 0.5 * (hex$j \%\% 2)
hex$y <- (sqrt(3)/2) * hex$j
hex <- hex[, c("x","y")]
get_neighborhood_params(hex, verbose = FALSE)

}
