rcoder/README.Rmd at main · nyuglobalties/rcoder · GitHub

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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
---
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%"
)
```

# rcoder

> rcoder outlines a lightweight data structure that captures categorical codings
and easily converts them to other implementations.

<!-- badges: start -->
[![R build status](https://github.com/nyuglobalties/rcoder/workflows/R-CMD-check/badge.svg)](https://github.com/nyuglobalties/rcoder/actions)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
<!-- badges: end -->

## Usage

rcoder's main functions are `coding()` and `code()`. `code()` maps a character-valued key to some value to represent a categorical level.

```{r}
library(rcoder)
library(magrittr)

code("Yes", 1)
```

`code()` objects can hold an arbitrary amount of metadata. Useful pieces of information to know are descriptions of what levels represent (in case the label doesn't have enough information) and whether or not the value represents a missing value.

```{r}
code(
  "No response",
  -99,
  description = "Surveyed individual ignored question when asked",
  missing = TRUE
)
```

`coding()` is a collection of `code()` objects that represents the full set of values for a categorical variable.

```{r}
coding(
  code("Don't know", 0, missing = TRUE),
  code("Never", 1),
  code("Rarely", 2),
  code("Sometimes", 3),
  code("Frequently", 4),
  code("Always", 5),
  code("No response", -99, missing = TRUE),
  code("Refused", -88, missing = TRUE),
  code("Absent", -77, missing = TRUE)
)
```

`coding()` objects are designed to be an intermediate representation of categorical data so that they can be converted into different representations on the fly, e.g. ODK XLSForm choices and STATA/SPSS columns via [`haven`](https://haven.tidyverse.org/).

```{r}
coding(
  code("Never", 1),
  code("Rarely", 2),
  code("Sometimes", 3),
  code("Frequently", 4),
  code("Always", 5),
  .label = "frequency"
) %>%
  coding_to_odk()
```

To facilitate recoding, `coding()` objects link to one another through the `code()` labels. If multiple values are collapsed into one, use the `links_from` parameter to identify which values are combined into one.

```{r}
original_coding <- coding(
  code("No", 0L),
  code("Yes", 1L),
  code("No response", -99L, missing = TRUE),
  code("Refused", -88L, missing = TRUE),
  code("Absent", -77L, missing = TRUE)
)

new_coding <- coding(
  code("No", 0L),
  code("Yes", 1L),
  code("Missing", NA, links_from = c("No response", "Refused", "Absent"))
)

new_coding %>%
  link_codings(original_coding)
```

These linked codings can be converted into a function that accepts a vector and returns a recoded vector.

```{r}
new_coding %>%
  link_codings(original_coding) %>%
  make_recode_query()
```

## Installation

Install rcoder from CRAN with:

``` r
install.packages("rcoder")
```

To get the latest stable changes that may not be on CRAN, install from the nyuglobalties r-universe with:

```r
install.packages("rcoder", repos = "https://nyuglobalties.r-universe.dev")
```

Finally, get the development version straight from GitHub:

```r
# install.packages("remotes")
remotes::install_github("nyuglobalties/rcoder")
```