Package 'scmSpillover'

Per-Capita Cigarette Consumption by U.S. State, 1970-2000

Description

Annual per-capita cigarette sales (in packs) for 39 U.S. states from 1970 to 2000. The first column, CA, is California – the treated unit in the Proposition 99 tobacco-control program, a large excise-tax increase that took effect in 1989. The remaining 38 columns are control (donor) states. This is the running example used in the synthetic control literature.

Usage

california_cigarette

Format

A numeric matrix with 31 rows (years 1970-2000) and 39 columns (U.S. states). Row names are the years; column names are two-letter state abbreviations, with CA (California) first.

Source

Orzechowski and Walker, The Tax Burden on Tobacco, as used by Abadie, Diamond and Hainmueller (2010) "Synthetic Control Methods for Comparative Case Studies".

Examples

data(california_cigarette)
dim(california_cigarette)
california_cigarette[1:5, 1:4]

---

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 of dimension n_periods x n_units (time in rows, units in columns); the first column is the treated unit.

Examples

sim <- generate_test_data(n_units = 10, n_periods = 30)
dim(sim)

---

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)

---

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)

---

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	Character; "effects" (default) for the treatment-effect plot or "all" for the full set of diagnostic plots.
...	Further arguments passed to plot_effects or plot_all.

Value

A ggplot2 object (invisibly), as returned by the underlying plotting function.

---

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.
...	Further arguments passed to or from other methods (unused).

Value

The input object x, invisibly.

---

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

An object of class scm_spillover: a list with the spillover-adjusted and standard treatment effects, confidence bounds, the synthetic-control series, and the inputs used.

Examples

set.seed(1)
sim <- generate_test_data(n_units = 10, n_periods = 30, treatment_start = 20)
res <- run_scm_spillover(sim, treatment_start = 20, verbose = FALSE)
res$spillover_effects

---

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 = ".",
  width = 10,
  height = 6,
  dpi = 300,
  ...
)

Arguments

result	Output from run_scm_spillover
prefix	File name prefix (default "scm")
path	Directory to save plots (default current directory)
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 names (invisibly)

---

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	Ridge regularization parameter for numerical stability

Value

List containing intercept (a) and weights (b)

Examples

set.seed(1)
controls <- matrix(rnorm(5 * 20, 100, 10), nrow = 5)
treated  <- c(0.5, 0.3, 0.2, 0, 0) %*% controls + rnorm(20, 0, 0.5)
Y <- rbind(treated, controls)
fit <- scm(Y)
fit$b   # weights; first entry (0) is the treated unit

---

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.
...	Further arguments passed to or from other methods (unused).

Value

A data frame of per-period effects, invisibly.

---

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

---