---
title: "Catalog of janitor functions"
date: "`r Sys.Date()`"
output:
  rmarkdown::github_document:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{Introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(collapse = T, comment = "#>")
library(janitor)
```
The janitor functions expedite the initial data exploration and cleaning that comes with any new data set.  This catalog describes the usage for each function.

# Major functions
Functions for everyday use.

## Cleaning

### Clean data.frame names with `clean_names()`
Call this function every time you read data.

It works in a `%>%` pipeline, and handles problematic variable names, especially those that are so well preserved by `readxl::read_excel()` and `readr::read_csv()`.

+ Returns names with only lowercase letters, with `_` as a separator
+ Handles special characters and spaces
+ Appends numbers to duplicated names
+ Converts "%" to "percent" to retain meaning

```{r, message = FALSE, warning = FALSE}
# Load dplyr for the %>% pipe
library(dplyr)
# Create a data.frame with dirty names
test_df <- as.data.frame(matrix(ncol = 6))
names(test_df) <- c("hIgHlo", "REPEAT VALUE", "REPEAT VALUE",
                    "% successful (2009)",  "abc@!*", "")
```
Clean the variable names, returning a data.frame:
```{r}
test_df %>%
  clean_names()
```
Compare to what base R produces:
```{r}
make.names(names(test_df))
```

## Exploring

### `tabyl()` - a better version of `table()`
`tabyl()` is a tidyverse-oriented replacement for `table()`.  It counts combinations of one, two, or three variables, and then can be formatted with a suite of `adorn_*` functions to look just how you want.  For instance:

```{r}
mtcars %>%
  tabyl(gear, cyl) %>%
  adorn_totals("col") %>%
  adorn_percentages("row") %>%
  adorn_pct_formatting(digits = 2) %>%
  adorn_ns()
```

Learn more in the [tabyls vignette](https://github.com/sfirke/janitor/blob/master/vignettes/tabyls.md).

### Explore records with duplicated values for specific combinations of variables with `get_dupes()`
This is for hunting down and examining duplicate records during data cleaning - usually when there shouldn't be any.

For example, in a tidy data frame you might expect to have a unique ID repeated for each year, and year repeated for each unique ID, but no duplicated pairs of unique ID & year.  Say you want to check for their presence, and study any such duplicated records.

`get_dupes()` returns the records (and inserts a count of duplicates) so you can sleuth out the problematic cases:
```{r}
get_dupes(mtcars, wt, cyl) # or mtcars %>% get_dupes(wt, cyl) if you prefer to pipe
```



# Minor functions
Smaller functions for use in particular situations.  More human-readable than the equivalent code they replace.

## Cleaning

### Fix dates stored as serial numbers with `excel_numeric_to_date()`
Ever load data from Excel and see a value like `42223` where a date should be?  This function converts those serial numbers to class `Date`, and contains an option for specifying the alternate date system for files created with Excel for Mac 2008 and earlier versions (which count from a different starting point).
```{r}
excel_numeric_to_date(41103)
excel_numeric_to_date(41103, date_system = "mac pre-2011")
```

### `remove_empty_cols()` and `remove_empty_rows()`
One-line wrapper functions that do what they say.  For cases like cleaning Excel files containing empty rows and columns.
```{r}
q <- data.frame(v1 = c(1, NA, 3),
                v2 = c(NA, NA, NA),
                v3 = c("a", NA, "b"))
q %>%
  remove_empty_cols() %>%
  remove_empty_rows()
```

## Exploring

### Count factor levels in groups of high, medium, and low with `top_levels()`

Originally designed for use with Likert survey data stored as factors.  Returns a `tbl_df` frequency table with appropriately-named rows, grouped into head/middle/tail groups.

+ Takes a user-specified size for the head/tail groups
+ Automatically calculates a percent column
+ Supports sorting
+ Can show or hide `NA` values.

```{r}
f <- factor(c("strongly agree", "agree", "neutral", "neutral", "disagree", "strongly agree"),
            levels = c("strongly agree", "agree", "neutral", "disagree", "strongly disagree"))
top_levels(f)
top_levels(f, n = 1)
```

