% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/causalsim_eval_grid.R
\name{causalsim_eval_grid}
\alias{causalsim_eval_grid}
\title{Evaluate an estimator across a parameter grid}
\usage{
causalsim_eval_grid(
  dgp,
  estimator,
  vary,
  reps = 200L,
  metrics = c("bias", "rmse", "coverage", "power"),
  seed = NULL,
  verbose = FALSE
)
}
\arguments{
\item{dgp}{A \code{causalsim_dgp} object. Provides fixed parameter values for
all dimensions not listed in \code{vary}.}

\item{estimator}{A function as accepted by \code{\link[=causalsim_eval]{causalsim_eval()}}.}

\item{vary}{Named list of atomic vectors. Each name must be a valid
\code{\link[=causalsim_dgp]{causalsim_dgp()}} argument (except \code{covariates}, which cannot be
varied atomically). Each vector supplies the values to try for that
dimension. The full grid is the Cartesian product of all dimensions.}

\item{reps}{Positive integer. Replications per grid cell. Default \code{200L}.}

\item{metrics}{Character vector. Passed to \code{\link[=causalsim_eval]{causalsim_eval()}}.}

\item{seed}{Integer or \code{NULL}. Passed to \code{\link[=set.seed]{set.seed()}} before the first
cell. The same RNG stream continues across cells, so results are
jointly reproducible. Default \code{NULL}.}

\item{verbose}{Logical. If \code{TRUE}, prints a progress message before each
cell. Default \code{FALSE}.}
}
\value{
An S3 object of class \code{causalsim_eval_grid} with components:
\describe{
\item{\code{results}}{Tidy data frame: one row per (cell, metric).
Columns: grid parameter names, \code{metric}, \code{value}, \code{se}.}
\item{\code{grid}}{Data frame of grid cells, one row per cell.}
\item{\code{vary}}{Character vector of varied parameter names.}
\item{\code{reps}}{Replications per cell.}
\item{\code{metrics}}{Metrics evaluated.}
}
}
\description{
Runs \code{\link[=causalsim_eval]{causalsim_eval()}} over the Cartesian product of one or more DGP
parameter values, returning a tidy data frame of performance metrics for
every cell. Designed for studying how estimator behavior changes with
sample size, confounding strength, effect size, or noise level.
}
\details{
\subsection{How it works}{

For each cell in \code{expand.grid(vary)}, \code{causalsim_eval_grid()} takes \code{dgp}'s
stored original parameters, overrides the cell's values, reconstructs a
new \code{\link[=causalsim_dgp]{causalsim_dgp()}}, runs \code{\link[=causalsim_eval]{causalsim_eval()}}, and tags the resulting
metrics with the cell's parameter values.
}

\subsection{Constraints on \code{vary}}{

Elements of \code{vary} must be atomic vectors (character, numeric, integer).
Functions cannot be varied via this interface. \code{covariates} (a list of
\code{\link[=causalsim_covar]{causalsim_covar()}} objects) is excluded. For complex covariate variation,
construct DGPs manually and use \code{\link[=causalsim_eval]{causalsim_eval()}} directly.

Note that varying \code{n_confounders} from 1 to 2 changes auto-generated
covariate names from \code{W} to \verb{W1, W2}. If the base DGP's \code{effect} function
references \code{W}, the reconstructed DGP will error at construction time.
Design the base DGP accordingly.
}
}
\examples{
dgp <- causalsim_dgp(n = 500, n_confounders = 1, effect = 2,
                     propensity = 0.5)

ols_estimator <- function(data) {
  fit <- lm(Y ~ A + W, data = data)
  est <- coef(fit)[["A"]]
  se  <- sqrt(vcov(fit)["A", "A"])
  c(estimate = est, ci_lower = est - 1.96 * se, ci_upper = est + 1.96 * se)
}

\donttest{
grid_result <- causalsim_eval_grid(
  dgp = dgp,
  estimator = ols_estimator,
  vary = list(n = c(250L, 500L, 1000L)),
  reps = 50L,
  seed = 1L
)
grid_result
}

}
