% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Battlefield-package.R
\docType{package}
\name{Battlefield-package}
\alias{Battlefield}
\alias{Battlefield-package}
\title{Battlefield: Swiss-army toolkit for spatial transcriptomics region selection}
\description{
Battlefield provides low-level, modular utilities to define and extract spatial
spots from specific regions in spatial transcriptomics data. It supports four core
workflows: identifying cluster interfaces, characterizing intra-cluster layers,
modeling inter-cluster trajectories, and analyzing neighborhood composition.
}
\section{Key Features}{

\describe{
  \item{\strong{Cluster Interfaces}}{Identify and analyze boundary regions
    where distinct tissue or cell populations interact.
    See \code{\link{select_border_spots}}, \code{\link{build_all_borders}},
    \code{\link{directed_cluster_interface_pairs}}.}

  \item{\strong{Intra-cluster Layers}}{Characterize spatial layers or gradients
    within a single cluster (border, intermediate, core).
    See \code{\link{create_cluster_layers}}, \code{\link{create_all_layers}}.}

  \item{\strong{Inter-cluster Trajectories}}{Model spatial transitions across
    multiple clusters via centroid-to-centroid Bresenham paths.
    See \code{\link{build_one_trajectory}}, \code{\link{build_similar_trajectories}}.}

  \item{\strong{Neighborhood Composition}}{Analyze k-NN cluster composition
    with optional distance constraints.
    See \code{\link{count_neighborhood}}, \code{\link{get_neighborhood_spots}}.}
}
}

\section{Core Workflow}{

1. Start with a \code{\link[SpatialExperiment]{SpatialExperiment}} object
   containing spot coordinates and cluster annotations.
2. Extract spot metadata via \code{colData(spe)} to create a working \code{data.frame}.
3. Apply selection functions (e.g., \code{\link{select_border_spots}},
   \code{\link{create_cluster_layers}}) to identify regions of interest.
4. Integrate results back to \code{spe} using helper functions:
   \code{\link{add_borders_to_spe}}, \code{\link{add_layers_to_spe}},
   \code{\link{add_trajectories_to_spe}}.
5. Use annotated \code{spe} for downstream analyses (e.g., ligand–receptor
   interactions via \pkg{BulkSignalR}).
}

\section{Key Algorithms}{

\itemize{
  \item \strong{Bresenham line rasterization}
    (\code{\link{bresenham_line}}): Traces discrete paths on a spot grid.
  \item \strong{k-NN neighborhood detection} (via \pkg{RANN}):
    Identifies spatial neighbors and cluster composition.
  \item \strong{Grid type inference} (\code{\link{detect_grid_type}}):
    Distinguishes square vs. hexagonal layouts.
  \item \strong{Layer classification}: Uses radial distance quantiles to
    stratify clusters into border/intermediate/core regions.
  \item \strong{Centroid-based trajectories}: Connects cluster centroids
    and selects nearby spots for trajectory analysis.
}
}

\section{Important Data Shapes}{

All selection functions work with \code{data.frame}s containing:
\describe{
  \item{\strong{Input columns (required)}}{
    \code{x}, \code{y} (numeric coordinates),
    \code{cluster} (any grouping type),
    \code{spot_id} (must match \code{colnames(spe)} for SPE integration).
  }
  \item{\strong{Output columns (added by selection functions)}}{
    \code{interface}, \code{directed_pair} (e.g., "3-4"),
    \code{is_border}, \code{is_core} (logical flags),
    \code{layer} ("border"/"intermediate"/"core").
    Keep these column names stable across pipelines.
  }
}
}

\section{Example Datasets}{

Three simulated \code{SpatialExperiment} objects are included for testing:
\itemize{
  \item \code{\link{visium_simulated_spe}}: Square grid (Visium-like).
  \item \code{\link{visiumHD_8um_simulated_spe}}: Hexagonal grid (VisiumHD 8 µm binned).
  \item \code{\link{visiumHD_16um_simulated_spe}}: Hexagonal grid (VisiumHD 16 µm binned).
}
Load with: \code{data("visium_simulated_spe", package = "Battlefield")}
}

\section{Links & References}{

\itemize{
  \item Main vignette: \code{vignettes/Battlefield-Main.Rmd} — comprehensive
    examples for all four core workflows.
  \item GitHub: \url{https://github.com/ZheFrench/Battlefield}
}
}

\seealso{
Useful links:
\itemize{
  \item \url{https://github.com/ZheFrench/BattleField}
  \item \url{https://zhefrench.github.io/Battlefield/}
  \item Report bugs at \url{https://github.com/ZheFrench/BattleField/issues}
}

}
\author{
\strong{Maintainer}: Jean-Philippe Villemin \email{jpvillemin@gmail.com} (\href{https://orcid.org/0000-0002-1838-5880}{ORCID})

Other contributors:
\itemize{
  \item European Research Council (ERC-2022) [funder]
}

}
\keyword{internal}
