https://github.com/urbaninstitute/sedtr
https://github.com/urbaninstitute/sedtr
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/urbaninstitute/sedtr
- Owner: UrbanInstitute
- License: gpl-3.0
- Created: 2024-03-06T21:34:04.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-15T13:29:59.000Z (about 1 year ago)
- Last Synced: 2024-05-16T02:55:22.940Z (about 1 year ago)
- Language: R
- Size: 35.8 MB
- Stars: 8
- Watchers: 7
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# sedtR
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[](https://www.gnu.org/licenses/gpl-3.0)
### 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.
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.
## 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}
library(sedtR)
# Call sedt API with wrapper function
sedt_response <- call_sedt_api(
resource = "https://equity-tool-api.urban.org/sample-data/minneapolis_bikes.csv",
geo = "city",
acs_data_year = 2021
)
```
A resource can be a path or URL for an existing delimited (`csv` or `tsv`) file with coordinate columns, a spatial data file that can be read with `sf::read_sf()`, a `sf` object, or a URL for a FeatureLayer. Any input spatial data file or object *must* use POINT geometry.
`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. 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
```
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.
## 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 [email protected].