Package 'SCMs'

Description

Add fitted values, residuals, and other observation-level statistics to the original data used in synthetic control estimation.

Usage

## S3 method for class 'scest'
augment(x, data = NULL, ...)

Arguments

Value

A data.table with original data plus:

• .fitted - Numeric. Fitted values from synthetic control

• .resid - Numeric. Residuals (actual - fitted)

• .period_type - Character. "pre" or "post" treatment

• .is_treated - Logical. Whether observation is from treated unit

Examples

toy <- data.frame(
  unit = rep(c("treated", "donor1", "donor2"), each = 6),
  year = rep(1:6, 3),
  y = c(10, 11, 12, 14, 15, 16,
        9, 10, 11, 12, 13, 14,
        11, 12, 13, 13, 14, 15)
)
sc_obj <- scdata(
  df = toy,
  id.var = "unit",
  time.var = "year",
  outcome.var = "y",
  period.pre = 1:4,
  period.post = 5:6,
  unit.tr = "treated",
  unit.co = c("donor1", "donor2"),
  covagg = list(list(var = "outcome_var", partition_periods = list(type = "by_period")))
)
fit <- scest(sc_obj, w.constr = list(name = "simplex"))
generics::augment(fit)

Description

Solve unconstrained quadratic programming problem using clarabel

Usage

b.est.clarabel.ols(A, Z, C = NULL, J, KM, w.constr, V)

Arguments

Value

Numeric vector of weights

Description

Solve simplex-constrained QP using clarabel (sum to 1, non-negative)

Usage

b.est.clarabel.simplex(A, Z, C = NULL, J, KM, w.constr, V)

Arguments

Value

Numeric vector of weights

Description

Dispatch to appropriate clarabel constraint-specific function

Usage

b.est.clarabel.unified(A, Z, C = NULL, J, KM, w.constr, V)

Arguments

Value

Numeric vector of weights

Description

Solve W optimization using CVXR (original implementation)

Usage

b.est.cvxr.fallback(A, Z, C = NULL, J, KM, w.constr, V, CVXR.solver)

Arguments

Value

Numeric vector of weights

Description

Implements bootstrap inference by: 1) Enforcing null hypothesis by subtracting actual treatment effect from post-treatment values, 2) Bootstrap resampling at unit level, 3) Re-estimating SCM on bootstrapped samples, 4) Computing p-values from bootstrap distribution

Usage

bootstrap_null_inference(
  sc.pred,
  dataset,
  n_bootstrap = 1000,
  cores = 1,
  verbose = FALSE,
  seed = NULL
)

Arguments

Details

Bootstrap Null Hypothesis Inference for Synthetic Control

Value

List containing bootstrap results and p-values

Description

Calculates significance measures following Abadie et al. (2010) German reunification paper. Computes post/pre RMSPE ratios, treatment effects, normalized treatment effects, and their rank-based p-values: one-sided in expected_direction, or two-sided (ranked by |statistic|) when expected_direction = "two_sided". The RMSPE ratio is always one-sided.

Usage

calculate_abadie_significance(
  taus_result,
  rmse_result,
  rmspe_threshold = 0,
  expected_direction = "two_sided"
)

Arguments

Details

Calculate Abadie-style Significance Measures

Value

List containing Abadie significance measures for all test statistics

Description

Calculates empirical bootstrap p-values by determining where the actual treatment effect ranks within the bootstrap distribution. This is the standard approach for bootstrap hypothesis testing.

Usage

calculate_bootstrap_pvalues(bootstrap_effects, actual_effects, verbose = FALSE)

Arguments

Details

The p-values are calculated as follows:

• One-tailed positive: P(bootstrap >= actual) = (n - rank) / n

• One-tailed negative: P(bootstrap <= actual) = (rank + 1) / n

• Two-tailed: 2 * min(positive, negative), capped at 1.0

Value

Data.table with p-values and rank information

Description

Calculates curve-level statistics and p-values on filtered specification-curve results using placebo-in-space comparison.

Usage

calculate_spec_curve_pvalues_filtered(
  filtered_results,
  curve_stat = c("abs_median_tau", "median_abs_tau", "consistency_ratio"),
  weighting = c("none", "pre_rmspe_percentile"),
  two_sided = TRUE,
  expected_direction = "two_sided",
  grid_policy = "strict",
  min_placebos = 1L,
  min_specs = 2L
)

Arguments

Details

Calculate Specification Curve P-values on Filtered Data

For each unit and specification, this function uses the signed per-spec effect summary tau_s. Two-sided p-values always compare absolute tails against placebo-unit curve statistics:

$p = (1 + \#\{|T_j| \ge |T_{treated}|\})/(J+1).$

One-sided p-values (two_sided = FALSE) require a signed statistic and count placebos at least as extreme in expected_direction, e.g. for "negative"

$p = (1 + \#\{T_j \le T_{treated}\})/(J+1).$

The supported curve statistics are:

• median_tau: $\mathrm{median}_s(\tau_s)$ (signed)

• abs_median_tau: $|\mathrm{median}_s(\tau_s)|$

• median_abs_tau: $\mathrm{median}_s(|\tau_s|)$

• consistency_ratio: $|\sum_s \tau_s| / \sum_s |\tau_s|$

For weighted variants, pre-RMSPE-percentile weights are defined within unit as $w_s = 1 - rank(\mathrm{RMSPE}^{pre}_s)/(S+1)$ and applied directly to the statistic computation.

Value

List with:

• treated_summary: Treated-unit curve statistics and p-values.

• stats_by_unit: Curve statistics for treated and placebo units.

• attrition_report: Unit/spec retention summary under grid_policy.

Description

The coef method for synthetic control prediction fitted objects.

Usage

## S3 method for class 'scest'
coef(object, ...)

Arguments

Value

No return value, called to show scest constructed weights.

Author(s)

Matias Cattaneo, Princeton University. [email protected].

Yingjie Feng, Tsinghua University. [email protected].

Filippo Palomba, Princeton University (maintainer). [email protected].

Rocio Titiunik, Princeton University. [email protected].

See Also

scest for synthetic control prediction.

Supported methods: print.scest, summary.scest, coef.scest.

Description

Creates standardized configuration objects for running specification curve analysis across multiple datasets.

Usage

create_analysis_config(
  analysis_type = c("homicide", "ois"),
  custom_params = list()
)

Arguments

Details

Create Analysis Configuration

Value

List containing configuration parameters for the specified analysis type.

Examples

# Create homicide analysis configuration
homicide_config <- create_analysis_config("homicide")

# Create OIS analysis configuration with custom parameters
ois_config <- create_analysis_config("ois", 
  custom_params = list(treated_period = 2021))

Description

Create Bootstrap Dataset by Unit-level Resampling

Usage

create_bootstrap_dataset(
  dataset_null,
  bootstrap_units,
  col_name_unit,
  treated_unit
)

Arguments

Value

Bootstrap dataset

Description

This function prepares a dataset for use with the Synthetic Control Method (SCM) by formatting and standardizing the input data.

Usage

create_scm_dataset(
  dataset,
  outcome,
  covagg,
  col_name_unit_name,
  name_treated_unit,
  col_name_period,
  treated_period,
  min_period,
  end_period,
  constant = FALSE
)

Arguments

Value

A list containing the prepared data for SCM analysis.

Examples

toy <- data.frame(
  unit = rep(c("treated", "donor1", "donor2"), each = 6),
  year = rep(1:6, 3),
  y = c(10, 11, 12, 14, 15, 16,
        9, 10, 11, 12, 13, 14,
        11, 12, 13, 13, 14, 15)
)
scm_data <- create_scm_dataset(
  dataset = toy,
  outcome = "y",
  covagg = list(
    list(var = "outcome_var", partition_periods = list(type = "by_period"))
  ),
  col_name_unit_name = "unit",
  name_treated_unit = "treated",
  col_name_period = "year",
  treated_period = 5,
  min_period = 1,
  end_period = 6
)
inherits(scm_data, "scdata")

Description

Creates configuration for XGBoost analysis that works directly with long format data from spec_curve().

Usage

create_xgboost_config(
  dataset_name,
  treated_unit_name,
  outcome_filter = NULL,
  spec_features = c("outcome_model", "const", "fw", "feat", "data_sample"),
  treated_unit_only = TRUE,
  tune_xgboost = NULL,
  xgboost_grid = NULL,
  xgboost_cv_folds = 5,
  xgboost_params = NULL
)

Arguments

Value

List containing configuration parameters.

Examples

xgb_cfg <- create_xgboost_config(
  dataset_name = "toy",
  treated_unit_name = "treated",
  outcome_filter = "outcome",
  spec_features = c("feat", "outcome_model", "const", "fw", "data_sample")
)

Description

Enforce Null Hypothesis by Subtracting Treatment Effects

Usage

enforce_null_hypothesis(dataset, sc.pred, actual_effects, verbose = FALSE)

Arguments

Value

Dataset with null hypothesis enforced

Description

This function processes and estimates a Synthetic Control Model (SCM) based on the provided dataset and parameters.

Usage

estimate_sc(
  dataset,
  outcome,
  covagg,
  col_name_unit_name,
  name_treated_unit,
  col_name_period,
  treated_period,
  min_period,
  end_period,
  outcome_models = c("none", "ols", "ridge", "lasso", "augsynth"),
  feature_weights = "uniform",
  w.constr = NULL,
  V = "separate",
  V.mat = NULL,
  solver = "ECOS",
  constant = FALSE
)

Arguments

Value

A list of class "scm_estimate" containing estimated SCM results and input parameters.

Examples

toy <- data.frame(
  unit = rep(c("treated", "donor1", "donor2"), each = 6),
  year = rep(1:6, 3),
  y = c(10, 11, 12, 14, 15, 16,
        9, 10, 11, 12, 13, 14,
        11, 12, 13, 13, 14, 15)
)
fit <- estimate_sc(
  dataset = toy,
  outcome = "y",
  covagg = list(
    list(var = "outcome_var", partition_periods = list(type = "by_period"))
  ),
  col_name_unit_name = "unit",
  name_treated_unit = "treated",
  col_name_period = "year",
  treated_period = 5,
  min_period = 1,
  end_period = 6,
  outcome_models = "none"
)
names(fit)

Description

Provides a formula interface for synthetic control methods, similar to lm() and other standard R modeling functions. This makes the package more accessible to users familiar with standard R model syntax while maintaining compatibility with data.table workflows.

Details

Formula Interface for Synthetic Control Methods

Description

Extract model-level fit statistics and metadata from synthetic control estimation results in a single-row data.table.

Usage

## S3 method for class 'scest'
glance(x, ...)

Arguments

Value

A single-row data.table with columns:

• n_donors - Integer. Number of donor units

• n_pre_periods - Integer. Number of pre-treatment periods

• n_post_periods - Integer. Number of post-treatment periods

• rmse_pre - Numeric. Root mean squared error in pre-treatment fit

• rmse_post - Numeric. Root mean squared error in post-treatment prediction

• constraint_type - Character. Type of weight constraint used

• feature_weighting - Character. Feature weighting method used

• n_active_donors - Integer. Number of donors with meaningful weights

• max_weight - Numeric. Largest donor weight

• herfindahl_index - Numeric. Concentration measure of weights

• has_constant - Logical. Whether constant term was included

Examples

toy <- data.frame(
  unit = rep(c("treated", "donor1", "donor2"), each = 6),
  year = rep(1:6, 3),
  y = c(10, 11, 12, 14, 15, 16,
        9, 10, 11, 12, 13, 14,
        11, 12, 13, 13, 14, 15)
)
sc_obj <- scdata(
  df = toy,
  id.var = "unit",
  time.var = "year",
  outcome.var = "y",
  period.pre = 1:4,
  period.post = 5:6,
  unit.tr = "treated",
  unit.co = c("donor1", "donor2"),
  covagg = list(list(var = "outcome_var", partition_periods = list(type = "by_period")))
)
fit <- scest(sc_obj, w.constr = list(name = "simplex"))
generics::glance(fit)

Description

Performs placebo inference by estimating synthetic control for each control unit and computing three test statistics: post/pre RMSE ratio, treatment effect, and normalized treatment effect. P-values are one-sided in expected_direction, or two-sided (ranked by |statistic|) when expected_direction = "two_sided". The RMSPE ratio is always one-sided.

Usage

inference_placebo(
  sc.pred,
  dataset,
  cores,
  verbose,
  expected_direction = "two_sided"
)

Arguments

Details

Placebo Inference for Synthetic Control Method

Value

List containing:

• taus: Treatment effects for all units

• rmse: RMSE values for all units

• abadie_significance: List with three elements:

  • rmse_ratio: Post/pre RMSE ratio test statistic and p-values

  • treatment_effect: Treatment effect test statistic and p-values

  • normalized_te: Normalized treatment effect test statistic and p-values

Description

Wrapper around inference_placebo for rank-based placebo inference.

Usage

inference_sc(
  sc.pred,
  dataset,
  cores = 1,
  verbose = TRUE,
  expected_direction = "two_sided"
)

Arguments

Value

A list with data, est.results, inference.results, rmse, and abadie_significance.

Examples

set.seed(1)
toy <- expand.grid(unit = c("treated", "donor1", "donor2", "donor3"), year = 1:10,
                   stringsAsFactors = FALSE)
toy$y <- 50 + 0.8 * toy$year + ifelse(toy$unit == "treated" & toy$year >= 7, 3, 0) +
  rnorm(nrow(toy), 0, 0.5)
sc_fit <- estimate_sc(
  dataset = toy,
  outcome = "y",
  covagg = list(
    list(var = "outcome_var", partition_periods = list(type = "by_period"))
  ),
  col_name_unit_name = "unit",
  name_treated_unit = "treated",
  col_name_period = "year",
  treated_period = 7,
  min_period = 1,
  end_period = 10,
  outcome_models = "none"
)
inf <- inference_sc(sc_fit, toy, cores = 1, verbose = FALSE)
names(inf)

Description

Perform Bootstrap Inference

Usage

perform_bootstrap_inference(
  dataset_null,
  sc.pred,
  actual_effects,
  n_bootstrap,
  cores,
  verbose
)

Arguments

Value

List with bootstrap effects and estimates

Description

Creates specification curve plots directly from long format data with integrated SHAP analysis and flexible filtering capabilities. Key features:

• Internal SHAP computation using XGBoost (automatic when show_shap=TRUE)

• Specification filtering BEFORE SHAP computation and p-value calculation

• Perfect alignment between SHAP values and specifications via full_spec_id

• FAIL HARD error handling with specific guidance when requirements aren't met

Usage

plot_spec_curve(
  long_data,
  name_treated_unit,
  outcomes = NULL,
  normalize_outcomes = "none",
  rmse_threshold = Inf,
  shap_values = NULL,
  file_path_save = NA,
  width = 6,
  height = 10,
  show_pvalues = FALSE,
  p_threshold = 0.05,
  prefer_bootstrap_pvalues = FALSE,
  curve_stat = "abs_median_tau",
  weighting = c("none", "pre_rmspe_percentile"),
  two_sided = TRUE,
  grid_policy = "strict",
  min_placebos = 1L,
  min_specs = 2L,
  test_statistic = "rmse_ratio",
  null_distribution = "placebo",
  crop_outliers = "none",
  sort_by = "tau",
  filter_specs = NULL,
  show_shap = TRUE,
  shap_label_type = "absolute",
  show_predictions = FALSE,
  predictions = NULL,
  xgboost_params = NULL,
  tune_xgboost = NULL,
  xgboost_grid = NULL,
  xgboost_cv_folds = 5
)

Arguments

Details

Plot Specification Curve Using Direct Long Format Data

Panel B labels are rich text. To save final_plot as SVG, use the Cairo device (grDevices::svg); svglite misaligns the labels.

Value

List containing:

• final_plot: ggplot object representing the complete specification curve with Panel A (treatment effects) and Panel B (feature groups/SHAP)

• panel_a: ggplot object for Panel A only (treatment effects)

• panel_b: ggplot object for Panel B only (feature groups/SHAP)

• plot_data_p1: data.table with Panel A plotting data including columns: Unit Name, Estimate, RMSE, Specification, unit_type, p_value (if available)

• plot_data_p2: data.table with Panel B plotting data including columns: Specification, feature_group, feature, shapley_value (if SHAP computed)

• computed_shap: Complete results from internal SHAP computation (NULL if external shap_values provided or show_shap=FALSE). Contains: results (feature importance), shapley (SHAP values), predictions (model predictions), models (trained XGBoost models), config (SHAP configuration)

• spec_curve_pvals: List with specification curve-level p-values calculated on filtered data: treated_summary (treated-unit curve estimates and p-values) and stats_by_unit (curve statistics for treated and placebo units), plus attrition_report summarizing unit/spec retention under grid_policy. NULL if no inference data available.

• filtered_specs: Integer count of specifications remaining after filtering (before filtering if filter_specs=NULL)

• feature_groups_displayed: Character vector of feature groups shown in Panel B (only groups with variation in filtered data)

Examples

specs <- data.table::data.table(
  full_spec_id = paste0("s", 1:4),
  outcome_model = c("none", "ridge", "none", "ridge"),
  const = c("simplex", "lasso", "simplex", "lasso"),
  fw = c("uniform", "uniform", "optimize", "optimize"),
  feat = c("f1", "f1", "f2", "f2")
)
long_data <- data.table::CJ(
  unit_name = c("treated", "donor1"),
  full_spec_id = as.character(specs[["full_spec_id"]]),
  post_period = c(FALSE, TRUE),
  sorted = FALSE
)
long_data[, unit_type := ifelse(unit_name == "treated", "treated", "control")]
long_data <- merge(long_data, specs, by = "full_spec_id", all.x = TRUE)
long_data[, outcome := "y"]
long_data[, rmse := 0.2 + as.numeric(factor(full_spec_id)) * 0.01]
long_data[, tau := ifelse(
  unit_name == "treated",
  as.numeric(factor(full_spec_id)) * 0.5 + ifelse(post_period, 0.2, 0),
  as.numeric(factor(full_spec_id)) * 0.1 + ifelse(post_period, 0.05, 0)
)]
out <- plot_spec_curve(
  long_data = long_data,
  name_treated_unit = "treated",
  show_shap = FALSE,
  show_pvalues = FALSE,
  curve_stat = "abs_median_tau",
  weighting = "none"
)
out$panel_a

Description

Plot method that creates a specification curve visualization by calling the main plotting function with appropriate defaults.

Usage

## S3 method for class 'spec_curve'
plot(x, ...)

Arguments

Details

This is a convenience method that calls plot_spec_curve with the specification curve data. All arguments supported by plot_spec_curve can be passed through the ... parameter.

Value

A ggplot object containing the specification curve plot

See Also

plot_spec_curve for detailed plotting options

Examples

specs <- data.table::data.table(
  full_spec_id = paste0("s", 1:4),
  outcome_model = c("none", "ridge", "none", "ridge"),
  const = c("simplex", "lasso", "simplex", "lasso"),
  fw = c("uniform", "uniform", "optimize", "optimize"),
  feat = c("f1", "f1", "f2", "f2")
)
dt <- data.table::CJ(
  unit_name = c("treated", "donor1"),
  full_spec_id = as.character(specs[["full_spec_id"]]),
  post_period = c(FALSE, TRUE),
  sorted = FALSE
)
dt[, unit_type := ifelse(unit_name == "treated", "treated", "control")]
dt <- merge(dt, specs, by = "full_spec_id", all.x = TRUE)
dt[, outcome := "y"]
dt[, rmse := 0.2 + as.numeric(factor(full_spec_id)) * 0.01]
dt[, tau := ifelse(
  unit_name == "treated",
  as.numeric(factor(full_spec_id)) * 0.5 + ifelse(post_period, 0.2, 0),
  as.numeric(factor(full_spec_id)) * 0.1 + ifelse(post_period, 0.05, 0)
)]
spec_results <- list(results = dt)
class(spec_results) <- "spec_curve"
plot(spec_results, show_shap = FALSE, show_pvalues = FALSE)

Description

The print method for synthetic control data objects.

Usage

## S3 method for class 'scdata'
print(x, ...)

Arguments

Value

No return value, called to print scdata results.

Author(s)

Matias Cattaneo, Princeton University. [email protected].

Yingjie Feng, Tsinghua University. [email protected].

Filippo Palomba, Princeton University (maintainer). [email protected].

Rocio Titiunik, Princeton University. [email protected].

See Also

scdata for synthetic control data preparation.

Supported methods: print.scdata, summary.scdata.

Description

The print method for synthetic control prediction fitted objects.

Usage

## S3 method for class 'scest'
print(x, ...)

Arguments

Value

No return value, called to print scest results.

Author(s)

Matias Cattaneo, Princeton University. [email protected].

Yingjie Feng, Tsinghua University. [email protected].

Filippo Palomba, Princeton University (maintainer). [email protected].

Rocio Titiunik, Princeton University. [email protected].

See Also

scest for synthetic control prediction.

Supported methods: print.scest, summary.scest, coef.scest.

Description

Print method for scest_formula objects

Usage

## S3 method for class 'scest_formula'
print(x, ...)

Arguments

Description

Performs specification curve analysis across multiple modeling choices and configurations, providing a systematic exploration of researcher degrees of freedom.

Usage

run_spec_curve_analysis(dataset, params, cores = 1, output_dir = NULL)

Arguments

Details

Run Comprehensive Specification Curve Analysis

Value

List structure containing:

• results - Data.table in long format with all specification results

• abadie_inference - Abadie placebo inference results (if inference_type includes "placebo")

• bootstrap_inference - Bootstrap inference results (if inference_type includes "bootstrap")

Examples

set.seed(1)
toy <- expand.grid(unit = c("treated", "donor1", "donor2", "donor3"), year = 1:10,
                   stringsAsFactors = FALSE)
toy$y <- 50 + 0.8 * toy$year + ifelse(toy$unit == "treated" & toy$year >= 7, 3, 0) +
  rnorm(nrow(toy), 0, 0.5)
params <- list(
  outcomes = "y",
  col_name_unit_name = "unit",
  name_treated_unit = "treated",
  covagg = list(
    baseline = list(
      label = "baseline",
      operations = list(list(var = "outcome_var", partition_periods = list(type = "by_period")))
    )
  ),
  treated_period = 7,
  min_period = 1,
  end_period = 10,
  col_name_period = "year",
  feature_weights = "uniform",
  donor_sample = "all",
  outcome_models = "none",
  constraints = list(list(name = "simplex")),
  inference_type = "placebo",
  inference_config = list(verbose = FALSE, placebo_cores = 1)
)
results <- run_spec_curve_analysis(dataset = toy, params = params, cores = 1)
names(results)

Description

Performs XGBoost modeling and SHAP analysis directly on long format data produced by spec_curve() or run_spec_curve_analysis().

Usage

run_xgboost_shap_analysis(long_data, config, compute_loo = TRUE)

Arguments

Details

Run XGBoost SHAP Analysis on Long Format Data

Value

List containing:

• results - Feature importance results

• shapley - SHAP values with proper spec_number alignment

• predictions - Model predictions

• config - Original configuration object

Examples

if (requireNamespace("xgboost", quietly = TRUE)) {
  long_data <- data.table::data.table(
    unit_name = rep("treated", 6),
    full_spec_id = paste0("s", 1:6),
    spec_number = 1:6,
    post_period = TRUE,
    tau = c(0.4, 0.6, 0.2, 0.8, 0.3, 0.7),
    outcome_model = c("none", "ridge", "none", "ridge", "none", "ridge"),
    const = c("simplex", "lasso", "simplex", "lasso", "simplex", "lasso"),
    fw = c("uniform", "uniform", "optimize", "optimize", "uniform", "optimize"),
    feat = c("f1", "f1", "f2", "f2", "f3", "f3")
  )
  xgb_cfg <- create_xgboost_config(
    dataset_name = "toy",
    treated_unit_name = "treated",
    spec_features = c("outcome_model", "const", "fw", "feat"),
    tune_xgboost = FALSE,
    xgboost_params = list(
      objective = "reg:squarederror",
      max_depth = 2,
      eta = 0.1,
      nrounds = 20,
      subsample = 1,
      colsample_bytree = 1,
      nthread = 1,
      seed = 42,
      verbose = 0
    )
  )
  shap_results <- run_xgboost_shap_analysis(
    long_data = long_data,
    config = xgb_cfg,
    compute_loo = FALSE
  )
  names(shap_results)
}

Description

This function prepares a data structure for use with Synthetic Control Methods (SCM) by formatting and organizing the input data. It validates inputs, structures the data appropriately, and creates matrices needed for synthetic control estimation.

Usage

scdata(
  df,
  id.var,
  time.var,
  outcome.var,
  period.pre,
  period.post,
  unit.tr,
  unit.co,
  anticipation = 0,
  constant = FALSE,
  verbose = TRUE,
  covagg = list(),
  cointegrated.data = FALSE
)

Arguments

Details

This function performs several key operations:

• Validates that all required variables exist in the data

• Checks for balanced panel structure

• Creates outcome matrices for treated and control units

• Handles missing data appropriately

• Prepares data structures required by estimation functions

The function expects panel data in long format where each row represents one unit-time observation.

Value

A list of class 'scdata' containing:

• Y.pre: Matrix of pre-treatment outcomes (controls × time periods)

• Y.post: Matrix of post-treatment outcomes

• Y.donors: Full outcome matrix for donor units

• Y.treated: Outcome vector for treated unit

• specs: List containing specification details

• Additional metadata for estimation and plotting

Examples

toy <- data.frame(
  unit = rep(c("treated", "donor1", "donor2"), each = 6),
  year = rep(1:6, 3),
  y = c(10, 11, 12, 14, 15, 16,
        9, 10, 11, 12, 13, 14,
        11, 12, 13, 13, 14, 15)
)
scm_data <- scdata(
  df = toy,
  id.var = "unit",
  time.var = "year",
  outcome.var = "y",
  period.pre = 1:4,
  period.post = 5:6,
  unit.tr = "treated",
  unit.co = c("donor1", "donor2"),
  covagg = list(
    list(var = "outcome_var", partition_periods = list(type = "by_period"))
  )
)
class(scm_data)

Description

This function estimates synthetic control weights for a single treated unit using various constraint specifications and optimization methods. It implements the core synthetic control methodology with flexible constraint options and feature weighting schemes.

Usage

scest(
  data,
  w.constr = NULL,
  feature_weights = "uniform",
  V = "separate",
  V.mat = NULL,
  solver = "ECOS",
  save.data = NULL,
  margin.ipop = 0.05,
  sigf.ipop = 5,
  bound.ipop = 10
)

Arguments

Details

The function implements the synthetic control method by solving the optimization problem:

$\min_W ||X_1 - X_0 W||_V^2 + penalty(W)$

where $X_1$ is the treated unit's pre-treatment characteristics, $X_0$ is the control units' characteristics matrix, $W$ are the synthetic control weights, and $V$ is the feature weighting matrix.

Different constraint types impose different penalty functions:

• Simplex: $\sum W_i = 1, W_i \geq 0$

• Lasso: $Q \sum |W_i|$

• Ridge: $Q \sum W_i^2$

• OLS: No constraints

Value

A list of class "scest" containing:

• est.results$w - Vector of synthetic control weights for donor units

• est.results$constant_term - Constant (intercept) coefficient if constant=TRUE was used in scdata, NULL otherwise

• est.results$b - Full coefficient vector (donor weights + constant term)

• est.results$Y.pre.fit - Fitted pre-treatment outcomes

• est.results$Y.post.fit - Fitted post-treatment outcomes

• est.results$V - Feature weighting matrix used

• est.results$w.constr - Weight constraint specification used

• data - Original scdata object with estimation matrices

• Additional estimation metadata and diagnostics

Examples

toy <- data.frame(
  unit = rep(c("treated", "donor1", "donor2"), each = 6),
  year = rep(1:6, 3),
  y = c(10, 11, 12, 14, 15, 16,
        9, 10, 11, 12, 13, 14,
        11, 12, 13, 13, 14, 15)
)
scm_data <- scdata(
  df = toy,
  id.var = "unit",
  time.var = "year",
  outcome.var = "y",
  period.pre = 1:4,
  period.post = 5:6,
  unit.tr = "treated",
  unit.co = c("donor1", "donor2"),
  covagg = list(
    list(var = "outcome_var", partition_periods = list(type = "by_period"))
  )
)
result <- scest(data = scm_data, w.constr = list(name = "simplex"))
names(result$est.results)

Description

Plot treated and synthetic time series from a fitted scest object.

Companion Stata and Python packages are described in Cattaneo, Feng, Palomba, and Titiunik (2022).

Companion commands are scdata for data preparation, scest for point estimation, and inference_sc for inference procedures.

For an introduction to synthetic control methods, see Abadie (2021) and references therein.

Usage

scplot(
  result,
  fig.path = NULL,
  fig.name = NULL,
  fig.format = "png",
  col.treated = "black",
  col.synth = "mediumblue",
  label.xy = NULL,
  plot.range = NULL,
  x.ticks = NULL,
  event.label = NULL,
  plot.specs = NULL,
  save.data = NULL
)

Arguments

Value

Author(s)

Matias Cattaneo, Princeton University. [email protected].

Yingjie Feng, Tsinghua University. [email protected].

Filippo Palomba, Princeton University (maintainer). [email protected].

Rocio Titiunik, Princeton University. [email protected].

References

• Abadie, A. (2021). Using synthetic controls: Feasibility, data requirements, and methodological aspects. Journal of Economic Literature, 59(2), 391-425.

See Also

scdata, scest, inference_sc

Examples

# Create example data
df <- data.frame(
  unit = rep(c("treated", "control1", "control2"), each = 20),
  time = rep(1:20, 3),
  outcome = c(rnorm(20, mean = 1:20), rnorm(20, mean = 1:20), rnorm(20, mean = 1:20))
)

# Prepare data for SCM
scm_data <- scdata(df = df, id.var = "unit", time.var = "time",
                   outcome.var = "outcome", period.pre = 1:10,
                   period.post = 11:20, unit.tr = "treated",
                   unit.co = c("control1", "control2"))

# Estimate synthetic control
result <- scest(scm_data, w.constr = list(name = "simplex"))

# Plot results
scplot(result)

Description

Solve quadratic programming problem using clarabel solver

Usage

solve_qp_clarabel(c, H, A, b, l, u)

Arguments

Value

Solution vector as matrix

Description

INTERNAL COMPUTATIONAL CORE - This function performs the core computation for specification curve analysis by systematically varying modeling choices and estimating treatment effects across all combinations. Called internally by run_spec_curve_analysis(). For user-facing specification curve analysis, use run_spec_curve_analysis() instead.

Usage

spec_curve(
  dataset,
  outcomes,
  col_name_unit_name,
  name_treated_unit,
  covagg = list(),
  treated_period,
  min_period,
  end_period,
  col_name_period,
  feature_weights = c("uniform", "optimize"),
  outcome_models = c("none", "augsynth", "ridge", "lasso", "ols"),
  donor_sample = c("all", "most_similar"),
  sim_function = most_similar,
  constraints = list(list(name = "ols"), list(name = "simplex"), list(name = "lasso"),
    list(name = "ridge"), list(name = "L1-L2")),
  constants = c(FALSE, TRUE),
  cores = 1,
  verbose = TRUE,
  inference_type = "placebo",
  inference_config = list(),
  expected_direction = "two_sided"
)

Arguments

Details

Generate Specification Curve (Core Computational Engine)

The function creates a Cartesian product of all specification choices and estimates synthetic controls for each combination. This implementation includes:

• Parallel Processing: Distributes computations across multiple cores.

• Error Handling: Captures failed estimations and returns diagnostics.

• Progress Tracking: Provides estimation progress updates.

• Memory Management: Handles large specification spaces.

The resulting specification curve can reveal:

• Sensitivity of treatment-effect estimates to modeling choices.

• Distribution of effect sizes across specifications.

• Which modeling choices are associated with estimate shifts.

• Overall robustness of findings.

Value

A list structure containing:

• results: data.table in long format with all specification results.

• abadie_inference: list containing placebo-in-space inference outputs, including p-values and post/pre RMSPE ratios.

• bootstrap_inference: list containing bootstrap inference outputs.

The results data.table contains treatment effects (tau), unit information, and specification metadata for all units (treated, control placebo, bootstrap iterations) across all specifications. Inference results are separated to avoid duplication and provide cleaner access to statistical tests.

References

• Simonsohn, U., Simmons, J. P., and Nelson, L. D. (2020). Specification curve analysis. Nature Human Behaviour, 4(11), 1208-1214.

• Huntington-Klein, N. et al. (2021). The influence of hidden researcher decisions in applied microeconomics. Economic Inquiry, 59(3), 944-960.

Examples

set.seed(1)
toy <- expand.grid(unit = c("treated", "donor1", "donor2", "donor3"), year = 1:10,
                   stringsAsFactors = FALSE)
toy$y <- 50 + 0.8 * toy$year + ifelse(toy$unit == "treated" & toy$year >= 7, 3, 0) +
  rnorm(nrow(toy), 0, 0.5)
results <- spec_curve(
  dataset = toy,
  outcomes = "y",
  col_name_unit_name = "unit",
  name_treated_unit = "treated",
  covagg = list(
    baseline = list(
      label = "baseline",
      operations = list(list(var = "outcome_var", partition_periods = list(type = "by_period")))
    )
  ),
  treated_period = 7,
  min_period = 1,
  end_period = 10,
  col_name_period = "year",
  feature_weights = "uniform",
  outcome_models = "none",
  donor_sample = "all",
  constraints = list(list(name = "simplex")),
  constants = FALSE,
  cores = 1,
  inference_type = "placebo",
  inference_config = list(verbose = FALSE, placebo_cores = 1)
)
names(results)

Description

This file contains S3 methods for objects of class "spec_curve" created by the spec_curve function. These methods provide a professional interface for examining and summarizing specification curve analysis results.

Print method for specification curve objects that provides a concise overview of the analysis results including number of specifications, treatment effect distribution, and available inference results.

Usage

## S3 method for class 'spec_curve'
print(x, ...)

Arguments

Details

The print method displays:

• Number of specifications estimated

• Number of outcomes analyzed

• Treatment effect summary statistics

• Available inference methods and significance rates

• Specification dimension summary

Value

No return value, called for side effects (printing)

Examples

specs <- data.table::data.table(
  full_spec_id = paste0("s", 1:4),
  outcome_model = c("none", "ridge", "none", "ridge"),
  const = c("simplex", "lasso", "simplex", "lasso"),
  fw = c("uniform", "uniform", "optimize", "optimize"),
  feat = c("f1", "f1", "f2", "f2")
)
dt <- data.table::CJ(
  unit_name = c("treated", "donor1"),
  full_spec_id = as.character(specs[["full_spec_id"]]),
  post_period = c(FALSE, TRUE),
  sorted = FALSE
)
dt[, unit_type := ifelse(unit_name == "treated", "treated", "control")]
dt <- merge(dt, specs, by = "full_spec_id", all.x = TRUE)
dt[, outcome := "y"]
dt[, rmse := 0.2 + as.numeric(factor(full_spec_id)) * 0.01]
dt[, tau := ifelse(
  unit_name == "treated",
  as.numeric(factor(full_spec_id)) * 0.5 + ifelse(post_period, 0.2, 0),
  as.numeric(factor(full_spec_id)) * 0.1 + ifelse(post_period, 0.05, 0)
)]
spec_results <- list(results = dt)
class(spec_results) <- "spec_curve"
print(spec_results)

Description

R6 class for managing large specification curve results with disk-based storage, compression, and memory-efficient retrieval patterns.

Public fields

Methods

Public methods

• SpecResultsManager$new()

• SpecResultsManager$store_results()

• SpecResultsManager$retrieve_results()

• SpecResultsManager$get_filtered_results()

• SpecResultsManager$update_metadata()

• SpecResultsManager$get_metadata()

• SpecResultsManager$check_memory_usage()

• SpecResultsManager$cleanup_memory()

• SpecResultsManager$get_storage_summary()

• SpecResultsManager$cleanup_storage()

• SpecResultsManager$merge_specification_sets()

• SpecResultsManager$clone()

SpecResultsManager$new()

Initialize storage manager

Usage

SpecResultsManager$new(
  storage_dir = tempdir(),
  max_memory_mb = 1000,
  compression_level = 6
)

Arguments

SpecResultsManager$store_results()

Store specification results efficiently

Usage

SpecResultsManager$store_results(spec_results, spec_id, metadata = list())

Arguments

SpecResultsManager$retrieve_results()

Retrieve specification results

Usage

SpecResultsManager$retrieve_results(spec_id, lazy = TRUE)

Arguments

SpecResultsManager$get_filtered_results()

Get filtered subset of results without loading all data

Usage

SpecResultsManager$get_filtered_results(
  spec_id,
  filter_function = NULL,
  select_cols = NULL
)

Arguments

SpecResultsManager$update_metadata()

Update metadata for stored results

Usage

SpecResultsManager$update_metadata(
  spec_id,
  file_path,
  spec_results,
  additional_metadata = list()
)

Arguments

SpecResultsManager$get_metadata()

Get metadata for all stored results

Usage

SpecResultsManager$get_metadata()

SpecResultsManager$check_memory_usage()

Check current memory usage and trigger cleanup if needed

Usage

SpecResultsManager$check_memory_usage()

SpecResultsManager$cleanup_memory()

Clean up memory by removing old cached objects

Usage

SpecResultsManager$cleanup_memory()

SpecResultsManager$get_storage_summary()

Get summary statistics about stored specifications

Usage

SpecResultsManager$get_storage_summary()

SpecResultsManager$cleanup_storage()

Clean up storage directory

Usage

SpecResultsManager$cleanup_storage(older_than_days = 30)

Arguments

SpecResultsManager$merge_specification_sets()

Merge multiple specification result sets efficiently

Usage

SpecResultsManager$merge_specification_sets(spec_ids, output_spec_id)

Arguments

SpecResultsManager$clone()

The objects of this class are cloneable with this method.

Usage

SpecResultsManager$clone(deep = FALSE)

Arguments

Description

The summary method for synthetic control prediction objects.

Usage

## S3 method for class 'scdata'
summary(object, ...)

Arguments

Value

No return value, called to summarize scdata results.

Author(s)

Matias Cattaneo, Princeton University. [email protected].

Yingjie Feng, Tsinghua University. [email protected].

Filippo Palomba, Princeton University (maintainer). [email protected].

Rocio Titiunik, Princeton University. [email protected].

See Also

scdata

Supported methods: print.scdata, summary.scdata.

Description

The summary method for synthetic control prediction fitted objects.

Usage

## S3 method for class 'scest'
summary(object, ...)

Arguments

Value

No return value, called to summarize scest results.

Author(s)

Matias Cattaneo, Princeton University. [email protected].

Yingjie Feng, Tsinghua University. [email protected].

Filippo Palomba, Princeton University (maintainer). [email protected].

Rocio Titiunik, Princeton University. [email protected].

See Also

scest

Supported methods: print.scest, summary.scest, coef.scest.

Description

Summary method for scest_formula objects

Usage

## S3 method for class 'scest_formula'
summary(object, ...)

Arguments

Description

Detailed summary method for specification curve objects that provides comprehensive information about the analysis results, including breakdown by specification dimensions and detailed inference results.

Usage

## S3 method for class 'spec_curve'
summary(object, ...)

Arguments

Details

The summary method provides detailed information including:

• Treatment effect statistics by specification dimension

• Inference results breakdown

• Model performance statistics (RMSE, fit)

• Specification robustness indicators

Value

No return value, called for side effects (printing detailed summary)

Examples

specs <- data.table::data.table(
  full_spec_id = paste0("s", 1:4),
  outcome_model = c("none", "ridge", "none", "ridge"),
  const = c("simplex", "lasso", "simplex", "lasso"),
  fw = c("uniform", "uniform", "optimize", "optimize"),
  feat = c("f1", "f1", "f2", "f2")
)
dt <- data.table::CJ(
  unit_name = c("treated", "donor1"),
  full_spec_id = as.character(specs[["full_spec_id"]]),
  post_period = c(FALSE, TRUE),
  sorted = FALSE
)
dt[, unit_type := ifelse(unit_name == "treated", "treated", "control")]
dt <- merge(dt, specs, by = "full_spec_id", all.x = TRUE)
dt[, outcome := "y"]
dt[, rmse := 0.2 + as.numeric(factor(full_spec_id)) * 0.01]
dt[, tau := ifelse(
  unit_name == "treated",
  as.numeric(factor(full_spec_id)) * 0.5 + ifelse(post_period, 0.2, 0),
  as.numeric(factor(full_spec_id)) * 0.1 + ifelse(post_period, 0.05, 0)
)]
spec_results <- list(results = dt)
class(spec_results) <- "spec_curve"
summary(spec_results)

Description

Estimate synthetic control using standard R formula syntax. This function provides a convenient interface that automatically handles data preparation and estimation based on formula specification.

Usage

synth(
  formula,
  data,
  time.var,
  id.var,
  treated.period,
  pre.period,
  post.period,
  constraint = "simplex",
  feature.weights = "uniform",
  covariate.matching = "average",
  ...
)

Arguments

Details

The formula interface translates standard R formula syntax into the appropriate scdata/scest calls:

Formula Components:

• Left side: Outcome variable

• Right side (before |): Covariates for matching

• Right side (after |): Treated unit identifier

Special Formula Syntax:

• I(log(var)) - Transform variables

• var1 + var2 - Include multiple covariates

• . - Include all available covariates

• -var - Exclude specific variables from matching

Value

An object of class "scest_formula" inheriting from "scest" with additional formula-related metadata

Examples

panel_data <- data.frame(
  state = rep(c("California", "Texas", "Florida"), each = 6),
  year = rep(1:6, 3),
  gdp = c(10, 11, 12, 14, 15, 16,
          9, 10, 11, 12, 13, 14,
          11, 12, 13, 13, 14, 15),
  population = c(1, 1.1, 1.2, 1.3, 1.35, 1.4,
                 0.9, 0.95, 1.0, 1.05, 1.1, 1.15,
                 1.2, 1.25, 1.3, 1.33, 1.36, 1.4),
  investment = c(2, 2.1, 2.2, 2.4, 2.5, 2.6,
                 1.8, 1.9, 2.0, 2.1, 2.2, 2.3,
                 2.0, 2.1, 2.2, 2.25, 2.3, 2.35)
)
result <- synth(
  gdp ~ population + investment | California,
  data = panel_data,
  time.var = "year",
  id.var = "state",
  treated.period = 5,
  pre.period = 1:4,
  post.period = 5:6,
  constraint = "simplex"
)
class(result)

Description

These methods provide broom-compatible interfaces for extracting information from synthetic control estimation results in tidy data.table format. They follow the broom convention of tidy(), glance(), and augment() methods while returning data.table objects for efficiency.

Details

Tidy Methods for SCMs Objects

Description

Extract donor unit weights and related information from synthetic control estimation results in a tidy data.table format compatible with broom workflows.

Usage

## S3 method for class 'scest'
tidy(x, conf.int = FALSE, conf.level = 0.95, ...)

Arguments

Value

A data.table with columns:

• term - Character. Donor unit names

• estimate - Numeric. Synthetic control weights

• donor_rank - Integer. Rank of donor by weight (1 = highest)

• weight_percentage - Numeric. Weight as percentage of total

• is_active - Logical. Whether weight is meaningfully non-zero

• constraint_type - Character. Type of constraint used

• std.error - Numeric. Standard error (if conf.int=TRUE and available)

• conf.low - Numeric. Lower confidence bound (if conf.int=TRUE)

• conf.high - Numeric. Upper confidence bound (if conf.int=TRUE)

Examples

toy <- data.frame(
  unit = rep(c("treated", "donor1", "donor2"), each = 6),
  year = rep(1:6, 3),
  y = c(10, 11, 12, 14, 15, 16,
        9, 10, 11, 12, 13, 14,
        11, 12, 13, 13, 14, 15)
)
sc_obj <- scdata(
  df = toy,
  id.var = "unit",
  time.var = "year",
  outcome.var = "y",
  period.pre = 1:4,
  period.post = 5:6,
  unit.tr = "treated",
  unit.co = c("donor1", "donor2"),
  covagg = list(list(var = "outcome_var", partition_periods = list(type = "by_period")))
)
fit <- scest(sc_obj, w.constr = list(name = "simplex"))
generics::tidy(fit)

Description

Extract treatment effect estimates and metadata from specification curve analysis results in tidy data.table format.

Usage

## S3 method for class 'spec_curve'
tidy(x, conf.int = FALSE, conf.level = 0.95, ...)

Arguments

Value

A data.table with columns:

• spec_id - Character. Specification identifier

• estimate - Numeric. Treatment effect estimate

• outcome - Character. Outcome variable name

• unit_name - Character. Treated unit name

• rmse - Numeric. Root mean squared error

• outcome_model - Character. Outcome modeling approach

• constraint_type - Character. Weight constraint type

• feature_weights - Character. Feature weighting method

• p.value - Numeric. P-value from inference (if available)

• statistic - Numeric. Test statistic (if available)

• method - Character. Inference method used

• significant - Logical. Whether p < 0.05

Examples

spec_results <- list(
  results = data.table::data.table(
    full_spec_id = c("s1", "s2"),
    tau = c(1.2, 0.8),
    outcome = "y",
    unit_name = "treated",
    unit_type = "treated",
    post_period = TRUE,
    rmse = c(0.2, 0.3)
  )
)
class(spec_results) <- "spec_curve"
generics::tidy(spec_results)