Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/echasnovski/keyholder
Store Data About Rows
https://github.com/echasnovski/keyholder
Last synced: 2 months ago
JSON representation
Store Data About Rows
- Host: GitHub
- URL: https://github.com/echasnovski/keyholder
- Owner: echasnovski
- License: other
- Created: 2017-07-09T13:20:23.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-03-12T09:59:10.000Z (almost 2 years ago)
- Last Synced: 2024-10-13T12:29:46.044Z (3 months ago)
- Language: R
- Homepage: https://echasnovski.github.io/keyholder/
- Size: 303 KB
- Stars: 7
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - echasnovski/keyholder - Store Data About Rows (R)
README
---
output: github_document
---
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
options(tibble.print_min = 3, tibble.print_max = 3)
```
# keyholder
[](https://travis-ci.org/echasnovski/keyholder)
[](https://github.com/echasnovski/keyholder/actions)
[](https://codecov.io/github/echasnovski/keyholder?branch=master)
[](https://cran.r-project.org/package=keyholder)
[](https://CRAN.R-project.org/package=keyholder)
[](https://cran.r-project.org/package=keyholder)
`keyholder` is a package for storing information (*keys*) about rows of data
frame like objects. The common use cases are to track rows of data without
modifying it and to backup and restore information about rows. This is done with
creating a class __keyed_df__ which has special attribute "keys". Keys are
updated according to changes in rows of reference data frame.
`keyholder` is designed to work tightly with [dplyr](https://dplyr.tidyverse.org/) package. All its one- and two-table verbs update keys properly.
## Installation
You can install current stable version from CRAN with:
```{r cran-installation, eval = FALSE}
install.packages("keyholder")
```
Also you can install development version from github with:
```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("echasnovski/keyholder")
```
## Usage
`keyholder` provides a set of functions to work with keys:
- Set keys with `assign_keys()` and `key_by()`.
- Get all keys with `keys()`. Get one specific key with `pull_key()`.
- Restore information stored in certain keys with `restore_keys()` and its
scoped variants (`*_all()`, `*_if()` and `*_at()`).
- Rename certain keys with `rename_keys()` and its scoped variants.
- Remove certain keys with `remove_keys()` and its scoped variants. Completely
unkey object with `unkey()`.
- Track rows with `use_id()` and special `.id` key.
For more detailed explanations and examples see package vignettes and
documentation.
### Common use cases
```{r setup, message = FALSE}
library(dplyr)
library(keyholder)
mtcars_tbl <- mtcars %>% as_tibble()
```
- Track rows without modifying data:
```{r usage track rows}
mtcars_tbl_id <- mtcars_tbl %>%
# Creates a key '.id' with row index
use_id() %>%
filter(vs == 1, gear == 4)
mtcars_tbl_id
mtcars_tbl_id %>% pull_key(.id)
```
- Backup and restore information:
```{r usage backup and restore}
mtcars_tbl_keyed <- mtcars_tbl %>%
# Backup
key_by(vs, am, gear) %>%
# Modify
mutate(vs = am) %>%
group_by(vs) %>%
mutate(gear = max(gear))
# Restore with recomputing groups
mtcars_tbl_restored <- mtcars_tbl_keyed %>% restore_keys_all()
mtcars_tbl_grouped <- mtcars_tbl %>% group_by(vs)
all.equal(
as.data.frame(mtcars_tbl_restored),
as.data.frame(mtcars_tbl_grouped),
check.attributes = FALSE
)
all.equal(
group_indices(mtcars_tbl_restored),
group_indices(mtcars_tbl_grouped)
)
# Restore with renaming
mtcars_tbl_keyed %>%
restore_keys_at("vs", .funs = list(~ paste0(., "_old")))
```
- As a special case of previous usage one can also hide columns for convenient
use of `dplyr`'s *_if scoped variants of verbs:
```{r usage dplyr _if scoped}
# Restored key goes to the end of the tibble
mtcars_tbl %>%
key_by(mpg, .exclude = TRUE) %>%
mutate_if(is.numeric, round, digits = 0) %>%
restore_keys_all()
```