`plotCiCoverage`

creates a plot showing the coverage before and after confidence interval
calibration at various widths of the confidence interval.

```
plotCiCoverage(
logRr,
seLogRr,
trueLogRr,
strata = as.factor(trueLogRr),
crossValidationGroup = 1:length(logRr),
legacy = FALSE,
evaluation,
legendPosition = "top",
title,
fileName = NULL
)
```

## Arguments

- logRr
A numeric vector of effect estimates on the log scale.

- seLogRr
The standard error of the log of the effect estimates. Hint: often the
standard error = (log(<lower bound 95 percent confidence interval>) -
log(<effect estimate>))/qnorm(0.025).

- trueLogRr
The true log relative risk.

- strata
Variable used to stratify the plot. Set `strata = NULL`

for no
stratification.

- crossValidationGroup
What should be the unit for the cross-validation? By default the unit
is a single control, but a different grouping can be provided, for
example linking a negative control to synthetic positive controls
derived from that negative control.

- legacy
If true, a legacy error model will be fitted, meaning standard
deviation is linear on the log scale. If false, standard deviation
is assumed to be simply linear.

- evaluation
A data frame as generated by the `evaluateCiCalibration`

function. If provided, the logRr, seLogRr, trueLogRr, strata, and legacy
arguments will be ignored.

- legendPosition
Where should the legend be positioned? ("none", "left", "right",
"bottom", "top").

- title
Optional: the main title for the plot

- fileName
Name of the file where the plot should be saved, for example
'plot.png'. See the function `ggsave`

in the ggplot2 package for
supported file formats.

## Value

A Ggplot object. Use the `ggsave`

function to save to file.

## Details

Creates a plot showing the fraction of effects above, within, and below the confidence interval. The
empirical calibration is performed using a leave-one-out design: The confidence interval of an
effect is computed by fitting a null using all other controls. The plot shows the coverage for
both theoretical (traditional) and empirically calibrated confidence intervals.

## Examples

```
if (FALSE) { # \dontrun{
data <- simulateControls(n = 50 * 3, mean = 0.25, sd = 0.25, trueLogRr = log(c(1, 2, 4)))
plotCiCoverage(data$logRr, data$seLogRr, data$trueLogRr)
} # }
```