PanelMatch {PanelMatch}

PanelMatch

Description

Create refined/weighted sets of treated and control units

Usage

PanelMatch(
  lag,
  time.id,
  unit.id,
  treatment,
  outcome.var,
  refinement.method,
  data,
  qoi,
  size.match = 10,
  match.missing = TRUE,
  covs.formula = NULL,
  lead = 0,
  verbose = FALSE,
  exact.match.variables = NULL,
  forbid.treatment.reversal = FALSE,
  matching = TRUE,
  listwise.delete = FALSE,
  use.diagonal.variance.matrix = FALSE,
  restrict.control.period = NULL,
  placebo.test = FALSE
)

Arguments

lag

An integer value indicating the length of treatment history periods to be matched on

time.id

A character string indicating the name of the time variable in the data. This data currently must be formatted as sequential integers.

unit.id

A character string indicating the name of unit identifier in the data. This data must be integer.

treatment

A character string indicating the name of the treatment variable in the data. The treatment must be a binary indicator variable (integer with 0 for the control group and 1 for the treatment group).

outcome.var

A character string identifying the outcome variable.

refinement.method

A character string specifying the matching or weighting method to be used for refining the matched sets. The user can choose "mahalanobis", "ps.match", "CBPS.match", "ps.weight", "CBPS.weight", or "none". The first three methods will use the size.match argument to create sets of at most size.match closest control units. Choosing "none" will assign equal weights to all control units in each matched set.

data

A data.frame object containing time series cross sectional data. Time data must be sequential integers that increase by 1. Unit identifiers must be integers. Treatment data must be binary.

qoi

quantity of interest, provided as a string: att (average treatment effect on treated units), atc (average treatment effect of treatment on the control units) art (average effect of treatment reversal for units that experience treatment reversal), or ate (average treatment effect).

size.match

An integer dictating the number of permitted closest control units in a matched set after refinement. This argument only affects results when using a matching method ("mahalanobis" or any of the refinement methods that end in ".match"). This argument is not needed and will have no impact if included when a weighting method is specified (any refinement.method that includes "weight" in the name).

match.missing

Logical variable indicating whether or not units should be matched on the patterns of missingness in their treatment histories. Default is TRUE. When FALSE, neither treated nor control units are allowed to have missing treatment data in the lag window.

covs.formula

One sided formula object indicating which variables should be used for matching and refinement. Argument is not needed if refinement.method is set to "none" If the user wants to include lagged variables, this can be done using a function, "lag()", which takes two, unnamed, positional arguments. The first is the name of the variable which you wish to lag. The second is the lag window, specified as an integer sequence in increasing order. For instance, I(lag(x, 1:4)) will then add new columns to the data for variable "x" for time t-1, t-2, t-3, and t-4 internally and use them for defining/measuring similarity between units. Other transformations using the I() function, such as I(x^2) are also permitted. The variables specified in this formula are used to define the similarity/distances between units.

lead

integer sequence specifying the lead window, for which qoi point estimates (and standard errors) will ultimately be produced. Default is 0 (which corresponds to contemporaneous treatment effect).

verbose

option to include more information about the matched.set object calculations, like the distances used to create the refined sets and weights.

exact.match.variables

character vector giving the names of variables to be exactly matched on. These should be time invariant variables. Exact matching for time varying covariates is not currently supported.

forbid.treatment.reversal

Logical. For the ATT, it indicates whether or not it is permissible for treatment to reverse in the specified lead window. This is defined analogously for the ART. It is not valid for the ATC or ATE. When set to TRUE, only matched sets for treated units where treatment is applied continuously in the lead window are included in the results. Default is FALSE.

matching

logical indicating whether or not any matching on treatment history should be performed. This is primarily used for diagnostic purposes, and most users will never need to set this to FALSE. Default is TRUE.

listwise.delete

TRUE/FALSE indicating whether or not missing data should be handled using listwise deletion or the package's default missing data handling procedures. Default is FALSE.

use.diagonal.variance.matrix

TRUE/FALSE indicating whether or not a regular covariance matrix should be used in mahalanobis distance calculations during refinement, or if a diagonal matrix with only covariate variances should be used instead. In many cases, setting this to TRUE can lead to better covariate balance, especially when there is high correlation between variables. Default is FALSE. This argument is only necessary when refinement.method = mahalanobis and will have no impact otherwise.

restrict.control.period

(optional) integer specifying the number of pre-treatment periods that treated units and potentially matched control units should be non-NULL and in the control state. For instance, specifying 4 would mean that the treatment history cannot contain any missing data or treatment from t-4 to t.

placebo.test

logical TRUE/FALSE. indicates whether or not you want to be able to run a placebo test. This will add additional requirements on the data – specifically, it requires that no unit included in the matching/refinement process can having missing outcome data over the lag window. Additionally, you should not use the outcome variable in refinement when placebo.test = TRUE.

Details

PanelMatch identifies a matched set for each treated observation. Specifically, for a given treated unit, the matched set consists of control observations that have an identical treatment history up to a number of lag time periods. Researchers must specify lag. A further refinement of the matched set may be performed by setting a maximum size of each matched set, size.match (the maximum number of control units that can be matched to a treated unit). Users can also specify covariates that should be used to identify similar control units and a method for defining similarity/distance between units. This is done via the covs.formula and refinement.method arguments, respectively, which are explained in more detail below.

Value

PanelMatch() returns an object of class "PanelMatch". This is a list that contains a few specific elements: First, a matched.set object(s) that has the same name as the provided qoi if the qoi is "att", "art", or "atc". If qoi = "ate" then two matched.set objects will be attached, named "att" and "atc." Please consult the documentation for matched_set() to read more about the structure and usage of matched.set objects. Also, see the vignette page about matched.set objects for more information about these objects: vignette("matched_set_objects", package = "PanelMatch"). The PanelMatch object also has some additional attributes:

qoi

The qoi specified in the original function call

lead

the lead window specified in the original function call

forbid.treatment.reversal

logial value matching the forbid.treatment.reversal parameter provided in the function call.

outcome.var

character string matching the outcome variable provided in the original function call.

Author(s)

Adam Rauh <[e-mail]>, In Song Kim <[e-mail]>, Erik Wang <[e-mail]>, and Kosuke Imai <[e-mail]>

References

Imai, Kosuke, In Song Kim, and Erik Wang (2023)

Examples

dem.sub <- dem[dem[, "wbcode2"] <= 100, ]
# create subset of data for simplicity
PM.results <- PanelMatch(lag = 4, time.id = "year", unit.id = "wbcode2", 
                         treatment = "dem", refinement.method = "ps.match", 
                         data = dem.sub, match.missing = TRUE, 
                         covs.formula = ~ tradewb,
                         size.match = 5, qoi = "att",
                         outcome.var = "y", lead = 0:4, forbid.treatment.reversal = FALSE)