A tidier version of prop.test() for equal or given
proportions.

prop_test(
x,
formula,
response = NULL,
explanatory = NULL,
p = NULL,
order = NULL,
alternative = "two-sided",
conf_int = TRUE,
conf_level = 0.95,
success = NULL,
correct = NULL,
z = FALSE,
...
)

## Arguments

x |
A data frame that can be coerced into a tibble. |

formula |
A formula with the response variable on the left and the
explanatory on the right, where an explanatory variable NULL indicates
a test of a single proportion. |

response |
The variable name in `x` that will serve as the response.
This is alternative to using the `formula` argument. This is an alternative
to the formula interface. |

explanatory |
The variable name in `x` that will serve as the
explanatory variable. Optional. This is an alternative to the formula
interface. |

p |
A numeric vector giving the hypothesized null proportion of
success for each group. |

order |
A string vector specifying the order in which the proportions
should be subtracted, where `order = c("first", "second")` means
`"first" - "second"` . Ignored for one-sample tests, and optional for two
sample tests. |

alternative |
Character string giving the direction of the alternative
hypothesis. Options are `"two-sided"` (default), `"greater"` , or `"less"` .
Only used when testing the null that a single proportion equals a given
value, or that two proportions are equal; ignored otherwise. |

conf_int |
A logical value for whether to report the confidence
interval or not. `TRUE` by default, ignored if `p` is specified for a
two-sample test. Only used when testing the null that a single
proportion equals a given value, or that two proportions are equal;
ignored otherwise. |

conf_level |
A numeric value between 0 and 1. Default value is 0.95.
Only used when testing the null that a single proportion equals a given
value, or that two proportions are equal; ignored otherwise. |

success |
The level of `response` that will be considered a success, as
a string. Only used when testing the null that a single
proportion equals a given value, or that two proportions are equal;
ignored otherwise. |

correct |
A logical indicating whether Yates' continuity correction
should be applied where possible. If `z = TRUE` , the `correct` argument will
be overwritten as `FALSE` . Otherwise defaults to `correct = TRUE` . |

z |
A logical value for whether to report the statistic as a standard
normal deviate or a Pearson's chi-square statistic. \(z^2\) is distributed
chi-square with 1 degree of freedom, though note that the user will likely
need to turn off Yates' continuity correction by setting `correct = FALSE`
to see this connection. |

... |
Additional arguments for prop.test(). |

## Examples

#> # A tibble: 1 x 6
#> statistic chisq_df p_value alternative lower_ci upper_ci
#> <dbl> <dbl> <dbl> <chr> <dbl> <dbl>
#> 1 0.0000204 1 0.996 two.sided -0.101 0.0917

# one-sample proportion test for hypothesized null
# proportion of college completion of .2
prop_test(gss,
college ~ NULL,
p = .2)

#> # A tibble: 1 x 4
#> statistic chisq_df p_value alternative
#> <dbl> <int> <dbl> <chr>
#> 1 636. 1 2.98e-140 two.sided

# report as a z-statistic rather than chi-square
# and specify the success level of the response
prop_test(gss,
college ~ NULL,
success = "degree",
p = .2,
z = TRUE)

#> # A tibble: 1 x 3
#> statistic p_value alternative
#> <dbl> <dbl> <chr>
#> 1 8.27 1.30e-16 two.sided