% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/R-layer.R
\name{create_cluster_layers}
\alias{create_cluster_layers}
\title{Create layer classification for spots in a cluster}
\usage{
create_cluster_layers(
  df,
  target_cluster,
  k = 6,
  max_dist = NULL,
  intermediate_quantile = 0.5,
  coord_cols = c("x", "y"),
  cluster_col = "cluster"
)
}
\arguments{
\item{df}{A data.frame containing at least the coordinate columns and a
cluster label column.}

\item{target_cluster}{Cluster label for which to create layers.}

\item{k}{Integer. Number of nearest neighbors to consider (excluding self)
when
  identifying border spots. Default is 6.}

\item{max_dist}{Optional numeric. Maximum Euclidean distance for neighbors.
If `NULL`, no distance filtering is applied.}

\item{intermediate_quantile}{Numeric between 0 and 1. The quantile of
distances to border
used to define the intermediate layer threshold. Default is 0.5 (median).
#' Spots with
distance to border <= this quantile threshold are classified as intermediate.
Use lower values (e.g., 0.33) for narrower intermediate layers, higher values
(e.g., 0.75)
  for wider intermediate layers.}

\item{coord_cols}{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 labels.
Default is `"cluster"`.}
}
\value{
A data.frame based on `df` filtered to contain only spots from
`target_cluster`, with an additional column:
- `layer`: character, one of "border", "intermediate", or "core"
}
\description{
This function classifies spots within a target cluster into three layers:
core, intermediate, and border. The border layer consists of spots at the
cluster interface (touching other clusters). The core layer consists of spots
far from any border. The intermediate layer bridges the two, with depth
defined by proximity to the border.
}
\details{
Layer definitions:
- **Border**: Spots in the target cluster that touch at least one spot from a
different cluster (kNN-based).
- **Intermediate**: Non-border spots whose distance to the nearest border
spot is within
  the `intermediate_quantile` threshold of all non-border spots.
- **Core**: All remaining non-border spots that are far from the border.

The `intermediate_quantile` parameter controls the depth of the intermediate
layer:
- 0.33: Narrow intermediate layer (only very close to border)
- 0.50: Moderate intermediate layer (median distance threshold)
- 0.75: Wide intermediate layer (most non-border spots included)
}
\examples{
data("visiumHD_16um_simulated_spe", package = "Battlefield")
spe <- visiumHD_16um_simulated_spe
df <- data.frame(
  spot_id = colnames(spe),
  x = SpatialExperiment::spatialCoords(spe)[, 1],
  y = SpatialExperiment::spatialCoords(spe)[, 2],
  cluster = SummarizedExperiment::colData(spe)$cluster
)
# Default: moderate depth
layers <- create_cluster_layers(df, target_cluster = 1, k = 6)
table(layers$layer)

# Narrow intermediate layer
layers_narrow <- create_cluster_layers(df, target_cluster = 1, k = 6,
intermediate_quantile = 0.33)
table(layers_narrow$layer)

}
