% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scm_design.R
\name{scm_design}
\alias{scm_design}
\title{Experimental Synthetic Control Design}
\usage{
scm_design(
  data,
  outcome,
  unit,
  time,
  T0,
  T_fit = NULL,
  m_min = 1L,
  m_max = 1L,
  f = NULL,
  predictors = NULL,
  design = c("base", "weakly_targeted", "unit_level"),
  beta = 1,
  xi = 1,
  alpha = 0.05,
  normalize = TRUE,
  max_subsets = 100000L
)
}
\arguments{
\item{data}{Long-format data frame (one row per unit–time).}

\item{outcome}{Name of the outcome column.}

\item{unit}{Name of the unit identifier column.}

\item{time}{Name of the time identifier column.}

\item{T0}{Last pre-experimental period (a value present in the time
column).  Periods after \code{T0} are the experimental periods.}

\item{T_fit}{Number of fitting periods, counted from the \strong{start} of
the pre-experimental phase.  Defaults to \code{NULL}, which uses all
pre-experimental periods for fitting (no blank periods; inference
disabled).  When \code{T_fit} is smaller than the total number of
pre-experimental periods, the remaining periods become blank periods used
for inference.}

\item{m_min}{Minimum number of units assigned to treatment (default 1).}

\item{m_max}{Maximum number of units assigned to treatment (default 1).}

\item{f}{Named numeric vector of population weights \eqn{f_j}.
Defaults to uniform weights \eqn{1/J}.  Will be normalised to sum to 1.}

\item{predictors}{A \code{list()} of \code{\link[=pred]{pred()}} specifications that define the
predictor matrix \eqn{X_j}.  Defaults to \code{NULL}, which uses all
fitting-period outcome values as predictors.}

\item{design}{Design formulation: \code{"base"} (default), \code{"weakly_targeted"},
or \code{"unit_level"}.}

\item{beta}{Trade-off parameter \eqn{\beta > 0} for the Weakly
targeted design (default 1).}

\item{xi}{Trade-off parameter \eqn{\xi > 0} for the Unit-level
design (default 1).}

\item{alpha}{Significance level for confidence intervals (default 0.05).}

\item{normalize}{If \code{TRUE} (default), each row of the predictor matrix is
divided by its cross-unit standard deviation before optimisation, so
predictors measured on different scales contribute equally.}

\item{max_subsets}{Maximum number of treatment-set candidates to evaluate
before switching to random sampling (default 100 000).}
}
\value{
An object of class \code{"scm_design"} with components:
\itemize{
\item \code{treated_units}: unit identifiers selected for treatment
\item \code{control_units}: unit identifiers in the control pool
\item \code{w}: J-length weight vector for the synthetic treated unit (sums to 1)
\item \code{v}: J-length weight vector for the synthetic control unit (sums to 1)
\item \code{tau_hat}: estimated treatment effects for each experimental period
\item \code{p_value}: permutation p-value (NA when blank periods are unavailable)
\item \code{ci_lower}, \code{ci_upper}: per-period split-conformal confidence interval
\item \code{Y_synth_tr}, \code{Y_synth_co}: synthetic treated/control series (all periods)
\item \code{estimate}: ATT (mean of \code{tau_hat})
}
}
\description{
Selects which units to assign to the treatment arm (and which to the control
arm) in a planned experiment, following Abadie and Zhao (2026).  Both sets
of units are chosen by minimising the distance between their weighted-average
predictor vectors and the population-average predictor vector \eqn{\bar{X}},
so the resulting estimates are less susceptible to post-randomisation bias
than pure random assignment.
}
\details{
Three design formulations are available:
\itemize{
\item \strong{\code{"base"}} (eq. 7): both the synthetic treated and the synthetic control
independently target the population average \eqn{\bar{X}}.
\item \strong{\code{"weakly_targeted"}} (eq. 9): the synthetic treated targets
\eqn{\bar{X}}; the synthetic control targets the synthetic treated predictor
vector (controlled by \code{beta}).
\item \strong{\code{"unit_level"}} (eq. 10): each treated unit gets its own synthetic
control; the aggregate control weight is a convex combination (controlled
by \code{xi}).
}

Inference uses "blank periods" — pre-experimental periods whose outcomes were
\emph{not} used to estimate the weights.  Set \code{T_fit} strictly smaller than the
number of pre-experimental periods to enable the permutation test and split-
conformal confidence intervals from Section 3 of Abadie and Zhao (2026).
}
\references{
Abadie, A. and Zhao, J. (2026). "Synthetic Controls for
Experimental Design." MIT Working Paper.
}
