README.Rmd

---
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%"
)
```

# codebreak

<!-- badges: start -->

[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) [![R-CMD-check](https://github.com/nt-williams/dictionary/workflows/R-CMD-check/badge.svg)](https://github.com/nt-williams/codebreak/actions) [![codecov](https://codecov.io/gh/nt-williams/codebreak/branch/main/graph/badge.svg?token=QGGA7OE5UY)](https://codecov.io/gh/nt-williams/codebreak)

<!-- badges: end -->

Quickly and easily label your data using codebooks saved as a [YAML](https://yaml.org/) text file.

## Installation

```{r eval=FALSE}
remotes::install_github("nt-williams/codebreak")
```

or

```{r eval=FALSE}
# Install 'codebook' from 'nt-williams' universe
install.packages('codebreak', repos = 'https://nt-williams.r-universe.dev')
```

## Applying a code book

```{r}
some_data <- data.frame(
     x = c(1, 2, 5, 3, 4, 1),
     y = c(0, 1, 1, 0, 1, 9), 
     z = c(5.2, 3.1, 5.6, 8.9, 9.0, 7.2), 
     w = c(1, 1, 0, 1, 1, 1)
)
```

Codebooks are created as YAML text files and are saved in the project directory (or somewhere else) as `codebook.yml` (or as something else).

```{yaml}
x:
  label: Variable X # include meaningful variable descriptions
  cb:
    1: These        # convert variable codes to labels
    2: Are
    3: Random
    4: Character
    5: Labels

"y":
  label: Variable Y
  cb: &binary        # reduce repetition with anchors
    0: "No"
    1: "Yes"
    9: null          # account for coded missing values

z:
  label: Variable Z

w:
  label: Variable W
  cb: *binary

```

Import and apply the codebook to the data:

```{r}
cb <- codebreak::Codebook$new(system.file("codebook.yml", package = "codebreak"))
cb

cb$decode(some_data)
```

Rename columns based on the codebook labels:

```{r}
cb$label(some_data)
```

Apply the codebook and rename columns:

```{r}
cb$decode(some_data, label = TRUE)
```

## Integration with the `labelled` package

`decode()` and `label()` can return data with the codebook applied using the [`labelled`](https://CRAN.R-project.org/package=labelled) package by setting `as_labelled = TRUE`.

```{r}
some_data <- tibble::as_tibble(some_data)

cb$decode(some_data, as_labelled = TRUE)
```