-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
111 lines (76 loc) · 5.55 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# sedtR
<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
<!-- badges: end -->
### Purpose of `sedtR`:
The `sedtR` package allows R programmers to easily interact with Urban's [Spatial Equity Data Tool](https://apps.urban.org/features/equity-data-tool/) (SEDT) [public application programming interface](https://ui-research.github.io/sedt_documentation/api_documentation.html) (API).
## Background
### What is the Spatial Equity Data Tool?
The SEDT enables local, state, and federal leaders, as well as the general public, to upload their own point spatial data and quickly assess whether place-based programs and resources – such as parks, libraries, wi-fi hotspots or electric vehicle charging stations – are equitably distributed across neighborhoods and demographic groups.
The tool – launched in 2020 and expanded in 2021 – has been used by a wide variety of experts and nonexperts alike to assess equity in the distribution of local programs and resources. For example, the Bloomington Pedestrian and Bicycle Safety Commission analyzed sidewalk funding allocations, and advocates in Cincinnati identified economic and racial inequities in car crash locations.
### Why Create a Public API and `sedtR`:
Through engagements with local government and nonprofit users, we identified a key barrier. Organizations wanted to embed the SEDT within their own tools and data workflows and thus make the Tool a core part of institutional processes. However, before the API's release in March of 2024, Tool users would have had to visit Urban’s website and use the GUI interface to upload one dataset at a time whenever new analyses were needed. The release of the API overcomes this barrier by allowing programmatic access to the Tool. We wrote `sedtR` to wrap the public API's endpoints in user-friendly R code. We are hopeful that `sedtR` makes it easy for researchers, analysts, and policymakers to incorporate SEDT calculations into R workflows.
## Installation
You can install the development version of sedtR from [GitHub](https://github.com/) with:
``` r
# install.packages("devtools")
devtools::install_github("UrbanInstitute/sedtR")
```
## Example
The following example illustrates using the `call_sedt_api()` function on Minneapolis, MN bikeshare data stored on the Urban Institute's [Data Catalog](https://datacatalog.urban.org/).
``` {r, echo = FALSE, message = FALSE, warning = FALSE}
library(sedtR)
withr::with_tempdir({
# Download bicycle data:
download.file(
"https://equity-tool-api.urban.org/sample-data/minneapolis_bikes.csv",
destfile = "bikes.csv")
# Call sedt API with wrapper function
sedt_response <- sedtR::call_sedt_api(
resource_file_path = here::here("bikes.csv"),
resource_lat_column = "lat",
resource_lon_column = "lon",
geo = "city",
acs_data_year = "2021")
})
```
`call_sedt_api()` returns a list object that contains a `sf` object storing the geographic disparity scores:
```{r}
sedt_response$geo_bias_data |>
head()
```
A data frame with demographic information used in the analysis is also returned:
```{r}
sedt_response$demo_bias_data |>
head()
```
The package allows users to visualize the geographic disparity scores and demographic disparity scores with `create_map()` and `create_demo_chart()`, respectively. By default, these functions do not save the resulting images, but both provide arguments (`save_map` and `save_chart`) which take logicals and allow a user to save the outputted visualization. Like the interactive visualizations on the [SEDT website] (https://apps.urban.org/features/equity-data-tool/), these functions allow users to visualize different geographic or demographic disparity scores. `create_map()` allows interactive or static visualizations.
```{r}
create_map(sedt_response$geo_bias_data,
interactive = FALSE, # optional, defaults to TRUE
save_map = FALSE, #optional, defaults to FALSE. If TRUE, provide file_path
col_to_plot = "diff_pop") #optional, default is "diff_pop"
```
```{r}
create_demo_chart(sedt_response$demo_bias_data,
group = "total", # optional, default is "total"
save_chart = FALSE) # optional, default is FALSE. If TRUE provide file_path
```
## Where Can I Learn More:
The Spatial Equity Data Tool has comprehensive documentation in the form of an [online book](https://ui-research.github.io/sedt_documentation/). Most notably, there is a chapter [specifically devoted to the API](https://ui-research.github.io/sedt_documentation/api_documentation.html). It provides more in-depth `sedtR` code and outputs.
Other particularly relevant chapters cover [common API errors and warnings](https://ui-research.github.io/sedt_documentation/common_errors_warnings.html), [how to interpret Tool results](https://ui-research.github.io/sedt_documentation/interpreting_results.html), and a [description of data appropriate for the Tool](https://ui-research.github.io/sedt_documentation/resource_datasets.html).
## Feedback:
Please provide feedback by opening [GitHub Issues](https://github.com/UrbanInstitute/sedtR/issues) or contacting us at sedt@urban.org.