| Type: | Package |
| Title: | Synthetic Control Method with Spillover Effects |
| Version: | 0.1.1 |
| 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". |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| Imports: | limSolve, MASS, ggplot2, stats |
| Suggests: | testthat (≥ 3.0.0) |
| RoxygenNote: | 7.3.3 |
| Depends: | R (≥ 3.5) |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2026-01-07 15:58:27 UTC; User |
| Author: | Jianfei Cao [aut], Zhanchao Fu [cre] |
| Maintainer: | Zhanchao Fu <fuzhanchao2001@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-01-09 15:00:07 UTC |
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)
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")
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)
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