ggpie.Rmd

---
title: "ggpie"
author: "Yabing Song"
date: "`r Sys.Date()`"
output: prettydoc::html_pretty
vignette: >
  %\VignetteIndexEntry{Introduction to ggpie}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  dpi=60
)
```

# ggpie - A ggplot2 extension to create pie, donut and rose pie plot

<img src = "../man/figures/ggpie_hex.png" align = "right" width = "200"/>

## Introduction
`ggpie` aims to create **pie (2D and 3D)**, **donut** and **rose pie** plot with the `ggplot2` plotting system which implemented the grammar of graphics. It contains five main functions:

* `ggpie`: Create 2D pie plot with single group variable.
* `ggdonut`: Create 2D donut plot with single group variable.
* `ggnestedpie`: Create 2D nested pie plot with two group variables.
* `ggpie3D`: Create 3D pie plot with single group variable.
* `ggrosepie`: Create rose pie plot with single or two group variables.

<hr />

## Installation
You can install the released version of `ggpie` from [CRAN](https://cran.r-project.org/package=ggpie) with:

```{r cran_install, eval=FALSE, message=FALSE, warning=FALSE}
install.packages("ggpie")
```

Or install the package via the [Github repository](https://github.com/showteeth/ggpie):
```{r github_install, eval=FALSE, message=FALSE, warning=FALSE}
# install.package("remotes")   #In case you have not installed it.
remotes::install_github("showteeth/ggpie")
```

<hr />

## Citation
```{r citation}
citation("ggpie")
```

<hr />

## Usage
### Preapre data
```{r prepare, message=FALSE, warning=FALSE}
library(ggpie)
library(ggplot2)
data(diamonds)
# check data used
str(diamonds)
```

<hr />

### Pie plot
#### no label
Pie plot with **no label**: 
```{r pie_basic_no_label}
# with no label
ggpie(data = diamonds, group_key = "cut", count_type = "full",label_type = "none")
```

#### circle label
**circle label** and **out** of pie:
```{r pie_circle_out}
ggpie(data = diamonds, group_key = "cut", count_type = "full",
      label_info = c("count", "ratio"), label_type = "circle",
      label_size = 4, label_pos = "out")
```

**circle label** and **in** pie plot, with **no split**:
```{r pie_circle_in_no_split}
ggpie(data = diamonds, group_key = "cut", count_type = "full",
      label_info = c("count", "ratio"), label_type = "circle", label_split = NULL,
      label_size = 4, label_pos = "in")
```

#### horizon label
**horizon label** and **in** pie plot, with **no split**:
```{r pie_horizon_in_no_split}
ggpie(data = diamonds, group_key = "cut", count_type = "full",
      label_info = c("count", "ratio"), label_type = "horizon", label_split = NULL,
      label_size = 4, label_pos = "in")
```

**horizon label** and **in** pie plot, **split with space**:
```{r pie_horizon_in_split}
ggpie(data = diamonds, group_key = "cut", count_type = "full",
      label_info = c("count", "ratio"), label_type = "horizon",
      label_size = 4, label_pos = "in")
```

**horizon label** and **out** pie plot, with **no split**:
```{r pie_horizon_out_no_split}
ggpie(data = diamonds, group_key = "cut", count_type = "full",
      label_info = c("count", "ratio"), label_type = "horizon",
      label_size = 4, label_pos = "out" )
```

#### adjust threashold
With `label_threshold`, `ggpie` will move label below `label_threshold` to out of pie. In this example, all labels below 10% are moved to out of pie:
```{r pie_threashold_horizon_in}
ggpie(data = diamonds, group_key = "cut", count_type = "full",
      label_info = c("count", "ratio"), label_type = "horizon", label_split = NULL,
      label_size = 4, label_pos = "in", label_threshold = 10)
```

<hr />

### Donut plot
#### no label
```{r donut_basic_no_label}
# with no label
ggdonut(data = diamonds, group_key = "cut", count_type = "full",label_type = "none")
```

#### circle label
**circle label** and **out** of pie:
```{r donut_circle_out}
ggdonut(data = diamonds, group_key = "cut", count_type = "full",
        label_info = c("count", "ratio"), label_type = "circle",
        label_size = 4, label_pos = "out")
```

**circle label** and **in** pie plot, with **no split**:
```{r donut_circle_in_no_split}
ggdonut(data = diamonds, group_key = "cut", count_type = "full",
        label_info = c("count", "ratio"), label_type = "circle", label_split = NULL,
        label_size = 4, label_pos = "in")
```

#### horizon label
**horizon label** and **in** pie plot, with **no split**:
```{r donut_horizon_in_no_split}
ggdonut(data = diamonds, group_key = "cut", count_type = "full",
        label_info = c("count", "ratio"), label_type = "horizon", label_split = NULL,
        label_size = 4, label_pos = "in")
```

**horizon label** and **in** pie plot:
```{r donut_horizon_in}
ggdonut(data = diamonds, group_key = "cut", count_type = "full",
        label_info = c("count", "ratio"), label_type = "horizon",
        label_size = 4, label_pos = "in")
```

**horizon label** and **out** of pie plot, with **no split**:
```{r donut_horizon_out_no_split}
ggdonut(data = diamonds, group_key = "cut", count_type = "full",
        label_info = c("count", "ratio"), label_type = "horizon", label_split = NULL,
        label_size = 4, label_pos = "out")
```

**horizon label** and **out** of pie plot:
```{r donut_horizon_out}
ggdonut(data = diamonds, group_key = "cut", count_type = "full",
        label_info = c("count", "ratio"), label_type = "horizon",
        label_size = 4, label_pos = "out")
```

#### adjust threashold
With `label_threshold`, `ggpie` will move label below `label_threshold` to out of donut. In this example, all labels below 10% are moved to out of donut:
```{r donut_threashold_horizon_in}
ggdonut(data = diamonds, group_key = "cut", count_type = "full",
        label_info = c("count", "ratio"), label_type = "horizon", label_split = NULL,
        label_size = 4, label_pos = "in", label_threshold = 10)
```


```{r donut_threashold_horizon_in_no_split}
ggdonut(data = diamonds, group_key = "cut", count_type = "full",
        label_info = c("count", "ratio"), label_type = "horizon",
        label_size = 4, label_pos = "in", label_threshold = 10)
```

<hr />

### 3D pie plot

```{r pie3d}
p1= ggpie3D(data = diamonds, group_key = "cut", count_type = "full", tilt_degrees = -10, label_size=2) + 
  ggtitle("tilt_degrees = -10") + 
  theme(plot.title = element_text(hjust = 0.5))

p2= ggpie3D(data = diamonds, group_key = "cut", count_type = "full", tilt_degrees = -40, label_size=2) + 
  ggtitle("tilt_degrees = -40") + 
  theme(plot.title = element_text(hjust = 0.5))

p3= ggpie3D(data = diamonds, group_key = "cut", count_type = "full", tilt_degrees = -10, 
            start_degrees = 60, label_size=2) + 
  ggtitle("start_degrees = 60") + 
  theme(plot.title = element_text(hjust = 0.5))

p4= ggpie3D(data = diamonds, group_key = "cut", count_type = "full", tilt_degrees = -10, 
            start_degrees = 180, label_size=2) + 
  ggtitle("start_degrees = 180") + 
  theme(plot.title = element_text(hjust = 0.5))

cowplot::plot_grid(p1,p2,p3,p4,ncol = 2)
```

<hr />

### Nested pie/donut plot
It is often the case that we have **two categorical variables** and then need to plot for both of them, `ggnestedpie` is designed to deal with this.

#### inner circle and outer circle
**inner circle label** and **no split**, **outer circle label** and **in** pie plot
```{r nested_pie_inner_outer_circle_in}
ggnestedpie(data = diamonds, group_key = c("cut", "color"), count_type = "full",
            inner_label_info = "all", inner_label_split = NULL,inner_label_size = 2,
            outer_label_type = "circle", outer_label_pos = "in", outer_label_info = "all")
```

**inner circle label** and **no split**, **outer circle label** and **in** pie plot, **remove fraction below 1 of inner pie**:
```{r nested_pie_inner_outer_circle_in_remove}
ggnestedpie(data = diamonds, group_key = c("cut", "color"), count_type = "full",
            inner_label_info = "all", inner_label_split = NULL,
            inner_label_threshold = 5, inner_label_size = 2,
            outer_label_type = "circle", outer_label_pos = "in", outer_label_info = "all")
```

**inner circle label** and **no split**, **outer circle label** and **out** of pie plot:
```{r nested_pie_inner_outer_circle_out}
ggnestedpie(data = diamonds, group_key = c("cut", "color"), count_type = "full",
            inner_label_info = "all", inner_label_split = NULL, inner_label_size = 2,
            outer_label_type = "circle", outer_label_pos = "out", outer_label_info = "all")
```

#### inner circle and outer horizon
**inner circle label** and **no split**, **outer horizon label** and **out** of pie plot, **remove fraction below 1 of inner pie**:
```{r nested_pie_inner_outer_horizon_out_remove}
ggnestedpie(data = diamonds, group_key = c("cut", "color"), count_type = "full",
            inner_label_info = "all", inner_label_split = NULL,
            inner_label_threshold = 1, inner_label_size = 2,
            outer_label_type = "horizon", outer_label_pos = "out", outer_label_info = "all")
```

**inner circle label** and **no split**, **outer horizon label** and **in** pie plot, **remove fraction below 1 of inner pie**, **adjust fraction below 10 to out of pie of outer pie plot**:
```{r nested_pie_inner_outer_remove_horizon_in_remove}
ggnestedpie(data = diamonds, group_key = c("cut", "color"), count_type = "full",
            inner_label_info = "all", inner_label_split = NULL,
            inner_label_threshold = 1, inner_label_size = 2,
            outer_label_type = "horizon", outer_label_pos = "in",
            outer_label_info = "all", outer_label_threshold = 10)
```

#### blank between plot
```{r nested_pie_blank_inner_outer}
ggnestedpie(data = diamonds, group_key = c("cut", "color"), count_type = "full", 
            r0 = 0.5, r1 = 1.5, r2 = 2.6,inner_label_info = "all", inner_label_split = NULL,
            inner_label_threshold = 1, inner_label_size = 2,
            outer_label_type = "horizon", outer_label_pos = "in",
            outer_label_info = "all", outer_label_threshold = 10)
```

<hr />

### Rose pie/donut plot
#### single variable
**do not show tick**:
```{r rose_pie_no_tick, fig.height=10, fig.width=18}
# pie plot
p1=ggrosepie(diamonds, group_key = "color", count_type = "full", label_info = "all",
             show_tick=F,donut_frac=NULL)
# donut plot
p2=ggrosepie(diamonds, group_key = "color", count_type = "full", label_info = "all",
             show_tick=F,donut_frac=0.3,donut_label_size=3)
cowplot::plot_grid(p1,p2)
```

**show tick** and **select breaks automaticly**:
```{r rose_pie_with_tick, fig.height=8, fig.width=18}
# pie plot
p1=ggrosepie(diamonds, group_key = "color", count_type = "full", label_info = "all",
             donut_frac=NULL)
# donut plot
p2=ggrosepie(diamonds, group_key = "color", count_type = "full", label_info = "all",
             donut_frac=0.3,donut_label_size=3)
cowplot::plot_grid(p1,p2)
```

**show tick** and **with specific breaks**:
```{r rose_pie_with_tick_specific_break, fig.height=8, fig.width=18}
# pie plot
p1=ggrosepie(diamonds, group_key = "color", count_type = "full", label_info = "all",
             tick_break = c(3000,5000,7000,11000), donut_frac=NULL)
# donut plot
p2=ggrosepie(diamonds, group_key = "color", count_type = "full", label_info = "all",
             tick_break = c(3000,5000,7000,11000), donut_frac=0.3,donut_label_size=3)
cowplot::plot_grid(p1,p2)
```

#### two variables
**do not show tick**:
```{r rose_pie_two_no_tick, fig.height=8, fig.width=18}
# pie plot
p1=ggrosepie(diamonds, group_key = c("color","clarity"),
             count_type = "full", label_info = "all",
             show_tick=F,donut_frac=NULL)
# donut plot
p2=ggrosepie(diamonds, group_key = c("color","clarity"),
             count_type = "full", label_info = "all",
             show_tick=F,donut_frac=0.3,donut_label_size=3)
cowplot::plot_grid(p1,p2)
```

**show tick** and **select breaks automaticly**:
```{r rose_pie_two_with_tick, fig.height=8, fig.width=18}
# pie plot
p1=ggrosepie(diamonds, group_key = c("color","clarity"),
             count_type = "full", label_info = "all",
             donut_frac=NULL)
# donut plot
p2=ggrosepie(diamonds, group_key = c("color","clarity"),
             count_type = "full", label_info = "all",
             donut_frac=0.3,donut_label_size=3)
cowplot::plot_grid(p1,p2)
```

**show tick** and **with specific breaks**:
```{r rose_pie_two_with_tick_specific_break, fig.height=8, fig.width=18}
# pie plot
p1=ggrosepie(diamonds, group_key = c("color","clarity"),
             count_type = "full", label_info = "all",
             tick_break = c(3000,5000,7000,11000), donut_frac=NULL)
# donut plot
p2=ggrosepie(diamonds, group_key = c("color","clarity"),
             count_type = "full", label_info = "all",
             tick_break = c(3000,5000,7000,11000), donut_frac=0.3,donut_label_size=3)
cowplot::plot_grid(p1,p2)
```

<hr />

## Contributing
Please note that the `ggpie` project is released with a [Contributor Code of Conduct](https://www.contributor-covenant.org/version/1/0/0/code-of-conduct/). By contributing to this project, you agree to abide by its terms.

<br />