Introduction
Did the treatment group actually outperform the control group, or is the gap between two unrelated samples within the range you'd expect from randomness alone? TwoSampleTTestOfIndependence runs an independent two-sample t-test directly on raw data grouped by a categorical column, computing the t-statistic and p-value with scipy.stats.ttest_ind, supporting both Student's t-test (equal variances) and Welch's correction (unequal variances), and plotting the simulated sample mean distributions for both groups so the size of the difference is visible, not just its significance.
Teaching Note
A two-sample t-test is essential for:
- Comparing experimental results between a treatment group and a control group
- Analyzing performance differences between two distinct demographic segments
- Testing if two manufacturing processes produce parts with different average sizes
- Evaluating the impact of two different marketing strategies on customer spend
- Assessing if gender, age, or location groups exhibit different average behaviors
- Validating whether a training program significantly improved scores vs. a baseline
- Comparing product satisfaction ratings between two different user categories
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dataframerequired | | — | The pandas DataFrame containing the data to be analyzed. |
outcome_columnrequired | | — | Name of the column in the DataFrame containing the continuous dependent variable. |
grouping_columnrequired | | — | Name of the column in the DataFrame containing the categorical independent variable (must have exactly two unique groups). |
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), 'less' (mean of first group is less than second), or 'greater' (mean of first group is greater than second). Defaults to 'two-sided'. |
homogeneity_of_variance | | True | If True, assumes equality of variance between groups (Student's t-test). If False, performs Welch's t-test for unequal variances. Defaults to True. |
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_distributions | | True | If True, displays a kernel density estimate of the simulated sample means for both groups to visualize the comparison. Defaults to True. |
color_palette | | 'Set2' | Seaborn color palette name used for the lines and fills in the plot. Defaults to 'Set2'. |
title_for_plot | | 'T-Test of Independence' | Main title text to display at the top of the plot. Defaults to 'T-Test of Independence'. |
subtitle_for_plot | | 'Shows the distribution of the sample means for each group.' | 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.Ttest_indResult named tuple containing the t-statistic and p-value, accessible via result.statistic and result.pvalue.
Example
python
from analysistoolbox.hypothesis_testing import TwoSampleTTestOfIndependence
import pandas as pd
import numpy as np
# Compare average sales between two different regions
df = pd.DataFrame({
'sales': np.random.normal(500, 50, 40),
'region': ['East'] * 20 + ['West'] * 20
})
results = TwoSampleTTestOfIndependence(
dataframe=df,
outcome_column='sales',
grouping_column='region'
)