% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scm_fit.R
\name{scm_fit}
\alias{scm_fit}
\title{Fit a Synthetic Control Method Model}
\usage{
scm_fit(
  formula,
  data,
  method = c("scm", "sdid", "gsc", "mc", "tasc", "si"),
  predictors = NULL,
  covariates = NULL,
  v_selection = c("insample", "oos"),
  donor_mspe_threshold = Inf,
  lambda_pen = NULL,
  v_optim = c("coord_descent", "auto", "bfgs"),
  ...
)
}
\arguments{
\item{formula}{A \code{Formula} object, e.g. \code{y ~ D | unit + time}.}

\item{data}{A \code{data.frame} in \strong{long} format (one row per unit-time).}

\item{method}{One of \code{"scm"}, \code{"sdid"}, \code{"gsc"}, \code{"mc"}, \code{"tasc"}, \code{"si"}.}

\item{predictors}{A \code{list()} of \code{\link[=pred]{pred()}} specifications that define the
predictor matrix for SCM (see Abadie et al. 2010, S.2.3). Each \code{\link[=pred]{pred()}}
entry aggregates one or more variables over a time window. Pass \code{NULL}
(default) to use all pre-treatment outcome periods as predictors.
Applies to \code{method = "scm"} only.}

\item{covariates}{An optional named \code{list} of additional time-varying
covariates to partial out before estimation. Each element is a character
string naming a column in \code{data}. Supported for \code{method = "sdid"},
\code{"scm"}, and \code{"gsc"}.}

\item{v_selection}{V matrix selection method for \code{method = "scm"}.
\code{"insample"} (default) follows Abadie et al. (2010): V is chosen by
minimising in-sample pre-treatment MSPE. \code{"oos"} follows Abadie (2021)
S.3.2: the pre-treatment window is split in half; V is selected to minimise
MSPE on the validation half, then W is refit on the full window.}

\item{donor_mspe_threshold}{Donor pool filtering threshold (Abadie 2021 S.4).
For \code{method = "scm"} only. Each donor's individual pre-treatment MSPE
(using that donor alone as the counterfactual) is divided by the minimum
such MSPE across all donors. Donors whose ratio exceeds this threshold are
excluded from estimation. \code{Inf} (default) disables filtering.}

\item{lambda_pen}{Penalised SCM parameter (Abadie & L'Hour 2021, JASA).
For \code{method = "scm"} only. \code{NULL} (default) runs standard unpenalised SCM.
\code{"auto"} selects the penalty via out-of-sample pre-treatment MSPE on the
same validation window as \code{v_selection = "oos"}. A non-negative number
uses that value directly.}

\item{v_optim}{Outer V-optimisation method for \code{method = "scm"}.
\code{"coord_descent"} (default) uses the existing C++ coordinate descent with
11-point grid search -- fastest when \code{k = T_pre} is large (outcomes-only).
\code{"bfgs"} uses R's L-BFGS-B, which requires only O(k^2) inner QP calls and
is faster when \code{k} is small (e.g. external predictors with k <= 15).
\code{"auto"} selects \code{"bfgs"} when \code{k <= 15}, otherwise \code{"coord_descent"}.}

\item{...}{Additional arguments forwarded to the specific method
(e.g. \code{r}, \code{lambda}, \code{zeta2}).}
}
\value{
An object of classes \code{c("coresynth_<method>", "coresynth")}.
All methods return at minimum:
\itemize{
\item \code{method}: estimator name
\item \code{estimate}: average treatment effect (ATT)
\item \code{times}: time index vector
\item \code{T_pre}: number of pre-treatment periods
\item \code{Y_treat}: treated unit outcome series
\item \code{gap}: treatment effect series (Y_treat - counterfactual)
}
}
\description{
Unified formula interface for Synthetic Control and related causal
inference methods.  The formula syntax is:
}
\details{
\code{outcome ~ treatment | unit_id + time_id}
}
\examples{
# Synthetic balanced panel: 10 units over 20 periods, unit 1 treated
# after period 15.
set.seed(1)
panel <- expand.grid(unit = 1:10, year = 1:20)
panel$treated <- as.integer(panel$unit == 1 & panel$year > 15)
panel$gdp <- panel$unit + 0.5 * panel$year +
  rnorm(nrow(panel)) + 3 * panel$treated

fit <- scm_fit(gdp ~ treated | unit + year, data = panel, method = "sdid")
summary(fit)

\donttest{
# Visualise the estimated gap (requires ggplot2)
plot(fit, type = "gap")
}
}
