README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```
# tidylog

[![CRAN Version](https://www.r-pkg.org/badges/version/tidylog)](https://CRAN.R-project.org/package=tidylog)
[![Build Status](https://travis-ci.org/elbersb/tidylog.svg?branch=master)](https://travis-ci.org/elbersb/tidylog)
[![Coverage status](https://codecov.io/gh/elbersb/tidylog/branch/master/graph/badge.svg)](https://codecov.io/github/elbersb/tidylog?branch=master)

The goal of tidylog is to provide feedback about dplyr and tidyr operations. It provides simple wrapper functions for the most common functions, such as `filter`, `mutate`, `select`, `full_join`, and `group_by`.

## Example

Load `tidylog` after `dplyr` and/or `tidyr`:

```{r message=FALSE, warning=FALSE}
library("dplyr")
library("tidyr")
library("tidylog", warn.conflicts = FALSE)
```

Tidylog will give you feedback, for instance when filtering a data frame:

```{r}
filtered <- filter(mtcars, cyl == 4)
```

This can be especially helpful in longer pipes:

```{r}
summary <- mtcars %>%
    select(mpg, cyl, hp, am) %>%
    filter(mpg > 15) %>%
    mutate(mpg_round = round(mpg)) %>%
    group_by(cyl, mpg_round, am) %>%
    tally() %>%
    filter(n >= 1)
```
Here, it might have been accidental that the last `filter` command had no effect.

## Installation

Download from CRAN:

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

Or install the development version:

``` r
devtools::install_github("elbersb/tidylog")
```

## More examples

### filter, distinct, drop_na

```{r}
a <- filter(mtcars, mpg > 20)
b <- filter(mtcars, mpg > 100)
c <- filter(mtcars, mpg > 0)
d <- filter_at(mtcars, vars(starts_with("d")), any_vars((. %% 2) == 0))
e <- distinct(mtcars)
f <- distinct_at(mtcars, vars(vs:carb))
g <- top_n(mtcars, 2, am)

h <- drop_na(airquality)
i <- drop_na(airquality, Ozone)
k <- drop_na(airquality, Wind, Temp, Month, Day)
```

### mutate, transmute, replace_na, fill

```{r}
a <- mutate(mtcars, new_var = 1)
b <- mutate(mtcars, new_var = runif(n()))
c <- mutate(mtcars, new_var = NA)
d <- mutate_at(mtcars, vars(mpg, gear, drat), round)
e <- mutate(mtcars, am_factor = as.factor(am))
f <- mutate(mtcars, am = as.factor(am))
g <- mutate(mtcars, am = ifelse(am == 1, NA, am))
h <- mutate(mtcars, am = recode(am, `0` = "zero", `1` = NA_character_))

i <- transmute(mtcars, mpg = mpg * 2, gear = gear + 1, new_var = vs + am)

j <- replace_na(airquality, list(Solar.R = 1))
k <- fill(airquality, Ozone)
```

### select

```{r}
a <- select(mtcars, mpg, wt)
b <- select(mtcars, matches("a"))
c <- select_if(mtcars, is.character)
```

### joins

```{r}
a <- left_join(band_members, band_instruments, by = "name")
b <- full_join(band_members, band_instruments, by = "name")
c <- anti_join(band_members, band_instruments, by = "name")
```

### summarize

```{r}
a <- mtcars %>%
    group_by(cyl, carb) %>%
    summarize(total_weight = sum(wt))

b <- iris %>%
    group_by(Species) %>%
    summarize_all(list(~min, ~max))
```

### tally, count, add_tally, add_count

```{r}
a <- mtcars %>% group_by(gear, carb) %>% tally
b <- mtcars %>% group_by(gear, carb) %>% add_tally()

c <- mtcars %>% count(gear, carb)
d <- mtcars %>% add_count(gear, carb, name = "count")
```

### gather, spread

```{r}
long <- mtcars %>%
    mutate(id = 1:n()) %>%
    gather("col", "data", -id)
wide <- long %>%
    spread(col, data)
```

## Turning logging off, registering additional loggers

To turn off the output for just a particular function call, you can simply call the dplyr and tidyr functions
directly, e.g. `dplyr::filter` or `tidyr::drop_na`.

To turn off the output more permanently, set the global option `tidylog.display` to an empty list:

```{r}
options("tidylog.display" = list())  # turn off
a <- filter(mtcars, mpg > 20)

options("tidylog.display" = NULL)    # turn on
a <- filter(mtcars, mpg > 20)
```

This option can also be used to register additional loggers. The option `tidylog.display` expects
a list of functions. By default (when `tidylog.display` is set to NULL), tidylog
will use the `message` function to display the output, but if you prefer a more colorful output,
simply overwrite the option:

```{r}
library("crayon")  # for terminal colors
crayon <- function(x) cat(red$bold(x), sep = "\n")
options("tidylog.display" = list(crayon))
a <- filter(mtcars, mpg > 20)
```

To print the output both to the screen and to a file, you could use:

```{r}
log_to_file <- function(text) cat(text, file = "log.txt", sep = "\n", append = TRUE)
options("tidylog.display" = list(message, log_to_file))
a <- filter(mtcars, mpg > 20)
```

## Namespace conflicts

Tidylog redefines several of the functions exported by dplyr and tidyr, so it should be loaded last, otherwise there will be no output. A more explicit way to resolve namespace conflicts is to use the [conflicted](https://CRAN.R-project.org/package=conflicted) package:

``` r
library("dplyr")
library("tidyr")
library("tidylog")
library("conflicted")
for (f in getNamespaceExports("tidylog")) {
    conflicted::conflict_prefer(f, "tidylog", quiet = TRUE)
}
```