Introduction
Is your process actually hitting its target, or does it just look close? OneSampleTTest answers that with a one-sample t-test: it compares a sample's mean against a hypothesized value — a spec, a benchmark, a target — and reports whether the difference is large enough to be real given the sample's variability, rather than just noise. It works without knowing the population standard deviation, which is exactly the situation you're usually in when checking a measurement against a standard.
Teaching Note
The one-sample t-test is essential for:
- Comparing product specifications (e.g., weight, length) against factory standards
- Testing if average student test scores differ from a national benchmark
- Evaluating if service delivery times meet a target performance level
- Analyzing if investment returns significantly deviate from a zero-growth baseline
- Assessing if average daily caloric intake matches a dietary recommendation
- Checking for systematic bias in measurement instruments
- Validating whether a new process has shifted a mean value away from a baseline
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dataframerequired | | — | The pandas DataFrame containing the numerical data to be tested. |
value_columnrequired | | — | Name of the column in the DataFrame containing the sample observations. |
hypothesized_valuerequired | | — | The expected population mean (null hypothesis value) to test the sample mean against. |
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. |
alternative_hypothesis | | 'two-sided' | Defines the alternative hypothesis. Must be one of 'two-sided' (mean is not equal to hypothesized), 'less' (mean is less than hypothesized), or 'greater' (mean is greater than hypothesized). Defaults to 'two-sided'. |
null_handling | | 'omit' | Method for handling missing values (NaN) in the data. Options include 'omit' (ignore NaNs), 'raise' (throw error), or 'propagate' (return NaN). Defaults to 'omit'. |
plot_sample_distribution | | True | If True, displays a kernel density estimate of the sample distribution and marks the hypothesized value for visual comparison. Defaults to True. |
fill_color | | '#999999' | The fill color for the KDE plot area. Defaults to '#999999'. |
fill_transparency | | 0.2 | Transparency level (alpha) for the KDE plot fill, ranging from 0 to 1. Defaults to 0.2. |
title_for_plot | | 'One Sample T-Test' | Main title text to display at the top of the plot. Defaults to 'One Sample T-Test'. |
subtitle_for_plot | | 'Shows the distribution of the sample mean and the hypothesized value.' | 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 (density 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 scipy.stats.TtestResult object containing the t-statistic, p-value, and degrees of freedom, accessible via result.statistic and result.pvalue.
Example
python
from analysistoolbox.hypothesis_testing import OneSampleTTest
import pandas as pd
# Test if average package weight is significantly different from 500g
df = pd.DataFrame({'weight': [498, 502, 505, 495, 499, 501, 503, 497] * 5})
results = OneSampleTTest(
dataframe=df,
value_column='weight',
hypothesized_value=500.0
)