# Estimate Treatment Effect for Sliding Spatiotemporal Windows 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). ```r 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, ...) ``` ## 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 . - ``...``: 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. ## Returns 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. - **parameters**: `list` of all arguments passed to the method. - **call**: the call. ## References Schutte, S., Donnay, K. (2014). ``Matched wake analysis: Finding causal relationships in spatiotemporal event data.'' **Political Geography** 41:1-10. ## Author(s) Sebastian Schutte and Karsten Donnay. ## See Also `mwa-package`, `slidingWake`, `slideWakeMatch`, `print.matchedwake`, `summary.matchedwake`, `plot.matchedwake` ## Examples ```r # 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) ```

matchedwake function