---
title: "Using 'confintr'"
bibliography: "biblio.bib"
link-citations: true
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using 'confintr'}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

{confintr} is dedicated to confidence intervals (CI). The following parameters are covered:

- mean (Student, Wald, bootstrap),
- proportion (Wilson, Clopper-Pearson, Agresti-Coutts, bootstrap),
- median and other quantiles (distribution-free binomial and bootstrap),
- variance and standard deviation (chi-squared, bootstrap),
- IQR and MAD (bootstrap only),
- skewness and kurtosis (bootstrap only),
- R-squared and the non-centrality parameter of the F distribution (parametric),
- Cramér's V and the non-centrality parameter of the chi-squared distribution (parametric and bootstrap),
- the odds ratio of a 2x2 table (exact),
- Pearson-, Spearman-, Kendall correlation coefficients (normal for Pearson, bootstrap for any),
- Mean, quantile and median differences of two samples (for quantile/median only bootstrap).

Many of the classic CIs on this list are discussed in @smithson2003. 

In line with the {boot} backend, the following bootstrap CIs are (usually) available:

1. Normal ("norm") bootstrap CI: This is the Wald/Student CI using bootstrap standard error and bootstrap bias correction. Simple, but only first-order accurate, and not transformation respecting.

2. Percentile ("perc") bootstrap CI: Uses quantiles of the bootstrap distribution as confidence limits. Simple, but only first-order accurate. Transformation respecting.

3. Basic ("basic") or reverse bootstrap CI: Flipped version of the percentile approach, dealing with bias but at the price of having very unnaturally tailed sampling distributions. Only first-order accurate.

4. Bias-corrected and accelerated ("bca") CI: Refined version of the percentile bootstrap. Second-order accurate and transformation respecting. Needs more replications than observations. **The default** (except for the mean and the mean difference, see below).

5. Student-t ("stud") bootstrap CI: Refined version of the normal bootstrap that replaces the Student quantile by a custom quantile obtained from bootstrapping the variance of the statistic. second-order accurate but not transformation respecting. Requires a formula for the variance of the estimator, which {confintr} provides for the mean, the mean difference, the variance (and standard deviation) as well as for the proportion. **Used as the default for the mean and the mean difference.**

For details on bootstrap CIs, we refer to @efron1993.

## Installation

```r
# From CRAN
install.packages("confintr")

# Development version
devtools::install_github("mayer79/confintr")
```

## Usage

```{r}
library(confintr)

set.seed(1)

# Mean
ci_mean(1:100)

ci_mean(1:100, type = "bootstrap")

# 95% value at risk
ci_quantile(rexp(1000), q = 0.95)

# IQR
ci_IQR(rexp(100))

# Correlation
ci_cor(iris[1:2], method = "spearman", type = "bootstrap")

# Proportions
ci_proportion(10, n = 100, type = "Wilson")

ci_proportion(10, n = 100, type = "Clopper-Pearson")

# R-squared
fit <- lm(Sepal.Length ~ ., data = iris)
ci_rsquared(fit, probs = c(0.05, 1))

# Kurtosis
ci_kurtosis(1:100)

# Mean difference
ci_mean_diff(10:30, 1:15)

ci_mean_diff(10:30, 1:15, type = "bootstrap")

# Median difference
ci_median_diff(10:30, 1:15)
```

## References