matchedwake: Estimate Treatment Effect for Sliding Spatiotemporal Windows

In css-konstanz/mwa: Causal Inference in Spatiotemporal Event Data

Estimate Treatment Effect for Sliding Spatiotemporal Windows

Description

This function performs the Matched Wake Analysis (mwa), which consists of two steps: counts for previous and posterior events are established for different spatial and temporal offsets from treatment and control events. After that, the treatment effect is estimated in a difference-in-differences regression design. For performance reasons, the iterative counting is done in Java using the rJava interface.

IMPORTANT: The size of the Java heap space has to be set before first calling the package via library(mwa) since JVM size cannot change once it has been initialized. This also implies that R has to be restarted if another library was already using a JVM in order for the heap space option to have any effect. To set the heap space to 1 GB, for example, use options(java.parameters = "-Xmx1g") (512 MB is the default size).

Usage

matchedwake(data, t_window, spat_window, treatment, control,
            dependent, matchColumns, t_unit = "days", estimation = "lm",
	    formula = "dependent_post ~ dependent_pre + treatment",
            weighted = FALSE, estimationControls = c(), TCM = FALSE,
            deleteSUTVA = FALSE, alpha1 = 0.05, alpha2 = 0.1,
            match.default = TRUE, match.details = FALSE, ...)

Arguments

data	data.frame containing the observations. See Details.
t_window	specification of temporal windows in t_units. See Details.
spat_window	specification of spatial windows in kilometers. See Details.
treatment	vector of Strings identifying which type of events serve as treatments. See Details.
control	vector of Strings identifying which type of events serve as controls. See Details.
dependent	vector of Strings identifying which type of events are affected by treatment. See Details.
matchColumns	vector of Strings indicating the columns to match on. See Details.
t_unit	String specifying the temporal units to be used, either "days", "hours", "mins" or "secs". Default = "days". See Details.
estimation	String specifying method used for estimation, "lm", "att" or "nb". Default = "lm". See Details.
formula	String specifying the model used for estimation. Default = "dependent_post ~ dependent_pre + treatment". See Details.
weighted	Boolean specifying whether regression is weighted (only affects estimations using "lm" or "att"). Default = FALSE.
estimationControls	vector of Strings indicating additional control dimensions to be included in the estimation. See Details.
TCM	Boolean to select whether the method should match on counts of previous treatment and control instances. Default = FALSE.
deleteSUTVA	Boolean to select whether overlapping treatment and control episodes are deleted. Default = FALSE.
alpha1	first significance level used for the analysis and plots. Default = 0.05.
alpha2	second significance level used for the analysis and plots. Default = 0.1.
match.default	Boolean to select whether observations are matched using cem. Default = TRUE.
match.details	Boolean to select whether detailed matching statistics are returned from cem. Default = FALSE.
...	optional parameters that can be passed to the methods used for matching and estimation. See Details.

Details

The method expects data to be a data.frame. Dates must be given in column timestamp and formatted as a date string with format "YYYY-MM-DD hh:mm:ss". Alternatively, a POSIX Date can be specified using the same format. data must also contain two entries called lat and lon for the geo location of each entry.

t_window specifies the minimal and maximal temporal window sizes and corresponding steps used in the iteration. Required syntax is c(min_window, max_window, step_size) with step_size in units of t_unit. The spatial window spat_window is specified in the same way with kilometers as units.

treatment, control and dependent define which category of events is considered to be treatment, control and dependent cases respectively. The required syntax is c(column_name, value) where column_name must be entered as String and value can be Numeric, Boolean, or a String.

matchColumns selects the columns in data used for matching. Matching variables are expected to be coded together with every treatment and control type event and are assumed to reflect a set of suitable matching variables (what is suitable will, of course, vary from case to case).

The optional argument t_unit specifies the temporal resolution for which the analysis is to be conducted, one of either "days", "hours", "mins" or "secs". If the time stamps provided in data are more precise than the resolution they are truncated accordingly.

mwa estimates treatment effects using a diff-in-diffs regression design. By default this is specified as "dependent_post ~ dependent_pre + treatment" (where “pre” and “post” refer to pre and post intervention). Alternatively, "dependent_post - dependent_pre ~ treatment" is accepted. Only those two input specifications are allowed, any other input will result in an error.

Three different estimation approaches can be chosen using estimation: a linear model ("lm", stats), all models available through ("att", cem) or a count dependent model ("glm.nb", MASS). For regressions using "lm" or "att" weighted sets whether or not the regression is weighted by the number of treatment vs. control cases. Additional control variables can be specified via estimationControls. For example, if estimationControls = c("covariate1"), the package automatically modifies the default estimation formula to "dependent_post ~ dependent_pre + covariate1 + treatment" (analogously for the other specification). In this case the output then also not only returns the estimate and p value for treatment but further returns the coefficients and p values for all additional control variables.

The package supports full inheritance for optional arguments of the following methods: cem and att (cem), lm (stats), glm.nb (MASS). To guarantee unique inputs for each method, options have to entered into matchedwake() using a prefix that consists of the method name separated by “.”. For example, in order for cem to return an exactly balanced dataset simply add cem.k2k = TRUE as optional argument.

Value

Returns an object of class matchedwake, which is a list of objects with the following slots:

estimates	data.frame with estimates and p values for all spatial and temporal windows considered. For estimation = "lm" it also returns a pseudo R^2 value. If additional control dimensions were included in the estimation, it further returns the corresponding coefficients and p values.
matching	data.frame with detailed matching statistics for all spatial and temporal windows considered. Returns the number of control and treatment episodes, L1 metric, percent common support. All values are given both pre and post matching.
SUTVA	data.frame with detailed statistics on the degree of overlaps of the spatiotemporal cylinders. Returns the fraction of cases in which two or more treatment (or control) episodes overlap (“SO”: same overlap) and the fraction of overlapping treatment and control episodes (“MO”: mixed overlap). All values are given pre and post matching and for the full time window.
wakes	data.frame providing the information for the spatiotemporal cylinders (or wakes) for all spatial and temporal windows considered. Returns the eventID (i.e. the index of the event in the time-ordered dataset), treatment (1: treatment episode, 0: control episode), counts of dependent events, overlaps (“SO” and “MO”) pre and post intervention, and the matching variables.
matched	data.frame with details on which observations were matched for all spatial and temporal windows considered. Returns the eventID (i.e. the index of the event in the time-ordered dataset), treatment (1: treatment episode, 0: control episode) and matched (1: matched, 0: not matched).
bins	data.frame with details for the bins used in cem matching for all spatial and temporal windows considered. Returns the bin information from cem (variable “breaks”) for each matchColumns.
parameters	list of all arguments passed to the method.
call	the call.

Author(s)

Sebastian Schutte and Karsten Donnay.

References

Schutte, S., Donnay, K. (2014). “Matched wake analysis: Finding causal relationships in spatiotemporal event data.” Political Geography 41:1-10.

See Also

mwa-package, slidingWake, slideWakeMatch, print.matchedwake, summary.matchedwake, plot.matchedwake

Examples

# Loading sample data
data(mwa_data)

# Specify required parameters:
# - 2 to 10 days in steps of 2
t_window <- c(2,10,2)
# - 2 to 10 kilometers in steps of 2
spat_window <- c(2,10,2)
# - column and entries that indicate treatment events 
treatment <- c("type","treatment")
# - column and entries that indicate control events 
control  <- c("type","control")
# - column and entries that indicate dependent events 
dependent <- c("type","dependent")
# - columns to match on
matchColumns <- c("match1","match2")

# Specify optional parameters:
# - use weighted regression (default estimation method is "lm")
weighted <- TRUE
# - temporal units
t_unit <- "days" 
# - match on counts of previous treatment and control events
TCM <- TRUE


# Execute method:
results <- matchedwake(mwa_data, t_window, spat_window, treatment, control, dependent,
                       matchColumns, weighted = weighted, t_unit = t_unit, TCM = TCM)

# Plot results:
plot(results)

# Return detailed summary of results:
summary(results, detailed = TRUE)

css-konstanz/mwa documentation built on Sept. 30, 2022, 4:39 a.m.