Getting Started with Benvos
In rbenvo: Built Environment Objects

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Introduction

This vignette serves to introduce the philosophy and structure of the rbenvo package, which implements the benvo class where benvo standards for Built Environment Object. This class makes working with built environment data easier by offering a convenient interface and methods for working with this type of relational data. We'll illustrate some of the very basics of how to use benvo's in this vignette as well as give some references as to how it might be used in other packages or settings.

We'll begin by loading the library and the two example data sets involving subjects living near Fast Food Restaurants (FFR). One of the two data sets will be for the subject level information, FFR_subjects, the other contains some measure of exposure (Distance/Time) that describe how long and/or how close subjects are located near the Built Environment Features (BEFs).

library(rbenvo)
library(ggplot2)
theme_set(theme_bw())
data("FFR_distances")
data("FFR_subjects")

The subject dataframe should look familiar. This is a tidy dataset with an ID and two subject-level measures: BMI and sex.

head(FFR_subjects,5)

The distance dataframe is a tidy "long" dataframe, containing multiple nearby BEF exposures per subject. Note that there must be at least two columns in every BEF dataset added to a benvo. One for the id and one for the Distance/Time data measured. Additionally, the latter columns must be named as "Distance" or "Time",as benvo's use these titles to perform their methods.

head(FFR_distances,5)

In order to create a benvo we'll pass the two dataframes to the benvo() function, wrapping the FFR_distances data frame in a list.

bdf <- benvo(subject_data = FFR_subjects,
             sub_bef_data = list(FFR=FFR_distances),by='id')
summary(bdf)

And that's it! That's all it takes to create a benvo, which is very particular kind of wrapper function for handling this specific kind of relational data in which there is a one-to-many relationship between the subject data frame and each BEF data frame.

Benvo Methods

While the summary method above gives us a look at the overall benvo object, if we simply print the benvo, we'll get a view of whatever data frame is active.

bdf

This notion of an active dataframe is inspired by (or borrowed from, depending on your perspective), the set-up of the tidygraph package which also has a particular kind of relational data structure.

Essentially, the active dataframe is that dataframe which is currently available for viewing and editing via the popular dplyr verbs.

bdf %>% activate(FFR) %>% filter(id<=5)

There are also a number of helpful plotting functions specific to built environment data built in, as one last descriptive offering, we can plot a point-range of the distances for each subject using the plot function and passing the BEF label we want plotted. You'll see that there are several observations missing, since not every subject lives near a FFR.

plot(bdf)

Other packages

While the above descriptive statistics are nice, the real power of using benvos is that they offer functions like joinvo to easily join the subject and bef data frames, which can be useful in setting up the data for models in other packages. Below we'll use the joinvo function, passing the benvo and bef character label for which table we want joined.

joinvo(bdf,"FFR")

Similarly, it is often the case - in my work at least - that some sort of model involving both the built environment data and the subject level data is needed. This means that information is incorporated at the subject level. This could manifest in, for example, the construction of a subject design matrix. Below I'll demonstrate how this works in a cross sectional as well as longitudinal framework, whilst highlighting how some of the previous functions take advantage of the longitudinal structure.

str(subject_design(bdf,BMI ~ sex))

Longitudinal Example

For our longitudinal example we'll look at a dataset that imagines a hypothetical set of grocery or "Healthy Food Stores"(HFS) near subjects. Subjects or grocery stores may move over time so this will be reflected in our data. Below we'll repeat the similar descriptives from above, highlighting the differences in a longitudinal benvo.

data("longitudinal_HFS")
longitudinal_HFS

summary(longitudinal_HFS)

plot(longitudinal_HFS,
     plotfun = "pointrange",
     term ="HFS",
     component = "Distance",
     p = 0.9)

Analogous to subject_design there is also the longitudinal_design function which effectively allows for lme4 style formulas to be used, incorporating subject or group level effects from the subject_data in the benvo and returning a glmod object along with the corresponding X and y design matrix and outcome vector, respectively.

str(longitudinal_design(longitudinal_HFS,BMI ~ sex + (1|id)),max.level=1)

Further Information

This completes this preliminary introduction to the rbenvo package. For current uses please see the rsstap or rstapDP packages. I've found that having these data structures greatly simplifies my code and allows for data to be organized more easily. If you're working with similar data, I hope you find the same!