Introduction
A reported conversion rate, defect rate, or poll number is only meaningful once you know whether it actually differs from a benchmark, or just landed there by sampling noise. TTestOfProportionFromStats tests a summarized proportion — no raw data needed, just the observed proportion, sample size, and hypothesized value — against that benchmark, automatically choosing a t-test for small samples or a z-test for larger ones, and visualizing the simulated sampling distribution against the hypothesized proportion.
Teaching Note
A hypothesis test of a proportion from statistics is essential for:
- Validating survey results on population characteristics
- Testing conversion rates against industry or historical benchmarks
- Verifying if defect rates in manufacturing meet quality standards
- Analyzing political polling data and projected vote shares
- Assessing click-through rates (CTR) in digital marketing campaigns
- Evaluating adoption rates of new features or software updates
- Benchmarking successful outcomes in clinical or social research
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
sample_proportionrequired | | — | The observed proportion exhibiting the characteristic of interest in the sample (range 0 to 1). |
sample_sizerequired | | — | The total number of observations in the sample (n). If n < 30, a t-distribution is used; otherwise, a normal distribution is assumed. |
hypothesized_proportionrequired | | — | The population proportion value to test against (null hypothesis value, range 0 to 1). |
alternative_hypothesis | | 'two-sided' | Defines the alternative hypothesis. Must be one of 'two-sided' (not equal to), 'less' (is less than), or 'greater' (is greater than). Defaults to 'two-sided'. |
confidence_interval | | 0.95 | The confidence level used to determine statistical significance (e.g., 0.95 for a 5% significance level). Defaults to 0.95. |
plot_sample_distribution | | True | If True, displays a histogram showing the distribution of simulated sample proportions relative to the hypothesized value. Defaults to True. |
value_name | | 'Value' | Descriptive name for the proportion being tested, used as the x-axis label in the visualization. Defaults to 'Value'. |
fill_color | | '#999999' | Hex color code or name for the distribution plot bars. Defaults to '#999999'. |
fill_transparency | | 0.6 | Transparency level (alpha) for the plot bars, ranging from 0 to 1. Defaults to 0.6. |
title_for_plot | | 'Hypothesis Test of a Proportion' | Main title text to display at the top of the plot. Defaults to 'Hypothesis Test of a Proportion'. |
subtitle_for_plot | | 'Shows the distribution of the sample proportion and the hypothesized proportion.' | Subtitle text to display below the main title. |
caption_for_plot | | None | Caption text displayed at the bottom of the plot. Defaults to None. |
data_source_for_plot | | None | Optional text identifying the data source, displayed in the caption area. Defaults to None. |
show_y_axis | | False | If True, displays the y-axis (frequency scale) on the distribution plot. Defaults to False. |
title_y_indent | | 1.1 | Vertical position for the main title relative to the axes. Defaults to 1.10. |
subtitle_y_indent | | 1.05 | Vertical position for the subtitle relative to the axes. Defaults to 1.05. |
caption_y_indent | | -0.15 | Vertical position for the caption relative to the axes. Defaults to -0.15. |
figure_size | | (8, 6) | Tuple specifying the (width, height) of the figure in inches. Defaults to (8, 6). |
Returns
A float — the calculated test statistic (z-score or t-score, depending on sample size).
Example
python
from analysistoolbox.hypothesis_testing import TTestOfProportionFromStats
# Test if a 60% observed conversion rate significantly exceeds a 50% benchmark
test_stat = TTestOfProportionFromStats(
sample_proportion=0.6,
sample_size=100,
hypothesized_proportion=0.5,
alternative_hypothesis='greater'
)