% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/blisa.R
\name{blisa}
\alias{blisa}
\alias{blisa.default}
\alias{blisa.SpatialExperiment}
\title{Run BLISA spatial cell-cell communication analysis}
\usage{
blisa(x, ...)

\method{blisa}{default}(
  x,
  bins,
  LR_df = NULL,
  bin_size = 50,
  dmax = 250,
  nsim = 999,
  p_cutoff = 0.05,
  min_ligand = 10,
  min_receptor = 10,
  min_cells = 1,
  n_cells_col = NA,
  annotation_col = "annotation",
  default_mode = "diffuse",
  diffuse_category = c("Secreted Signaling", "Non-protein Signaling"),
  species = c("human", "mouse"),
  genes = NULL,
  counts_by_group = NULL,
  ...
)

\method{blisa}{SpatialExperiment}(x, bin_size = 50, LR_df = NULL, group = "cell_type", genes = NULL, ...)
}
\arguments{
\item{x}{A gene-by-bin count matrix (for \code{blisa.default}) or a
cell-level \code{SpatialExperiment} object (for
\code{blisa.SpatialExperiment}).}

\item{...}{Additional arguments passed to the relevant method.}

\item{bins}{An \code{sf} object of bin polygons. Row order must match the
column order of \code{x}.}

\item{LR_df}{Data frame of ligand-receptor pairs with columns
\code{ligand.symbol} and \code{receptor.symbol}. When \code{NULL},
CellChatDB for the chosen \code{species} is downloaded automatically.}

\item{bin_size}{Numeric. Width of each hexagonal bin in coordinate units
(e.g. microns). Passed to \code{\link{hexBinCells}} and
\code{\link{computeSpatialWeights}}. Default \code{50}.}

\item{dmax}{Numeric. Maximum distance for diffuse-mode neighbours.
Default \code{250}.}

\item{nsim}{Integer. Number of permutations for Moran's I significance.
Default \code{999}.}

\item{p_cutoff}{Numeric. P-value threshold for High-High hotspots.
Default \code{0.05}.}

\item{min_ligand}{Numeric. Minimum ligand count threshold. Default \code{10}.}

\item{min_receptor}{Numeric. Minimum receptor count threshold.
Default \code{10}.}

\item{min_cells}{Integer. Bins with fewer cells are excluded from
Moran's I and assigned neutral statistics (\emph{p} = 1, LISA = 0).
Ignored when \code{n_cells_col = NA}. Default \code{1}.}

\item{n_cells_col}{Character or \code{NA}. Column in \code{bins} holding
per-bin cell counts used for \code{min_cells} filtering.
Set to \code{NA} to skip (default).}

\item{annotation_col}{Character. Column in \code{LR_df} specifying
interaction category used for communication-mode assignment. Default
\code{"annotation"}.}

\item{default_mode}{Character. CCC mode assigned to LR pairs whose
annotation does not match \code{diffuse_category}. Default
\code{"diffuse"}.}

\item{diffuse_category}{Character vector of annotation categories treated
as diffuse signalling.}

\item{species}{Character. Which CellChatDB to download when
\code{LR_df = NULL}. One of \code{"human"} (default) or \code{"mouse"}.}

\item{genes}{Character vector of gene names to consider when matching
ligand-receptor pairs. Defaults to \code{rownames(x)} (all genes in the
\code{SpatialExperiment} object).}

\item{counts_by_group}{Named list of gene-by-bin count matrices, one per
group level (e.g. cell type), as returned by \code{\link{hexBinCells}}
when \code{group} is supplied. When provided, \code{\link{runCCI}} is
called automatically after the BLISA loop and its output is included in
the result as \code{CCI_scores}. Default \code{NULL}.}

\item{group}{Character. Column name in \code{colData(x)} to use as the
grouping variable (e.g. cell type) for per-group bin aggregation and
downstream CCI analysis via \code{\link{runCCI}}. If the column is not
found in \code{colData(x)}, a message is issued and CCI is skipped.
Default \code{"cell_type"}.}
}
\value{
A list; see individual method documentation for details.

An object of class \code{blisa} with four components:
\describe{
\item{LR_results}{Data frame of BLISA results for each LR pair, including
\code{ccc_mode}, \code{sig_numbers}, \code{sig_index}, \code{sig_pval},
\code{all_pval}, \code{all_lisa}, \code{all_quadrant}, and original
columns from \code{LR_df}. \code{all_quadrant} is a character vector
of \code{spdep::hotspot} quadrant labels (\code{"High-High"},
\code{"Low-Low"}, etc.) for every bin; non-tested bins are \code{NA}.}
\item{bins}{Bin-level \code{sf} object of hexagonal polygons.}
\item{spatial_weights}{Spatial weights list from \code{\link{computeSpatialWeights}}.}
\item{CCI_scores}{\code{NULL} unless \code{counts_by_group} is supplied,
in which case a wide data frame of interaction scores from
\code{\link{runCCI}}: rows are \code{"Sender->Receiver"} group pairs,
columns are LR pairs.}
}
}
\description{
Generic function for running BLISA (Bivariate Local Indicator of Spatial
Association). Dispatches on the class of \code{x}:
\itemize{
\item \code{blisa.default} accepts a pre-binned gene-by-bin count
matrix and a matching \code{bins} polygon object.
\item \code{blisa.SpatialExperiment} accepts a cell-level
\code{SpatialExperiment} object and bins cells into hexagonal tiles
internally via \code{\link{hexBinCells}} before running the analysis.
}
}
\section{Methods (by class)}{
\itemize{
\item \code{blisa(default)}: Method for a gene-by-bin count matrix.

\item \code{blisa(SpatialExperiment)}: Method for a cell-level SpatialExperiment object.
Bins cells into hexagonal tiles via \code{\link{hexBinCells}} then
delegates to \code{blisa.default}.

}}
