% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simulate.R
\name{simulate_smoothbp}
\alias{simulate_smoothbp}
\title{Simulate data from the smooth change-point model}
\usage{
simulate_smoothbp(
  n_subj = 20L,
  n_obs = 8L,
  b0 = 5,
  b1 = -0.3,
  delta = 1.2,
  omega = 3,
  rho = 4,
  sigma = 0.4,
  sigma_u = 0.5,
  tau_range = c(0, 6),
  seed = NULL
)
}
\arguments{
\item{n_subj}{Number of subjects (groups).  Set to \code{1} and
\code{sigma_u = 0} for a single-group simulation.}

\item{n_obs}{Observations per subject.  May be a scalar (same for all
subjects) or a length-\code{n_subj} integer vector for unbalanced designs.}

\item{b0}{Overall intercept (conditional mean at \eqn{\tau = \omega_1}).}

\item{b1}{Pre-change-point slope (evaluated relative to \eqn{\omega_1}).}

\item{delta}{Change in slope at each change-point.  A numeric vector of
length \eqn{K}; a scalar is treated as \eqn{K = 1}.}

\item{omega}{Change-point location(s).  A numeric vector of length
\eqn{K}, in ascending order.  A scalar is treated as \eqn{K = 1}.}

\item{rho}{Sharpness of each transition.  A numeric vector of length
\eqn{K} (all values must be positive); a scalar is recycled to length
\eqn{K}.}

\item{sigma}{Residual standard deviation.}

\item{sigma_u}{Between-subject SD for random intercepts.  Set to \code{0}
to suppress random effects.  Default \code{0.5}.}

\item{tau_range}{Numeric vector of length 2 giving the range of the time
variable.  Observations are evenly spaced within this range for each
subject.  Default \code{c(0, 6)}.}

\item{seed}{Integer seed for reproducibility.  Sampled randomly if
\code{NULL} (default).}
}
\value{
A \code{data.frame} with columns:
\describe{
\item{\code{subject}}{Subject identifier (factor).}
\item{\code{tau}}{Time variable.}
\item{\code{mu}}{Noise-free conditional mean \eqn{\mu_{ij}}.}
\item{\code{y}}{Observed response.}
}
The attribute \code{"true_params"} is a named list containing the
data-generating values of \code{b0}, \code{b1}, \code{delta}, \code{omega},
\code{rho}, \code{sigma}, \code{sigma_u}, the vector of subject-level
deviations \code{u}, and the \code{seed} used.
}
\description{
Generates synthetic data from the model used by \code{\link{smoothbp}},
including optional between-subject random intercepts.  Supports any number
of breakpoints \eqn{K \geq 1}.  True parameter values are stored as the
\code{"true_params"} attribute so they can be compared against posterior
estimates.
}
\details{
The data-generating model for \eqn{K} breakpoints is:
\deqn{
  y_{ij} = (b_0 + u_j) + b_1 (\tau_{ij} - \omega_1)
           + \sum_{k=1}^{K} \delta_k \, d_{ijk} \, \text{logistic}(d_{ijk} \, \rho_k)
           + \varepsilon_{ij}
}
where \eqn{d_{ijk} = \tau_{ij} - \omega_k} and \eqn{\text{logistic}(\cdot)} is the
logistic function \eqn{\text{logistic}(x) = (1 + e^{-x})^{-1}}.  The pre-break slope \eqn{b_1} is centred at the first
change-point \eqn{\omega_1}, so \eqn{b_0} represents the conditional mean
at \eqn{\tau = \omega_1} (consistent with the fitted model).

For a single breakpoint (\eqn{K = 1}), scalar values of \code{omega},
\code{rho}, and \code{delta} are accepted for backward compatibility.
}
\examples{
# Single breakpoint (K = 1)
dat1 <- simulate_smoothbp(
  n_subj = 20, n_obs = 8,
  b0 = 5, b1 = -0.3, delta = 1.2,
  omega = 3, rho = 4, sigma = 0.4, sigma_u = 0.5,
  seed = 42
)
head(dat1)
attr(dat1, "true_params")

# Two breakpoints (K = 2)
dat2 <- simulate_smoothbp(
  n_subj = 20, n_obs = 12,
  b0 = 5, b1 = -0.3,
  delta = c(1.2, -0.8),
  omega = c(2, 4),
  rho   = c(4, 4),
  sigma = 0.4, sigma_u = 0.5,
  seed = 42
)
head(dat2)

}
