Package 'scmSpillover'

Title: Synthetic Control Method with Spillover Effects
Description: A general-purpose implementation of synthetic control methods that accounts for potential spillover effects between units. Based on the methodology of Cao and Dowd (2019) <doi:10.48550/arXiv.1902.07343> "Estimation and Inference for Synthetic Control Methods with Spillover Effects".
Authors: Jianfei Cao [aut], Zhanchao Fu [cre]
Maintainer: Zhanchao Fu <[email protected]>
License: MIT + file LICENSE
Version: 0.1.1
Built: 2026-05-09 07:11:24 UTC
Source: https://github.com/cran/scmSpillover

Help Index

Generate simulated data for testing

Description

Generate simulated data for testing

Usage

generate_test_data(
  n_units = 20,
  n_periods = 30,
  treatment_start = 20,
  effect_size = -5
)

Arguments

n_units

Number of units
n_periods

Number of time periods
treatment_start

When treatment begins
effect_size

Size of treatment effect

Value

A numeric matrix with dimensions (n_periods x n_units). The first column represents the treated unit, remaining columns are control units. Rows represent time periods.

Examples

# Generate test data with default parameters
data <- generate_test_data()
dim(data)  # 30 periods x 20 units

# Generate smaller dataset
data <- generate_test_data(n_units = 10, n_periods = 20,
                           treatment_start = 15, effect_size = -3)

Generate all plots for SCM analysis

Description

Generate all plots for SCM analysis

Usage

plot_all(
  result,
  start_year = NULL,
  unit_name = "Treated Unit",
  outcome_label = "Outcome",
  treatment_label = "Treatment",
  show_ci = TRUE
)

Arguments

result

Output from run_scm_spillover
start_year

First year of treatment period
unit_name

Name of treated unit (default "Treated Unit")
outcome_label

Label for outcome variable (default "Outcome")
treatment_label

Label for treatment (default "Treatment")
show_ci

Logical, whether to show confidence bands (default TRUE)

Value

A list containing three ggplot objects (p1, p2, p3), returned invisibly. Called primarily for side effects (displaying plots).

Examples

## Not run: 
  data <- generate_test_data()
  result <- run_scm_spillover(data, treatment_start = 20)
  plots <- plot_all(result)

## End(Not run)

Plot treatment effects only

Description

Plot treatment effects only

Usage

plot_effects(
  result,
  start_year = NULL,
  unit_name = "Treated Unit",
  outcome_label = "Outcome",
  show_ci = TRUE,
  show_vanilla = FALSE
)

Arguments

result

Output from run_scm_spillover
start_year

First year of treatment period
unit_name

Name of treated unit (default "Treated Unit")
outcome_label

Label for outcome variable (default "Outcome")
show_ci

Logical, whether to show confidence bands (default TRUE)
show_vanilla

Logical, whether to show vanilla SCM comparison (default FALSE)

Value

A ggplot object that can be further customized or saved.

Examples

data <- generate_test_data()
  result <- run_scm_spillover(data, treatment_start = 20, verbose = FALSE)
  p <- plot_effects(result)

Plot method for scm_spillover objects

Description

Plot method for scm_spillover objects

Usage

## S3 method for class 'scm_spillover'
plot(x, type = "effects", ...)

Arguments

x

An object of class scm_spillover
type

Type of plot: "effects" or "all"
...

Additional arguments passed to plotting functions

Value

A ggplot object (invisibly for type="all")

Print method for scm_spillover objects

Description

Print method for scm_spillover objects

Usage

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

Arguments

x

An object of class scm_spillover
...

Additional arguments (not used)

Value

Invisibly returns the input object

Quick plot all three main plots in sequence

Description

Quick plot all three main plots in sequence

Usage

qplot_all(
  result,
  start_year = NULL,
  unit_name = "Treated Unit",
  outcome_label = "Outcome",
  treatment_label = "Treatment",
  show_ci = TRUE,
  pause = TRUE
)

Arguments

result

Output from run_scm_spillover
start_year

First year of treatment period
unit_name

Name of treated unit (default "Treated Unit")
outcome_label

Label for outcome variable (default "Outcome")
treatment_label

Label for treatment (default "Treatment")
show_ci

Logical, whether to show confidence bands (default TRUE)
pause

Logical, whether to pause between plots (default TRUE)

Value

List of ggplot objects (invisibly)

Quick plot with confidence intervals only

Description

Quick plot with confidence intervals only

Usage

qplot_ci(
  result,
  start_year = NULL,
  unit_name = "Treated Unit",
  outcome_label = "Outcome"
)

Arguments

result

Output from run_scm_spillover
start_year

First year of treatment period
unit_name

Name of treated unit (default "Treated Unit")
outcome_label

Label for outcome variable (default "Outcome")

Value

ggplot object (invisibly)

Quick plot for method comparison (Spillover vs Vanilla)

Description

Quick plot for method comparison (Spillover vs Vanilla)

Usage

qplot_compare(
  result,
  start_year = NULL,
  unit_name = "Treated Unit",
  outcome_label = "Outcome"
)

Arguments

result

Output from run_scm_spillover
start_year

First year of treatment period
unit_name

Name of treated unit (default "Treated Unit")
outcome_label

Label for outcome variable (default "Outcome")

Value

ggplot object (invisibly)

Quick plot for treatment effects with confidence intervals

Description

Quick plot for treatment effects with confidence intervals

Usage

qplot_effects(
  result,
  start_year = NULL,
  unit_name = "Treated Unit",
  outcome_label = "Outcome",
  show_ci = TRUE,
  show_vanilla = FALSE
)

Arguments

result

Output from run_scm_spillover
start_year

First year of treatment period
unit_name

Name of treated unit (default "Treated Unit")
outcome_label

Label for outcome variable (default "Outcome")
show_ci

Logical, whether to show confidence bands (default TRUE)
show_vanilla

Logical, whether to show vanilla SCM comparison (default FALSE)

Value

ggplot object (invisibly)

Quick plot without confidence intervals

Description

Quick plot without confidence intervals

Usage

qplot_point(
  result,
  start_year = NULL,
  unit_name = "Treated Unit",
  outcome_label = "Outcome"
)

Arguments

result

Output from run_scm_spillover
start_year

First year of treatment period
unit_name

Name of treated unit (default "Treated Unit")
outcome_label

Label for outcome variable (default "Outcome")

Value

ggplot object (invisibly)

Quick plot for actual vs synthetic control time series

Description

Quick plot for actual vs synthetic control time series

Usage

qplot_series(
  result,
  start_year = NULL,
  unit_name = "Treated Unit",
  outcome_label = "Outcome",
  treatment_label = "Treatment"
)

Arguments

result

Output from run_scm_spillover
start_year

First year of treatment period
unit_name

Name of treated unit (default "Treated Unit")
outcome_label

Label for outcome variable (default "Outcome")
treatment_label

Label for treatment (default "Treatment")

Value

ggplot object (invisibly)

Run Complete SCM Analysis with Spillover Effects

Description

Run Complete SCM Analysis with Spillover Effects

Usage

run_scm_spillover(
  data,
  treatment_start,
  treated_unit = 1,
  affected_units = NULL,
  verbose = TRUE
)

Arguments

data

Matrix or data frame (time x units)
treatment_start

Integer, first treatment period (row number)
treated_unit

Integer, column index of treated unit (default = 1)
affected_units

Vector of column indices for all affected units (including treated)
verbose

Logical, print progress

Value

List with all results

Safe matrix inversion with regularization

Description

Safely inverts a matrix using regularization if needed

Usage

safe_solve(M, tol = 1e-10)

Arguments

M

Matrix to invert
tol

Tolerance for condition number check

Value

Inverted matrix

Save all plots to files

Description

Save all plots to files

Usage

save_all_plots(
  result,
  prefix = "scm",
  path = NULL,
  width = 10,
  height = 6,
  dpi = 300,
  ...
)

Arguments

result

Output from run_scm_spillover
prefix

File name prefix (default "scm")
path

Directory to save plots (required, no default)
width

Plot width in inches (default 10)
height

Plot height in inches (default 6)
dpi

Resolution (default 300)
...

Additional arguments passed to plotting functions

Value

Character vector of saved file paths, returned invisibly.

Examples

## Not run: 
  data <- generate_test_data()
  result <- run_scm_spillover(data, treatment_start = 20)
  save_all_plots(result, path = tempdir())

## End(Not run)

Basic SCM function for single unit

Description

Computes synthetic control weights for a single treated unit

Usage

scm(Y, lambda = 1e-06)

Arguments

Y

N x T matrix where first row is treated unit
lambda

Regularization parameter for numerical stability

Value

List containing intercept (a) and weights (b)

Batch SCM for all units

Description

Computes synthetic control weights for all units

Usage

scm_batch(Y, verbose = FALSE)

Arguments

Y

N x T matrix of outcomes
verbose

Print progress messages

Value

List with intercepts (a) and weight matrix (B)

Test for spillover effects

Description

Tests whether spillover effects are significant

Usage

sp_andrews_spillover(Y0, Y1, A, alpha_sig = 0.05)

Arguments

Y0

N x T pre-treatment matrix
Y1

N x 1 post-treatment vector
A

N x k spillover structure matrix
alpha_sig

Significance level

Value

List with test results

Andrews test for treatment effects

Description

Tests significance of treatment effects

Usage

sp_andrews_te(Y0, Y1, A, C = NULL, alpha_sig = 0.05)

Arguments

Y0

N x T pre-treatment matrix
Y1

N x 1 post-treatment vector (single period)
A

N x k spillover structure matrix
C

Constraint matrix (default tests first unit)
alpha_sig

Significance level

Value

List with estimates, p-values, and confidence intervals

Spillover-adjusted SCM estimation

Description

Estimates treatment effects accounting for spillovers

Usage

sp_estimation(Y_pre, Y_post, A, verbose = FALSE)

Arguments

Y_pre

N x T pre-treatment matrix
Y_post

N x S post-treatment matrix
A

N x k spillover structure matrix
verbose

Print progress messages

Value

List containing treatment effects and other results

Summary method for scm_spillover objects

Description

Summary method for scm_spillover objects

Usage

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

Arguments

object

An object of class scm_spillover
...

Additional arguments (not used)

Value

Invisibly returns a data frame with detailed results

Standard SCM without spillovers

Description

Computes standard synthetic control for comparison

Usage

vanilla_scm(Y_pre, Y_post)

Arguments

Y_pre

N x T pre-treatment matrix
Y_post

N x S post-treatment matrix

Value

Synthetic control values for all periods