README.Rmd

---
title: "attrbl"
output: github_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, collapse = FALSE, comment = "#>")
library(attrbl)
library(magrittr)
```

A tibble-like package for working with attributes and data frames.

***Warning: this package is in early development***

## Install

Install the dev version from Github

```{r, eval = FALSE}
if (!requireNamespace("devtools", quietly = TRUE)) {
  install.packages("devtools")
}
devtools::install_github("mkearney/attrbl")
```

## Use case

Let's say you have a list of two data frames. And each data frame contains a data frame attribute "users" with around 100 observations.

```{r, cache=TRUE}
## tweets data with users data attribute
rts <- list(
  rtweet::search_tweets("statistics", verbose = FALSE),
  rtweet::search_tweets("data science", verbose = FALSE))

## each object contains "users" data attribute with around 100 rows
rts %>%
  lapply(rtweet::users_data) %>%
  lapply(nrow)
```

When you bind the data frames using `do.call(..., rbind)`, it returns a "users" attribute. But it only has around 100 rows (it should be closer to 200). It completely **drops** the second "users" attribute!

```{r}
## base R's method
rts %>%
  do.call("rbind", .) %>%
  attr("users") %>%
  nrow()
```

When you bind the data frames using `dplyr::bind_rows(...)`, it **doesn't return** a "users" attribute at all!

```{r}
## dplyr's bind_rows method
rts %>%
  dplyr::bind_rows() %>%
  attr("users")
```

But when you bind the data frames using `attrbl::do_call_rbind(...)`, it not only **keeps** all "users" attributes. It binds them together for you!

```{r}
## attrbl's do_call_rbind method
rts %>%
  lapply(as_attrbl) %>%
  do_call_rbind() %>%
  attr("users") %>%
  nrow()
```

## Usage

### Bind data frames without losing attributes

When a `data.frame` is merged with `dplyr::bind_rows(...)`, it **loses** its attribute(s).

```{r}
## list of data frames
mtcars2 <- list(mtcars, mtcars)

## dplyr method
mtcars2 %>%
  dplyr::bind_rows() %>%
  attr("row.names")
```

When an `attrbl` is merged with `attrbl::do_call_rbind`, it **keeps** its attribute(s).

```{r}
## attrbl method
mtcars2 %>%
  lapply(as_attrbl) %>%
  do_call_rbind() %>%
  attr("row.names")
```

### Select attributes with `atselect`

Use `atselect` to select attributes the tidy way (no quotes required).

```{r}
atselect(mtcars, row.names, class)
```

### Add attributes with `add_attr`

Use `add_attr` to add one or more attributes to a data frame.

```{r}
mtcars %>%
  add_attr(seed = quote(set.seed(1234)), timestamp = Sys.time()) %>%
  attributes()
```

<!--
## Tidy evaluation reading materials

+ [Slides: Tidy Eval Hygienic FEXPRS](https://www.r-project.org/dsc/2017/slides/tidyeval-hygienic-fexprs.pdf)
+ [Thesis](https://web.wpi.edu/Pubs/ETD/Available/etd-090110-124904/unrestricted/jshutt.pdf)
+ [Blog post](http://www.onceupondata.com/2017/08/12/my-first-steps-into-the-world-of-tidyeval/)

-->