# ggProportionPlot

##### Sample distribution based plotting of proportions

This function visualises percentages, but avoids a clear cut for the sample point estimate, instead using the confidence (as in confidence interval) to create a gradient. This effectively hinders drawing conclusions on the basis of point estimates, thereby urging a level of caution that is consistent with what the data allows.

##### Usage

```
ggProportionPlot(dat, items = NULL,
loCategory = NULL,
hiCategory = NULL,
subQuestions = NULL,
leftAnchors = NULL,
rightAnchors = NULL,
compareHiToLo = TRUE,
showDiamonds = FALSE,
diamonds.conf.level=.95,
diamonds.alpha=1,
na.rm = TRUE,
barHeight = 0.4,
conf.steps = seq(from=0.001, to=.999, by=.001),
scale_color = viridis(option="magma", 2, begin=0, end=.5),
scale_fill = viridis(option="magma", 2, begin=0, end=.5),
linetype=1,
theme = theme_bw(),
returnPlotOnly = TRUE)
```

##### Arguments

- dat
The dataframe containing the items (variables), or a vector.

- items
The names of the items (variables). If none are specified, all variables in the dataframe are used.

- loCategory
The value of the low category (usually 0). If not provided, the minimum value is used.

- hiCategory
The value of the high category (usually 1). If not provided, the maximum value is used.

- subQuestions
The labels to use for the variables (for example, different questions). The variable names are used if these aren't provided.

- leftAnchors
The labels for the low categories. The values are used if these aren't provided.

- rightAnchors
The labels for the high categories. The values are used if these aren't provided.

- compareHiToLo
Whether to compare the percentage of low category values to the total of the low category values and the high category values, or whether to ignore the high category values and compute the percentage of low category values relative to all cases. This can be useful when a variable has more than two values, and you only want to know/plot the percentage relative to the total number of cases.

- showDiamonds
Whether to add diamonds to illustrate the confidence intervals.

- diamonds.conf.level
The confidence level of the diamonds' confidence intervals.

- diamonds.alpha
The alpha channel (i.e. transparency, or rather 'obliqueness') of the diamonds.

- na.rm
Whether to remove missing values.

- barHeight
The height of the bars, or rather, half the height. Use .5 to completely fill the space.

- conf.steps
The number of steps to use to generate the confidence levels for the proportion.

- scale_color, scale_fill
A vector with two values (valid colors), that are used for the colors (stroke) and fill for the gradient; both vectors should normally be the same, but if you feel adventurous, you can play around with the number of

`conf.steps`

and this. If you specify only one color, no gradient is used but a single color (i.e. specifying the same single color for both`scale_color`

and`scale_fill`

simply draws bars of that color).- linetype
The

`linetype`

to use (0 = blank, 1 = solid, 2 = dashed, 3 = dotted, 4 = dotdash, 5 = longdash, 6 = twodash).- theme
The theme to use.

- returnPlotOnly
Whether to only return the

`ggplot2`

plot or the full object including intermediate values and objects.

##### Details

This function used `confIntProp`

to compute confidence intervals for proportions at different levels of confidence. The confidence interval bounds at those levels of confidence are then used to draw rectangles with colors in a gradient that corresponds to the confidence level.

Note that percentually, the gradient may not look continuous because at the borders between lighter and darker rectangles, the shade of the lighter rectangle is perceived as even lighter than it is, and the shade of the darker rectangle is perceived as even darker. This makes it seem as if each rectange is coloured with a gradient in the opposite direction.

##### Value

A `ggplot2`

object (if `returnPlotOnly`

is TRUE), or an object containing that `ggplot2`

object and intermediate products.

##### See Also

##### Examples

```
# NOT RUN {
### V/S (no idea what this is: ?mtcars only mentions 'V/S' :-))
### and transmission (automatic vs manual)
ggProportionPlot(mtcars, items=c('vs', 'am'));
### Number of cylinders, by default comparing lowest value
### (4) to highest (8):
ggProportionPlot(mtcars, items=c('cyl'));
# }
# NOT RUN {
### Not running these to save time during package building/checking
### We can also compare 4 to 6:
ggProportionPlot(mtcars, items=c('cyl'),
hiCategory=6);
### Now compared to total records, instead of to
### highest value (hiCategory is ignored then)
ggProportionPlot(mtcars, items=c('cyl'),
compareHiToLo=FALSE);
### And for 6 cylinders:
ggProportionPlot(mtcars, items=c('cyl'),
loCategory=6, compareHiToLo=FALSE);
### And for 8 cylinders:
ggProportionPlot(mtcars, items=c('cyl'),
loCategory=8, compareHiToLo=FALSE);
### And for 8 cylinders with different labels
ggProportionPlot(mtcars, items=c('cyl'),
loCategory=8,
subQuestions='Cylinders',
leftAnchors="Eight",
rightAnchors="Four\nor\nsix",
compareHiToLo=FALSE);
### ... And showing the diamonds for the confidence intervals
ggProportionPlot(mtcars, items=c('cyl'),
loCategory=8,
subQuestions='Cylinders',
leftAnchors="Eight",
rightAnchors="Four\nor\nsix",
compareHiToLo=FALSE,
showDiamonds=TRUE);
# }
# NOT RUN {
### Using less steps for the confidence levels and changing
### the fill colours
ggProportionPlot(mtcars,
items=c('vs', 'am'),
showDiamonds = TRUE,
scale_fill = c("#B63679FF", "#FCFDBFFF"),
conf.steps=seq(from=0.0001, to=.9999, by=.2));
# }
```

*Documentation reproduced from package userfriendlyscience, version 0.7.2, License: GPL (>= 3)*