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

# tjmisc 
[![Travis build status](https://travis-ci.org/tjmahr/tjmisc.svg?branch=master)](https://travis-ci.org/tjmahr/tjmisc)


The goal of tjmisc is to gather miscellaneous helper functions, mostly for use 
in [my dissertation](https://github.com/tjmahr/dissertation). 

Apologies in advance. I think "misc" packages are kind of bad because packages
should be focused on specific problems: for example, my helper packages for
[working on polynomials](https://github.com/tjmahr/polypoly),
[printing numbers](https://github.com/tjmahr/printy) or 
[tidying MCMC samples](https://github.com/tjmahr/tristan). Having modular code
snapping together like Lego blocks is better than a grab-bag of functions, it's
true, but using `library(helpers)` is much, much better than using
`source("helpers.R")`. So here we are... in the grab-bag.


## Installation

You can install the tjmisc from github with:

```{r, eval = FALSE}
# install.packages("devtools")
devtools::install_github("tjmahr/tjmisc")
```

## Examples

### Sample groups of data

`sample_n_of()` is like dplyr's `sample_n()` but it samples groups. 

```{r example}
library(dplyr, warn.conflicts = FALSE)
library(tjmisc)
set.seed(11022017)

data <- tibble::tibble(
  day = 1:10 %>% rep(10) %>% sort(),
  id  = 1:10 %>% rep(10),
  block = letters[1:5] %>% rep(10) %>% sort() %>% rep(2),
  value = rnorm(100) %>% round(2))

# data from 3 days
sample_n_of(data, 3, day)

# data from 1 id
sample_n_of(data, 1, id)

# data from 2 block-id pairs
sample_n_of(data, 2, block, id)
```

### Tidy quantiles

`tidy_quantile()` returns a dataframe with quantiles for a given variable. I
like to use it to select values for plotting model predictions.

```{r}
iris %>% 
  tidy_quantile(Petal.Length)

iris %>% 
  group_by(Species) %>% 
  tidy_quantile(Petal.Length)
```

### Tidy correlations

`tidy_correlation()` calculates correlations between pairs of selected dataframe
columns. It accepts `dplyr::select()` selection semantics, and it respects
grouped dataframes.

```{r}
tidy_correlation(iris, -Species)

iris %>%
  dplyr::group_by(Species) %>%
  tidy_correlation(dplyr::starts_with("Petal"))
```

### Pairwise comparisons

`compare_pairs()` compares all pairs of values among levels of a categorical
variable. Hmmm, that sounds confusing. Here's an example. We compute the
difference in average score between each pair of workers.

```{r}
to_compare <- nlme::Machines %>%
  group_by(Worker) %>%
  summarise(avg_score = mean(score)) %>%
  print()

to_compare %>%
  compare_pairs(Worker, avg_score) %>%
  rename(difference = value) %>%
  mutate_if(is.numeric, round, 1)
```

### Et cetera

`ggpreview()` is like ggplot2's `ggsave()` but it saves an image to a temporary
file and then opens it in the system viewer. If you've ever found yourself in
a loop of saving a plot, leaving RStudio to doubleclick the file, sighing, going
back to RStudio, tweaking the height or width or plot theme, ever so slowly
spiraling in on your desired plot, then `ggpreview()` is for you.

`seq_along_rows()` saves a few keystrokes in for-loops that iterate over
dataframe rows.

```{r}
cars %>% head(5) %>% seq_along_rows()
cars %>% head(0) %>% seq_along_rows()
```

`is_same_as_last` and `replace_if_same_as_last()` are helpers for formatting
tables. I use them to replace repeating values in a text column with blanks.

```{r}
mtcars %>% 
  tibble::rownames_to_column("name") %>% 
  slice(1:10) %>% 
  select(cyl, name, mpg) %>% 
  arrange(cyl, mpg) %>% 
  mutate_at(c("cyl"), replace_if_same_as_last, "") %>% 
  knitr::kable()
```

`fct_add_counts()` adds counts to a factor's labels.

```{r}
# Create a factor with some random counts
set.seed(20190124)
random_iris <- iris %>% 
  dplyr::sample_n(250, replace = TRUE)

table(random_iris$Species)

# Updated factors
random_iris$Species %>% levels()
random_iris$Species %>% fct_add_counts() %>% levels()
```

You can tweak the format for the first label. I like to use this for plotting by
stating the unit next to the first count. 

```{r}
random_iris$Species %>% 
  fct_add_counts(first_fmt = "{levels} ({counts} flowers)") %>% 
  levels()
```



## More involved demos

These are things that I would have used in the demo above but cut and moved
down here to keep that overview succinct.

### Comparing pairs of values over a posterior distribution

I wrote `compare_pairs()` to compute posterior differences in Bayesian models.
For the sake of example, let's fit a Bayesian model of average sepal length for
each species in `iris`. We could get these estimates more directly using the default dummy-coding of factors, but let's ignore that for now.

```{r, results = "hide"}
library(rstanarm)
m <- stan_glm(
  Sepal.Length ~ Species - 1,
  iris,
  family = gaussian)
```

Now, we have a posterior distribution of species means.

```{r}
newdata <- data.frame(Species = unique(iris$Species))

p_means <- posterior_linpred(m, newdata = newdata) %>%
  as.data.frame() %>%
  tibble::as_tibble() %>%
  setNames(newdata$Species) %>%
  tibble::rowid_to_column("draw") %>%
  tidyr::gather(species, mean, -draw) %>%
  print()
```

For each posterior sample, we can compute pairwise differences of means with
`compare_means()`.

```{r pairs, fig.width = 4, fig.height = 2.5}
pair_diffs <- compare_pairs(p_means, species, mean) %>%
  print()

library(ggplot2)

ggplot(pair_diffs) +
  aes(x = pair, y = value) +
  stat_summary(fun.data = median_hilow, geom = "linerange") +
  stat_summary(fun.data = median_hilow, fun.args = list(conf.int = .8),
               size = 2, geom = "linerange") +
  stat_summary(fun.y = median, size = 5, shape = 3, geom = "point") +
  labs(x = NULL, y = "Difference in posterior means") +
  coord_flip()
```

...which should look like the effect ranges in the dummy-coded models.

```{r, results = "hide"}
m2 <- update(m, Sepal.Length ~ Species)
m3 <- update(m, Sepal.Length ~ Species, 
             data = iris %>% mutate(Species = forcats::fct_rev(Species)))
```

Give or take a few decimals of precision and give or take changes in signs
because of changes in who was subtracted from whom.

```{r}
# setosa verus others
m2 %>% 
  posterior_interval(regex_pars = "Species") %>% 
  round(2)

# virginica versus others
m3 %>% 
  rstanarm::posterior_interval(regex_pars = "Species") %>% 
  round(2)

# differences from compare_pairs()
pair_diffs %>% 
  tidyr::spread(pair, value) %>% 
  select(-draw) %>% 
  as.matrix() %>% 
  posterior_interval() %>% 
  round(2)
```