% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/graph_lgcp.R
\name{graph_lgcp_sim}
\alias{graph_lgcp_sim}
\title{Simulate log-Gaussian Cox processes on metric graphs}
\usage{
graph_lgcp_sim(n = 1, intercept = 0, sigma, range, alpha, graph)
}
\arguments{
\item{n}{Integer. Number of replicate point patterns to simulate. Default is 1.}

\item{intercept}{Numeric scalar or vector. Mean value(s) of the log-intensity
field. Can be a constant or vary spatially if provided as a vector of length
equal to the number of mesh nodes.}

\item{sigma}{Numeric. Marginal standard deviation parameter of the Gaussian field.}

\item{range}{Numeric. Practical correlation range parameter of the Gaussian field.}

\item{alpha}{Numeric. Smoothness parameter of the Whittle-Matérn field. Currently
supports values 1 and 2, corresponding to exponential and Matérn-3/2 covariance
functions respectively.}

\item{graph}{A \code{metric_graph} object with a built mesh. The graph must have an
existing mesh (built with \code{graph$build_mesh()}) and computed FEM matrices
(computed with \code{graph$compute_fem()}).}
}
\value{
If \code{n = 1}, returns a list with components:
\describe{
\item{u}{Numeric vector of the simulated Gaussian field values at mesh nodes}
\item{edge_number}{Integer vector of edge numbers where points were simulated}
\item{edge_loc}{Numeric vector of locations along edges (normalized coordinates)}
}
If \code{n > 1}, returns a list of length \code{n}, where each element is a list with
the above components.
}
\description{
This function simulates point patterns from a log-Gaussian Cox process (LGCP)
driven by Whittle-Matérn Gaussian random fields on metric graphs. The intensity
function is modeled as \eqn{\lambda(s) = exp(\beta + u(s))}{lambda(s) = exp(beta + u(s))}, where \eqn{\beta}{beta} is an intercept parameter
and \eqn{u(s)}{u(s)} is a Gaussian field with Whittle-Matérn covariance.
}
\details{
The function implements a two-step simulation procedure:
\enumerate{
\item Simulate the Gaussian random field u(s) using finite element methods
\item Generate point locations using acceptance-rejection sampling from the
intensity \eqn{\lambda(s) = exp(\beta + u(s))}{lambda(s) = exp(beta + u(s))}
}

The Gaussian field is characterized by the SPDE:
\eqn{(\kappa^2 - \Delta)^{\alpha/2} \tau u = \mathcal{W}}{(kappa^2 - Delta)^(alpha/2) tau u = W}
where \eqn{\kappa, \tau}{kappa, tau} are derived from the range and sigma parameters, and \eqn{\mathcal{W}}{W} is white noise.
}
\examples{
\dontrun{
# Create a metric graph and build mesh
graph <- metric_graph$new()
graph$build_mesh(h = 0.1)
graph$compute_fem()

# Simulate a single point pattern
lgcp_data <- graph_lgcp_sim(
  intercept = -1, 
  sigma = 0.5, 
  range = 2, 
  alpha = 2, 
  graph = graph
)

# Simulate multiple replicates
lgcp_replicates <- graph_lgcp_sim(
  n = 10,
  intercept = -1, 
  sigma = 0.5, 
  range = 2, 
  alpha = 2, 
  graph = graph
)

# Plot the simulated intensity
graph$plot_function(X = exp(lgcp_data$u), vertex_size = 0)
}

}
\seealso{
\code{\link{lgcp_graph}} for fitting LGCP models,
\code{\link{precompute_lgcp_graph}} for efficient model fitting
}
