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

The goal of tidylog is to provide feedback about basic dplyr 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`:

```{r message=FALSE}
library("dplyr")
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) %>%
    filter(mpg > 15) %>%
    mutate(mpg_round = round(mpg)) %>%
    group_by(cyl, mpg_round) %>%
    tally() %>%
    filter(n >= 1)
```
Here, it might have been accidental that the last `filter` command had no effect.

## Installation

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

## More examples

### filter & distinct

```{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)
```

### mutate / transmute

```{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)
```

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

## Turning logging off, registering additional loggers

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

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 `print`,
simply overwrite the option:

```{r}
options("tidylog.display" = list(print))
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, 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(tidylog)
library(conflicted)
for (f in getNamespaceExports("tidylog")) {
    conflicted::conflict_prefer(f, 'tidylog', quiet = TRUE)
}
```