% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/causalsim_dgp.R
\name{causalsim_dgp}
\alias{causalsim_dgp}
\title{Create a causal data generating process}
\usage{
causalsim_dgp(
  n,
  effect = 1,
  propensity = "moderate",
  baseline = "moderate",
  sigma = 1,
  covariates = list(),
  n_confounders = 0L,
  n_effect_modifiers = 0L,
  n_noise = 0L,
  mc_draws = 10000L
)
}
\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}.}
}
\value{
An S3 object of class \code{causalsim_dgp} with components:
\describe{
\item{\code{n}}{Sample size (integer)}
\item{\code{covar_spec}}{Named list of \code{\link[=causalsim_covar]{causalsim_covar()}} objects}
\item{\code{effect_fn}}{Normalized effect function}
\item{\code{propensity_fn}}{Normalized propensity function}
\item{\code{baseline_fn}}{Normalized baseline function}
\item{\code{sigma}}{Outcome noise standard deviation}
\item{\code{true_ate}}{True ATE: exact for scalar, MC approximation otherwise}
\item{\code{heterogeneous}}{Logical; \code{TRUE} if \code{effect} was a function}
\item{\code{mc_draws}}{Monte Carlo draws used (integer)}
}
}
\description{
Defines a causal DGP with known ground truth. Covariates can be specified
via shorthand count arguments (Option B), an explicit named list of
\code{\link[=causalsim_covar]{causalsim_covar()}} objects (Option A), or both combined.
}
\details{
\subsection{Structural model}{

\if{html}{\out{<div class="sourceCode">}}\preformatted{W ~ covariate_spec
A ~ Bernoulli(propensity(W))
Y  = baseline(W) + effect(W) * A + N(0, sigma^2)
}\if{html}{\out{</div>}}

\code{A} is used for treatment throughout to avoid collision with R's built-in
\code{T} alias.
}

\subsection{Function calling convention}{

The \code{effect}, \code{propensity}, and \code{baseline} functions are called with named
arguments matching covariate names, not a data frame. Write:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{effect = function(W) 2 + 1.5 * W
propensity = function(W1, W2) plogis(0.3 * W1 + 0.5 * W2)
}\if{html}{\out{</div>}}

Every argument name is validated against the DGP's covariate spec at
construction time, so mismatches surface immediately rather than at draw
time. The propensity function is additionally evaluated on a small test draw
to confirm it returns values in [0, 1].
}

\subsection{True ATE}{

For scalar \code{effect} the true ATE is exact. For function \code{effect} it is
approximated via Monte Carlo over \code{mc_draws} draws from the covariate
distribution.
}
}
\examples{
# Minimal: one confounder, constant effect, moderate confounding
dgp <- causalsim_dgp(n = 500, n_confounders = 1, effect = 2)
dgp

# Heterogeneous effect, explicit covariate spec
dgp2 <- causalsim_dgp(
  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),
  baseline = function(W) 1.5 * W
)

# Mixed: shorthand confounders + explicit noise covariate + RCT propensity
dgp3 <- causalsim_dgp(
  n = 1000,
  n_confounders = 2,
  covariates = list(X = causalsim_covar("normal", role = "noise")),
  effect = 1,
  propensity = 0.5
)

}
