Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/domjarkey/relatable
Functions for Mapping Key-Value Pairs, Many-to-Many, One-to-Many, and Many-to-One Relations
https://github.com/domjarkey/relatable
Last synced: 3 months ago
JSON representation
Functions for Mapping Key-Value Pairs, Many-to-Many, One-to-Many, and Many-to-One Relations
- Host: GitHub
- URL: https://github.com/domjarkey/relatable
- Owner: domjarkey
- License: other
- Created: 2018-01-25T21:07:57.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2018-02-01T07:38:01.000Z (almost 7 years ago)
- Last Synced: 2024-07-10T17:26:38.403Z (4 months ago)
- Language: R
- Homepage:
- Size: 187 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
Awesome Lists containing this project
README
---
title: relatable
output: github_document
---
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-"
)
```
`relatable` provides two easy-to-use, robust functions for mapping from a vector of keys to a vector of values, as well as creating and applying more sophisticated mappings, such as many-to-many, one-to-many, and many-to-one relations. These are primarily designed with two goals in mind:
1. Producing reusable code that is easier to write and read.
2. Ensuring relations conform to specified restrictions, for example injectivity or surjectivity, and safely handle nonstandard mappings, including unexpected inputs, NAs, heterogeneous lists containing multiple variable types including other lists, and mappings between vectors of uncertain or unequal lengths.
## Installation
```{r installation, eval = FALSE}
# Install from CRAN:
install.packages("relatable")
# The development version is also available from GitHub:
# install.packages("devtools")
devtools::install_github("domjarkey/relatable")
```
## Usage
For more detailed information, see the `relatable` help documentation [online](https://cran.r-project.org/web/packages/relatable/relatable.pdf) or with `?relate` in R, as well as the [Relation Types and Restrictions](https://cran.r-project.org/web/packages/relatable/vignettes/restrictions.html) vignette (`vignette("restrictions")` in R).
### A simple key-value dictionary
For basic use, `relate` maps a vector of inputs `X` from their position in a vector of keys `A` to the corresponding value in vector `B`. `relation` returns a function that performs the same mapping for repeated usage.
```{r key_value}
library(relatable)
# Use relate() for a one-off mapping of inputs from one vector to another
relate(c("March", "April", "May"), month.name, month.abb)
# Create a reusable dictionary function with relation().
chem_symbol <- relation(elements$Name, elements$Symbol)
chem_symbol(c("Iron", "Lithium", "Sodium"))
# Unexpected inputs return by default, but this can be changed
chem_symbol(c("Sodium", "Adamantium"))
# relate() and relation() have optional arguments to determine the type of
# output and default return values.
chem_symbol <- relation(elements$Name, elements$Symbol,
default = "Unknown", named = TRUE)
chem_symbol(c("Sodium", "Adamantium"))
```
### Ensure expected inputs while manipulating larger data sets
When working with unfamiliar data it can be easy to forget to account for all possible values a variable might take, or worse, typographical entry errors. Using `allow_default = FALSE`, `relatable` functions can flag unexpected inputs to ensure these problems don't arise.
In the following example we use the [DWNOMINATE](https://voteview.com/about) data set assembled by Poole and Rosenthal et al, which estimates the ideological positions of US politicians. Suppose we want to create a new column for our data frame indicating political party by colour (red for Republicans, blue for Democrats):
```{r data_frames}
## Obtain data for senators in the 113th Congress, spanning 2013-2015.
US_senate_113 <- subset(
foreign::read.dta("ftp://k7moa.com/junkord/SL01113D21_BSSE_12.DTA"),
cong == 113
)
## Setting allow_default = FALSE ensures we will be notified of any funny inputs.
US_senate_113$colour <- relate(
X = US_senate_113$party,
A = c(100, 200),
B = c("blue", "red"),
allow_default = FALSE
)
## Woops! Looks like we forgot to allow for the two Independent Senators in the data set,
## coded as 328. Let's try again:
US_senate_113$colour <- relate(
X = US_senate_113$party,
A = c(100, 200, 328),
B = c("blue", "red", "gray30"),
allow_default = FALSE
)
```
No warnings, no worries!
```{r senate_plot}
with(
US_senate_113,
plot(
x = dwnom1,
y = dwnom2,
col = colour,
main = "Ideal Points of US Senators",
xlab = "Economic Issues",
ylab = "Social Issues"
)
)
```