% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simulate.R
\name{simulate_mtl}
\alias{simulate_mtl}
\title{Simulate Multi-Task Data with Time-Varying Effects}
\usage{
simulate_mtl(
  n = 200,
  p = 30,
  n_signals = 5,
  n_continuous = 1,
  thresholds = c(4, 6, 10, 15),
  mode = c("survival", "regression", "classification"),
  noise_sd = 1,
  censoring_max = 25,
  baseline_hazard = 0.05,
  effect_strength = 0.8,
  treatment_effect = -0.3,
  seed = NULL
)
}
\arguments{
\item{n}{Number of patients. Default: \code{200}.}

\item{p}{Number of features excluding the treatment column.
Default: \code{30}.}

\item{n_signals}{Number of features with true non-zero effects.
Default: \code{5}. Must be \code{<= p}.}

\item{n_continuous}{Number of continuous features (placed first
in the feature matrix). Default: \code{1}. Remaining features
are binary.}

\item{thresholds}{Numeric vector of time thresholds defining the
task structure. Default: \code{c(4, 6, 10, 15)}.}

\item{mode}{Character; the response type to generate. One of
\code{"survival"} (default), \code{"regression"}, or
\code{"classification"}. The feature matrix and ground-truth
coefficients are generated identically across modes; only the
response differs:
\describe{
  \item{survival}{piecewise-exponential \code{SurvTime}/\code{Event}
    (the historical behaviour).}
  \item{regression}{\code{Y = X \%*\% beta + N(0, noise_sd^2)},
    returned as the \code{n x length(thresholds)} matrix \code{Y}.}
  \item{classification}{binary labels in \eqn{\{-1, +1\}} sampled
    from \eqn{P(Y = +1) = 1 / (1 + e^{-X beta})}, returned as
    \code{Y}. This matches the label encoding \code{orthoMTL}
    optimises with \code{logistic = TRUE}.}
}}

\item{noise_sd}{Standard deviation of the Gaussian noise added in
\code{mode = "regression"}. Ignored otherwise. Default: \code{1}.}

\item{censoring_max}{Maximum censoring time. Censoring times are
drawn from \code{Unif(0, censoring_max)}. Default: \code{25}.}

\item{baseline_hazard}{Baseline hazard rate per interval. Default:
\code{0.05}.}

\item{effect_strength}{Multiplier controlling the magnitude of
feature effects. Default: \code{0.5}.}

\item{treatment_effect}{Effect of treatment on the log-hazard
(negative = protective). Default: \code{-0.3}.}

\item{seed}{Optional random seed for reproducibility. Default:
\code{NULL} (no seed is set; the ambient RNG state is used as-is).
Pass an integer to make the simulated data reproducible.}
}
\value{
An object of class \code{"simulated_mtl"} containing:
  \describe{
    \item{mode}{The response type generated.}
    \item{Y}{For \code{mode = "regression"} / \code{"classification"},
      the \code{n x length(thresholds)} response matrix. \code{NULL}
      in survival mode (use \code{SurvTime}/\code{Event} instead).}
    \item{SurvTime, Event}{Survival mode only (\code{NULL} otherwise):
      observed times and event indicators.}
    \item{X}{Numeric matrix of dimensions \code{n x (p + 1)}.
      Columns include \code{n_continuous} continuous features
      (standard normal), \code{p - n_continuous} binary features
      (prevalences drawn from \code{Beta(2, 10)}), and a
      \code{treatment} column (balanced 1:1).}
    \item{SurvTime}{Numeric vector of observed survival times.}
    \item{Event}{Binary vector: \code{1} = event observed,
      \code{0} = censored.}
    \item{treatment}{Binary vector (also present as last column
      of \code{X}).}
    \item{feature_names}{Character vector of column names of
      \code{X}.}
    \item{ground_truth}{A list containing:
      \describe{
        \item{coefficients}{Matrix of true coefficients with
          dimensions \code{(p + 1) x length(thresholds)}.}
        \item{signal_features}{Names of features with non-zero
          effects.}
        \item{null_features}{Names of features with zero effects.}
        \item{effect_types}{Named character vector mapping signal
          features to their temporal effect template.}
        \item{thresholds}{The thresholds used.}
        \item{baseline_hazard}{The baseline hazard used.}
      }
    }
    \item{n, p, n_signals, n_continuous, thresholds, seed}{Input
      parameters stored for reference.}
    \item{call}{The matched function call.}
  }
}
\description{
Generates a realistic simulated dataset with binary and continuous
features and a known ground-truth coefficient structure. The
\code{mode} argument selects the response type: piecewise-exponential
\strong{survival} times (default), multi-task \strong{regression}
targets, or multi-task binary \strong{classification} labels. Designed
for demonstrating and testing \code{\link{orthoMTL}}.
}
\details{
\strong{Feature structure:}
\itemize{
  \item Continuous features are drawn from \code{N(0, 1)}.
  \item Binary features have prevalences drawn from \code{Beta(2, 10)},
    producing a realistic range (~5-30\%).
  \item Treatment is balanced 1:1 via random assignment.
}

\strong{Effect templates:}
Each signal feature is assigned one of five temporal patterns:
\itemize{
  \item \code{"early"}: strong effect at early thresholds, fading to
    zero at late.
  \item \code{"late"}: zero at early thresholds, emerging at late.
  \item \code{"constant"}: equal effect across all thresholds
    (detectable by standard Cox models).
  \item \code{"increasing"}: effect grows over time.
  \item \code{"decreasing"}: effect shrinks over time.
}
Templates are assigned cyclically across signal features with
random sign (risk-increasing or protective).

\strong{Survival time generation:}
Uses a piecewise-exponential model where the hazard in each
interval is
\code{h_k(i) = baseline_hazard * exp(X[i, ] \%*\% beta[, k])}.
Patients progress through intervals sequentially; an event
occurs when the simulated time within an interval is shorter
than the interval width.

\strong{Censoring:}
Independent of event times. \code{C ~ Unif(0, censoring_max)}.
Observed time = \code{min(T, C)}, event indicator = \code{T <= C}.
}
\examples{
# Generate simulated data
sim <- simulate_mtl(n = 100, p = 20, n_signals = 4, seed = 42)
sim

# Inspect ground truth
sim$ground_truth$signal_features
sim$ground_truth$effect_types
sim$ground_truth$coefficients[sim$ground_truth$signal_features, ]

# Use in orthoMTL workflow
\donttest{
thresholds <- c(4, 6, 10, 15)
Y <- create_longitudinal_labels(sim$SurvTime, sim$Event, thresholds)
W <- create_indicator_matrix(Y)
K <- create_constraint_matrix(length(thresholds))

fit <- orthoMTL(sim$X, Y, lambda = 1e-3, K = K,
                survival = TRUE, censored.mat = W)
summary(fit)
}
}
\seealso{
\code{\link{create_longitudinal_labels}},
  \code{\link{orthoMTL}}
}
