Introduction
Before-and-after data — the same subjects measured twice — isn't independent, so treating it like two separate samples throws away the very structure that makes the comparison powerful. TwoSampleTTestPaired runs the paired (dependent) t-test instead, testing whether the mean difference between paired observations is significantly different from zero using scipy.stats.ttest_rel, and plots the simulated distribution of that mean difference against the null hypothesis so you can see both the size and the certainty of the change.
Teaching Note
A paired t-test is essential for:
- Evaluating treatment efficacy in pre-test and post-test study designs
- Analyzing performance changes in employees before and after training
- Testing if a new software update improved system processing speeds
- Comparing identical twins or matched pairs on a specific metric
- Assessing seasonal variations where the same entities are tracked over time
- Measuring the impact of a marketing campaign on individual customer spend
- Validating the consistency of two different measurement tools on the same subjects
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dataframerequired | | — | The pandas DataFrame containing the paired outcome data. |
outcome1_columnrequired | | — | Name of the column containing the first set of observations (e.g., 'Pre-test'). |
outcome2_columnrequired | | — | Name of the column containing the second set of observations (e.g., 'Post-test'). |
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' (means are not equal), 'greater' (mean of first is greater than second), or 'less' (mean of first is less than second). Defaults to 'two-sided'. |
null_handling | | 'omit' | Method for handling missing values (NaN) in the data. Options include 'omit' (ignore pairs with NaNs), 'raise' (throw error), or 'propagate' (return NaN). Defaults to 'omit'. |
plot_sample_distributions | | True | If True, displays a kernel density estimate of the simulated mean difference distribution to visualize the comparison against zero. Defaults to True. |
fill_color | | '#999999' | The fill color for the distribution plot area. Defaults to '#999999'. |
fill_transparency | | 0.2 | Transparency level (alpha) for the distribution plot fill, ranging from 0 to 1. Defaults to 0.2. |
title_for_plot | | 'Paired T-Test' | Main title text to display at the top of the plot. Defaults to 'Paired T-Test'. |
subtitle_for_plot | | 'Shows the distribution of the mean difference across all pairs' | 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.1. |
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 named tuple containing the t-statistic and p-value, accessible via result.statistic and result.pvalue.
Example
python
from analysistoolbox.hypothesis_testing import TwoSampleTTestPaired
import pandas as pd
# Compare student test scores before and after a training seminar
test_df = pd.DataFrame({
'before': [75, 82, 68, 91, 77] * 10,
'after': [80, 85, 72, 90, 81] * 10
})
results = TwoSampleTTestPaired(
dataframe=test_df,
outcome1_column='before',
outcome2_column='after',
alternative_hypothesis='less'
)