README.Rmd

---
output: github_document
---

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

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse=TRUE,
  comment="#>",
  strip.white=FALSE,
  tidy=FALSE,
  dpi=300,
  fig.align="center",
  fig.path="man/figures/README-",
  fig.width=5.25,
  fig.height=3.8,
  out.width="700px"
)
```


[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/ggdistribute)](https://cran.r-project.org/package=ggdistribute)

# ggdistribute

A `ggplot2` Extension for Plotting Unimodal Distributions

The `ggdistribute` package is an extension for plotting posterior or other types of unimodal distributions that require overlaying information about a distribution's intervals. It makes use of the `ggproto` system to extend `ggplot2`, providing additional "geoms", "stats", and "positions." The extensions integrate with existing `ggplot2` layer elements.

## Example

```{r, echo=FALSE, message=FALSE, results='hide', warning=FALSE}
library(ggplot2)
devtools::load_all(".", export_all = FALSE)
theme_set(theme_mejr())
```

The package function `example_plot()` is an overview of combining `ggdistribute` with other `ggplot2` elements. The contents of this function are printed below and gives details about the extended parts to `ggplot2`.

```{r, eval=FALSE}
library(ggplot2)
library(ggdistribute)
```

```{r turtle_snails, echo = FALSE, fig.width=5, fig.height=3, out.width="100%"}
plot(example_plot())
```

```{r prin_ex_plot, echo=FALSE, results='asis'}
ggdistribute:::function2chunk("example_plot")
```

## Additional examples from an arbritrary dataset

```{r}
# total number of samples in the dataset
N <- 2500
means <- c(-1, 2, 3, 5)
```

The `data` object below is a randomly generated dataset of `r length(means)` different normal distributions. Two factors, `Condition` and `Group`, are assigned to subsets of the generated values. `r N` samples are generated for each value of `mu` for a total of $ `r N*length(means)` $ rows.

```{r norm_data}
data <- data_normal_sample(mu = means, n = N)
```

Create a new grouping variable called `Level` based on the column `Group`.

```{r norm_data_grps}
# number of levels to make
num_levels <- 8L

# R version >= 3.5 now let's you assign factors this way.
data$Level <- with(data, factor(
  Group,
  levels = letters[seq_len(num_levels)],
  labels = c(rep("Low", 3), rep("Mid", 2), rep("High", 3)),
  ordered = TRUE
))
```

Show unique groups per `Group`, `Condition`, and `Level` to help understand the data factors.

```{r}
unique(data[, c("Group", "Condition", "Level")])
```

### Facetting and spreading groups

```{r space_ships, fig.width=5, fig.height=4}
ggplot(data) +
  aes(x=value, y=Condition, group=Group) +
  geom_posterior(
    aes(fill=Level),
    mirror=TRUE,
    show.legend=FALSE,
    adjust=1.5,
    brighten=c(6, 0, 2.5),
    position=position_spread(reverse=TRUE)
  ) +
  geom_point(
    aes(color=Level, shape=Condition),
    alpha=.08,
    fill=NA,
    show.legend=FALSE,
    position=position_jitter(0, .45)
  ) +
  coord_cartesian(ylim=c(0.5, 2.5), expand=FALSE) +
  facet_wrap(~ Level, scales="free") +
  labs(title="Space Invaders", y="Condition", x="Parameter estimate")
```

### Changing the appearance of `geom_posterior`

```{r candy_wrappers, fig.width=5, fig.height=4}
ggplot(data) +
  aes(x=value, y=Group) +
  geom_vline(
    xintercept=0, size=.6
  ) +
  geom_posterior(
    aes(color=Condition),
    midline=NULL,
    mirror=TRUE,
    fill="#FFFFFF",
    draw_sd=FALSE,
    interval_type="hdi",
    vjust=0,
    position=position_spread(height=2)
  ) +
  labs(
    title="Candy Wrappers",
    x="Parameter estimate",
    y="Sample location"
  ) +
  scale_x_continuous(breaks=seq(-10, 10, 1)) +
  theme(
    legend.position=c(.025, .9),
    legend.justification=c(0, 0),
    panel.grid.major.y=element_line(color=gray(.92))
  )
```

### The *y* axis is a repeated, continuous grouping variable

The variable `GroupScore` is a continuous variable assigned to each `Group`. The distributions will be positioned at the start of the y value for each group, and resized to not overlap with the next group. Resizing can be overriden by specifying `height` in `position_spread`.

```{r y_cont}
unique(data[, c("Group", "GroupScore")])
```

```{r rainbow_hills, fig.width=5, fig.height=6}
ggplot(data) +
  aes(x=value, y=GroupScore) +
  geom_vline(
    xintercept=0, size=.6
  ) +
  geom_posterior(
    aes(fill=Group),
    midline="#FFFFFF",
    colour="#FFFFFF",
    alpha=0.7,
    brighten=c(1.3, 0, -1.3),
    interval_type="hdi",
    position=position_spread(height=0.5, padding=0)
  ) +
  labs(
    title="Rainbow Hills",
    x="Parameter estimate",
    y="Group's score"
  ) +
  scale_x_continuous(breaks=seq(-10, 10, 1)) +
  scale_y_continuous(breaks=seq(-10, 10, .5))
```

## How to install

### Dependencies

- R: <https://www.r-project.org/>

A current R installation.

#### Dependencies for installing the development version of this package

- `devtools` package: <https://www.rstudio.com/products/rpackages/devtools/>

The `devtools` package is an R package that makes it easier to install local or remote content as an R package that can be used like any other standard R package. You can install `devtools` by opening up RStudio or an R terminal and running

```{r devtools-inst, eval=FALSE}
install.packages("devtools")
```

For Windows users, you *may* be required to install Rtools first before you can use the `devtools` package, if there is any code that needs to be compiled. These are a set of build tools customized for building R packages (see the `devtools` link above for more details).

- Build tools: <http://cran.r-project.org/bin/windows/Rtools/>

### Installing from CRAN


If you want to use the last version that was uploaded to the CRAN repository, do the following:

```{r cran-inst, eval=FALSE}
install.packages("ggdistribute")
```

### Installing from the downloaded package content folder

If you have all of the `ggdistribute` package contents (e.g., an unzipped folder containing `DESCRIPTION`, `NAMESPACE`, `R/`, etc...), you can open up the `ggdistribute.Rproj` file in RStudio and use both `devtools` and RStudio to load or install package.

The first step is to make sure you have all the package dependencies (other packages that this pacakge relies on) to be able to load or install the `ggdistribute` package materials. You can run the line below to install dependencies first.

```{r local-inst-dep, eval=FALSE}
devtools::install_dev_deps()
```

After the dependencies are installed, you can now build and install `ggdistribute` from the current working directory.
Assuming the `ggdistribute` project is loaded in RStudio, you can leave out the first argument.

```{r local-inst, eval=FALSE}
devtools::install()
```

If installing from a different working directory, enter the path of the package contents to manually specify what to install.

```{r local-inst-alt, eval=FALSE}
devtools::install_dev_deps("/Path/to/the/folder/ggdistribute")
devtools::install("/Path/to/the/folder/ggdistribute")
```


### Installing from GitHub

If `devtools` are installed, you may use the `install_github()` function to download and install the development version of the package from this GitHub repository instead of the one hosted on CRAN. Run the code below to download and install the development version:

```{r gh-installation, eval = FALSE}
devtools::install_github("iamamutt/ggdistribute")
```

or to install all suggested packages as well...

```{r gh-installation-dep, eval = FALSE}
devtools::install_github("iamamutt/ggdistribute", dependencies=TRUE)
```

### Loading the package

If successful, the package should now be installed and can be loaded as any other package. Repeat the last intall step if there are updates to the package, or complete all steps to install on another machine. You should now be able to use the package materials and should see it in your packages tab if using RStudio. It should be loaded like any other package.

```{r load-pkg, eval=FALSE}
library(ggdistribute)
```


## Getting help

### Browsing the vignettes

Vignettes can be viewed in several different ways.

- pre-built and saved in the `inst\doc` folder on GitHub.
- calling `vignette("geom_posterior", "ggdistribute")` from within R after the package is installed.
- navigating to packages tab > ggdistribute > User guides, package vignettes... in RStudio.

### Viewing the help documentation

View the package welcome page to navigate to different types of help documents

```{r show-welcome, eval=FALSE}
package?ggdistribute
```

Viewing package information and a list of exported objects:

```{r show-help, eval=FALSE}
help(package = "ggdistribute")

# or
library(help="ggdistribute")
```