Step 1. Converting data to hyperframes

The first step of spatiotemporal causal inference is to convert dataframes into an object called hyperframe. Essentially, a hyperframe is a dataframe with each cell being any types of objects, including pixel images and point processes. Users can convert dataframes into hyperframes easily with a function called get_hfr().

1 Data

To illustrate the usage of our package, we use two datasets: airstrikes and insurgencies. These two datasets are spatiotemporal data of airstrikes and insurgencies in Iraq from March 2007 to June 2007. It should be noted that location information is saved in the decimal degree format. To use geocausal, if the original data is not in the decimal degree format, it is recommended that users convert it to the decimal degree format. Additionally, time variable must be numerics.

2 Converting data to hyperframes

Our first task is to convert data to a collection of point processes. Intuitively, we want to generate maps of all the locations of airstrikes and insurgencies for all subtypes and all dates. For dates and subtypes with no observations, we want to generate an empty map.

A key function for this step is get_hfr(). This function does the following:

  1. aggregating all observations by dates and subtypes, and converting them to a point process;
  2. identifying dates with zero observations and generating an empty map for those dates; and
  3. sorting everything and creating a hyperframe.
# 1. Treatment data

## 1-1. Convert time variable to numerics
airstrikes$time <- as.numeric(airstrikes$date - min(airstrikes$date) + 1)

## 1-2. Generate a hyperframe
treatment_hfr <- get_hfr(data = airstrikes,
                         subtype_column = "type",
                         window = iraq_window,
                         time_column = "time",
                         time_range = c(1, max(airstrikes$time)),
                         coordinates = c("longitude", "latitude"),
                         combined = TRUE)
#> Converting the data to ppp objects...
#> Converting the data to a hyperframe...
#> Generating a hyperframe of point processes...

# 2. Outcome data

## 2-1. Convert time variable to numerics
insurgencies$time <- as.numeric(insurgencies$date - min(insurgencies$date) + 1)

outcome_hfr <- get_hfr(data = insurgencies,
                       subtype_column = "type",
                       window = iraq_window,
                       time_column = "time",
                       time_range = c(1, max(insurgencies$time)),
                       coordinates = c("longitude", "latitude"),
                       combined = TRUE)
#> Converting the data to ppp objects...
#> Converting the data to a hyperframe...
#> Generating a hyperframe of point processes...

# 3. Combine two hyperframes
dat_hfr <- spatstat.geom::cbind.hyperframe(treatment_hfr, outcome_hfr[, -1])
names(dat_hfr)[names(dat_hfr) == "all_combined"] <- "all_treatment"
names(dat_hfr)[names(dat_hfr) == "all_combined.1"] <- "all_outcome"

The output is a hyperframe, with each element being a point process, denoted as (ppp) in the output.

head(dat_hfr)
#> Hyperframe:
#>   time Airstrike   SOF all_treatment   SAF   IED all_outcome
#> 1    1     (ppp) (ppp)         (ppp) (ppp) (ppp)       (ppp)
#> 2    2     (ppp) (ppp)         (ppp) (ppp) (ppp)       (ppp)
#> 3    3     (ppp) (ppp)         (ppp) (ppp) (ppp)       (ppp)
#> 4    4     (ppp) (ppp)         (ppp) (ppp) (ppp)       (ppp)
#> 5    5     (ppp) (ppp)         (ppp) (ppp) (ppp)       (ppp)
#> 6    6     (ppp) (ppp)         (ppp) (ppp) (ppp)       (ppp)

3 Visualization

To visualize hyperframes, users can employ vis_hfr().

vis_hfr(hfr = dat_hfr,
        subtype_column = c("Airstrike", "SOF"),
        time_column = "time",
        range = c(1, 5),
        combined = TRUE)
#> The legacy packages maptools, rgdal, and rgeos, underpinning the sp package,
#> which was just loaded, will retire in October 2023.
#> Please refer to R-spatial evolution reports for details, especially
#> https://r-spatial.org/r/2023/05/15/evolution4.html.
#> It may be desirable to make the sf package available;
#> package maintainers should consider adding sf to Suggests:.
#> The sp package is now running under evolution status 2
#>      (status 2 uses the sf package in place of rgdal)