---
title: "ggnormalviolin"
format: 
  html:
    toc: true
vignette: >
  %\VignetteIndexEntry{ggnormalviolin}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk:
    collapse: true
    comment: '#>'
---

```{r}
#| label: setup
#| include: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6.5,
  fig.height = 6.5
)
library(ggnormalviolin)
```

Suppose there are 4 hypothetically normal distributions with specific means and standard deviations. They can be plotted like so:

```{r}
#| label: fig-example
#| fig-cap: Example of a how to use ggnormalviolin
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations
library(ggplot2)
library(ggnormalviolin)

# Make data
d <- data.frame(
  dist = c("A", "B", "C", "D"),
  dist_mean = c(80, 90, 110, 130),
  dist_sd = c(15, 10, 20, 5),
  cp = c(0.5, 0.8, 0.2, 0.1)
)

# Make base plot
p <- ggplot(data = d,
            aes(x = dist,
                mu = dist_mean,
                sigma = dist_sd,
                fill = dist)) +
  theme_light() +
  theme(legend.position = "none") +
  labs(x = NULL, y = NULL)

# Add normal violins
p + geom_normalviolin()
```

## Tail Highlighting

Suppose you want to highlight the two tails of the distributions. Set the `p_tails` to specify the total area of the tails. Thus, if `p_tail` = 0.05, each tail will represent the outermost 2.5% of the distributions (i.e, 0.05 = 2 &mult; 0.025).

```{r}
#| label: fig-example2
#| fig-cap: How to shade both violin tails
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with 2.5 percent of
#|   each tail shaded.
p + geom_normalviolin(p_tail = 0.05)
```

Suppose you want to highly only the upper tails. Set `p_upper_tail` to the proportion desired.

```{r}
#| label: fig-uppertail
#| fig-cap: How to shade the upper tails only
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with 5 percent of the
#|   upper tails shaded.
p + geom_normalviolin(p_upper_tail = 0.05)
```

Analogously, you can highlight only the lower tails by setting the `p_lower_tail` parameter.

```{r}
#| label: fig-lowertail
#| fig-cap: How to shade the lower tails only
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with 5 percent of the
#|   lower tails shaded.
p + geom_normalviolin(p_lower_tail = 0.05)
```

The `p_tail`, `p_lower_tail`, and `p_upper_tail` can be different for each violin by mapping them to a variable.

```{r}
#| label: fig-shadedifferent
#| fig-cap: How to shade the lower tails differently for each grid
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with different proportions of the
#|   lower tails shaded.
p + geom_normalviolin(aes(p_upper_tail = cp))
```


The defaults for highlighting is accomplished by selecting a subset of the whole distribution, setting `tail_fill` to black, and then making the black fill transparent by setting `tail_alpha` = 0.4. Setting these values to other colors and levels of transparency can dramatically change the look of the plot.

```{r}
#| label: fig-style
#| fig-cap: How to style normal violins
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with white tails,
#|   and gray outlines.
p +
  geom_normalviolin(
    p_tail = 0.05,
    tail_fill = "white",
    tail_alpha = 0.8,
    color = "gray20",
    linewidth = 0.1
  )
```




## Direction of Violin

If you want to omit the left or right side of the violins, you can set the `face_left` or `face_right` parameters to `FALSE`.

```{r}
#| label: fig-faceright
#| fig-cap: How make half-violins
#| fig-alt: >
#|   Plot of 4 normal half-violin shapes of different fill colors,
#|   means, and standard deviations, with 5 percent of the
#|   upper tails shaded.
p + geom_normalviolin(face_right = FALSE, p_tail = 0.05)

```

## Violin Width

You can set the `width` of the violin to any size desired.

```{r}
#| label: fig-setwidth
#| fig-cap: How to set violin width to a constant value
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with width set to 1.
p + geom_normalviolin(width = 1)
```

If you want the shape of the distribution to remain constant, map the `width` parameter to a multiple of the standard deviation.

```{r}
#| label: fig-setsdwidth
#| fig-cap: How to set violin width to be proportional to the standard deviation
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with width set to be
#|   proportional to the standard deviation
p + geom_normalviolin(aes(width = dist_sd * 0.05))

```

## Setting Limits

By default, the normal violins extend 4 standard deviations in both directions. Use the `nsigma` parameter to set a different value.

```{r}
#| label: fig-nsigma
#| fig-cap: How to set violin height
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with height set to plus
#|   or minus 1.5 standard deviations.
p + geom_normalviolin(nsigma = 1.5)
```

If you set limits on the y scale, it is possible that some of the violins will be distorted or cut in pieces.

```{r}
#| label: fig-ylim
#| fig-cap: A distorted plot due to limits set too narrowly
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with limits set too
#|   narrowly, which distors the violin shapes.
p +
  geom_normalviolin() +
  ylim(50, 140)
```

This occurs because data outside the limits is discarded, breaking up the polygons that compose the violins into smaller pieces. To prevent such behavior, set the `upper_limit` and `lower_limit` parameters equal to the same limits you have specified for the y scale (or any other values you wish).

```{r}
#| label: fig-upperlowerlimits
#| fig-cap: How to set plot limits to prevent image distortion
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with limits set
#|   appropriately wide using the ylim function.
p +
  geom_normalviolin(lower_limit = 50, upper_limit = 140) +
  ylim(50, 140)
```

Alternately, you can set the limits in `ggplot2::coord_cartesian` (or any of the `coord_*` functions), which will zoom the plot instead of discarding the data.

```{r}
#| label: fig-coordcartesian
#| fig-cap: How to set zooming limits using a `coord_*` function
#| fig-alt: >
#|   Plot of 4 normal violin shapes of different fill colors,
#|   means, and standard deviations, with limits set
#|   appropriately wide using the coord_cartesian function's
#|   ylim parameter.
p +
  geom_normalviolin() +
  coord_cartesian(ylim = c(50, 140))
```
