README.Rmd

---
output: github_document
---

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

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

# tidycat

<!-- badges: start -->

[![CRAN status](https://www.r-pkg.org/badges/version/tidycat)](https://CRAN.R-project.org/package=tidycat)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/grand-total/tidycat?color=blue)](https://r-pkg.org/pkg/tidycat)
[![Lifecycle: superseded](https://img.shields.io/badge/lifecycle-superseded-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html#superseded)
[![R-CMD-check](https://github.com/guyabel/tidycat/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/guyabel/tidycat/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

<!-- <img src='./man/figures/logo.png' align="right" height="139" /> -->

## Introduction

The `tidycat` package includes the `tidy_categorical()` function to expand `broom::tidy()` outputs for categorical parameter estimates.

See the [pkgdown site](http://guyabel.github.io/tidycat/) for full details.

## Installation

You can install the released version of tidycat from [CRAN](https://CRAN.R-project.org) with:

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

And the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("guyabel/tidycat")
```

## Limitations

The `tidy_categorical()` function will probably not work as expected for non-default contrasts such as `contr.helmert()` and when one or more model parameters are rank deficient. It also only supports a limited range of models; `lm()` or `glm()` should be fine. For more complex cases, or an alternative method to create great coefficient plots, see the [`ggcoef_model()`](https://larmarange.github.io/ggstats/articles/ggcoef_model.html) function in the [ggstats](https://larmarange.github.io/ggstats/) package, which went through a major upgrade around the same time as I developed tidycat.


## Documentation

For full documentation, see the package vignette: [The tidycat package: expand broom::tidy() output for categorical parameter estimates](https://guyabel.github.io/tidycat/articles/tidycat.html)
 
## Hello World

The `tidy()` function in the broom package takes the messy output of built-in functions in R, such as `lm()`, and turns them into tidy data frames.

```{r, message=FALSE, warning=FALSE}
library(dplyr)
library(broom)

m1 <- mtcars %>%
  mutate(transmission = recode_factor(am, `0` = "automatic", `1` = "manual")) %>%
  lm(mpg ~ as.factor(cyl) + transmission + wt *  as.factor(cyl), data = .)

tidy(m1)
```

The `tidy_categorical()` function adds 

  - further columns (`variable`, `level` and `effect`) to the `broom::tidy()` output to help manage categorical variables
  - further rows for reference category terms and a column to indicate their location (`reference`) when setting `include_reference = TRUE` (default)

It requires two inputs

  - a data frame `d` of parameter estimates from a model from `broom::tidy()`
  - the corresponding model object `m` passed to `broom::tidy()`

For example:    
```{r}
library(tidycat)
d1 <- m1 %>%
  tidy(conf.int = TRUE) %>%
  tidy_categorical(m = m1)
d1 %>%
  select(-(3:5))
```

The expanded data frame from `tidy_categorical()` of parameter estimates can be particularly useful for creating coefficient plots, allowing:

  - grouping terms from the same categorical variable from the additional columns.
  - inclusion of reference categories in a coefficient plot from the additional rows, allowing the reader to better grasp the meaning of the parameter estimates in each categorical variable.

For example:

```{r fig.height=4, fig.width=8, eval=FALSE}
library(forcats)
library(ggplot2)
library(ggforce)

d1 %>%
  slice(-1) %>%
  mutate(variable = fct_inorder(variable)) %>%
  ggplot(mapping = aes(x = level, y = estimate, colour = reference,
                       ymin = conf.low, ymax = conf.high)) +
  facet_row(facets = "variable", scales = "free_x", space = "free") +
  geom_hline(yintercept = 0, linetype = "dashed") +
  geom_pointrange()
```


```{r echo=FALSE}
# eval = FALSE above and this because pkgdown wont inlcude plot from readme... not sure why
knitr::include_graphics("https://raw.githubusercontent.com/guyabel/tidycat/master/README-files/unnamed-chunk-4-1.png")
```