% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/causalsim.R
\name{causalsim}
\alias{causalsim}
\title{Simulate a causal dataset with known ground truth}
\usage{
causalsim(
  n,
  effect = 1,
  propensity = "moderate",
  baseline = "moderate",
  sigma = 1,
  covariates = list(),
  n_confounders = 0L,
  n_effect_modifiers = 0L,
  n_noise = 0L,
  mc_draws = 10000L,
  seed = NULL
)
}
\arguments{
\item{n}{Positive integer. Sample size for each simulated dataset.}

\item{effect}{Numeric scalar or function. A scalar specifies a constant
(homogeneous) treatment effect; ATE = CATE everywhere. A function should
accept named arguments matching covariate names defined in the DGP and
return a numeric vector of individual-level causal effects (CATE).
See Details.}

\item{propensity}{Numeric scalar, preset string, or function. Treatment
assignment probability. A scalar (e.g. \code{0.5}) gives a constant propensity
(randomized trial). Preset strings \code{"low"}, \code{"moderate"}, \code{"high"} generate
a logistic propensity over confounders with coefficients 0.25, 0.5, and
1.0 respectively. A function follows the same named-argument convention as
\code{effect} and must return values in [0, 1]. Defaults to \code{"moderate"}.}

\item{baseline}{Numeric scalar, preset string, or function. Mean potential
outcome under control, \code{E[Y(0) | W]}. Preset strings follow the same
levels as \code{propensity} and apply a linear combination of confounders.
Defaults to \code{"moderate"}, so that confounders declared via \code{n_confounders}
(or \code{role = "confounder"}) enter both the treatment and outcome models and
therefore actually induce confounding bias. With no confounders present,
any preset baseline resolves to \code{0}. Set a numeric scalar (e.g. \code{0}) for a
constant baseline that ignores covariates.}

\item{sigma}{Positive numeric. Standard deviation of the outcome noise term.
Default \code{1}.}

\item{covariates}{Named list of \code{\link[=causalsim_covar]{causalsim_covar()}} objects (Option A /
explicit path).
Each name becomes the column name in generated data and the argument name
expected by \code{effect}, \code{propensity}, and \code{baseline} functions. Merged with
any auto-generated covariates; name collisions error.}

\item{n_confounders}{Non-negative integer. Standard normal confounders
auto-generated as \code{W} (single) or \verb{W1, W2, ...} (multiple).}

\item{n_effect_modifiers}{Non-negative integer. Auto-generates standard
normal effect modifiers as \code{V} or \verb{V1, V2, ...}.}

\item{n_noise}{Non-negative integer. Auto-generates standard normal noise
covariates as \code{X} or \verb{X1, X2, ...}.}

\item{mc_draws}{Positive integer. Monte Carlo draws for true ATE
approximation. Default \code{10000L}. Ignored for scalar \code{effect}.}

\item{seed}{Integer or \code{NULL}. Passed to \code{\link[=set.seed]{set.seed()}} before drawing.
Default \code{NULL}.}
}
\value{
A data frame with covariate columns, \code{A}, \code{Y}, \code{.tau}, and \code{.p}.
}
\description{
A convenience wrapper around \code{\link[=causalsim_dgp]{causalsim_dgp()}} and \code{\link[=causalsim_draw]{causalsim_draw()}}.
Defines a causal data generating process and returns one simulated dataset
in a single call.
}
\details{
The returned data frame includes all covariate columns, the treatment
indicator \code{A}, the outcome \code{Y}, and two ground-truth columns:

\describe{
\item{\code{.tau}}{Individual-level causal effect (CATE).}
\item{\code{.p}}{True propensity score.}
}

For full control over the DGP (multiple draws, grid evaluation, estimator
benchmarking), use \code{\link[=causalsim_dgp]{causalsim_dgp()}} and \code{\link[=causalsim_draw]{causalsim_draw()}} directly.
}
\examples{
# One confounder, constant effect of 2, moderate confounding
data <- causalsim(n = 500, n_confounders = 1, effect = 2, seed = 1L)
head(data)

# Heterogeneous effect with an explicit covariate spec
data2 <- causalsim(
  n = 500,
  covariates = list(
    W = causalsim_covar("normal", role = "confounder"),
    V = causalsim_covar("binary", role = "effect_modifier", prob = 0.4)
  ),
  effect = function(V) 2 + 1.5 * V,
  propensity = function(W) plogis(0.5 * W),
  seed = 42L
)
head(data2)

}
