% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/panoramic-visualization.R
\name{create_spatial_network}
\alias{create_spatial_network}
\title{Construct spatial colocalization network from PANORAMIC results}
\usage{
create_spatial_network(
  se_diff,
  fdr_threshold = 0.05,
  leiden_resolution = 1,
  z_sign = c("both", "positive", "negative"),
  include_nonsig = FALSE,
  nonsig_max_fdr = 1,
  directed = FALSE,
  sig_operator = c("lt", "gt")
)
}
\arguments{
\item{se_diff}{A SummarizedExperiment returned by
\code{panoramic_meta_mv(...)}, where
rowData(se_diff) contains
at least ct1, ct2, z_diff, p_diff, and fdr_diff.}

\item{fdr_threshold}{Numeric scalar. FDR threshold used to define
significance for \code{edge_class} and, when
\code{include_nonsig = FALSE}, to filter edges (default 0.05).}

\item{leiden_resolution}{Numeric. Clustering resolution for the Leiden algorithm.}

\item{z_sign}{Character sign filter for \code{z_diff}, one of
\code{"both"} (default), \code{"positive"}, or \code{"negative"}.
This enables group-specific networks by retaining only positive or
only negative differential effects.}

\item{include_nonsig}{Logical. If TRUE, include non-significant edges
(up to \code{nonsig_max_fdr}) and mark them as dotted in plotting.
If FALSE (default), keep only \code{fdr_diff < fdr_threshold}.}

\item{nonsig_max_fdr}{Numeric upper bound for retained edges when
\code{include_nonsig = TRUE} (default 1.0).}

\item{directed}{Logical. If \code{TRUE}, construct a directed network
(and directed centrality metrics). If \code{FALSE}, construct an
undirected network.}

\item{sig_operator}{One of \code{"lt"} (default) or \code{"gt"} controlling
significance threshold direction for \code{fdr_diff} when
\code{include_nonsig = FALSE}. \code{"lt"} uses standard
\code{fdr_diff < fdr_threshold}; \code{"gt"} inverts the threshold
(diagnostic use only).}
}
\value{
A list with components:
\itemize{
\item graph: an igraph object (directed or undirected) with edge attributes
\code{weight}, \code{fdr}, \code{pval}, \code{edge_sig},
\code{edge_class} and vertex attributes
\code{cluster}, \code{cluster_id}, \code{degree},
\code{betweenness}, \code{strength}.
\item clusters: the community structure object from
\code{igraph::cluster_leiden()}.
\item n_clusters: number of detected clusters.
\item modularity: modularity score of the clustering.
\item z_sign: the applied sign filter.
\item fdr_threshold: the applied significance threshold.
\item include_nonsig: whether non-significant edges were included.
\item nonsig_max_fdr: maximum retained FDR when non-significant edges
are included.
}
}
\description{
Build a cell-type network where edges represent differential
spatial colocalization between cell-type pairs, based on the output of
\code{panoramic_meta_mv(...)} (or a compatible function). Edges are
filtered by FDR and optional \code{z_diff} sign, and weighted by
\code{|z_diff|}.
}
\examples{
se_diff <- SummarizedExperiment::SummarizedExperiment(
  assays = list(dummy = matrix(0, nrow = 3, ncol = 1)),
  rowData = S4Vectors::DataFrame(
    ct1 = c("A", "A", "B"),
    ct2 = c("B", "C", "C"),
    z_diff = c(2.0, -1.5, 1.2),
    p_diff = c(0.01, 0.03, 0.20),
    fdr_diff = c(0.02, 0.05, 0.30)
  )
)

net <- create_spatial_network(
  se_diff,
  fdr_threshold = 0.2,
  z_sign = "both",
  include_nonsig = TRUE
)

net$graph
}
