Introduction
Are two categorical variables actually related, or does it just look that way in a cross-tab? ChiSquareTestOfIndependence runs the chi-square test of independence directly on raw data: it builds the contingency table for you, compares the observed cell counts against what independence would predict, and reports the chi-square statistic, degrees of freedom, and p-value — along with a clustered bar chart that makes it easy to see exactly which category combinations are driving the association.
Teaching Note
The chi-square test of independence is essential for:
- Determining if two categorical variables are related or independent
- Analyzing survey data and cross-tabulations
- Testing associations in medical and clinical research
- Market research and customer segmentation analysis
- Quality control and process improvement studies
- Social science research on demographic patterns
- A/B testing and experimental design validation
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dataframerequired | | — | The pandas DataFrame containing the categorical variables to analyze. |
categorical_outcome_columnrequired | | — | Name of the column containing the categorical outcome variable (dependent variable). This will be displayed on the x-axis of the visualization. |
categorical_predictor_columnrequired | | — | Name of the column containing the categorical predictor variable (independent variable). This will be used to create separate facets in the visualization. |
show_contingency_tables | | True | If True, prints the observed and expected contingency tables to the console. Defaults to True. |
show_plot | | True | If True, displays a clustered bar chart comparing observed and expected counts for each combination of categories. Defaults to True. |
color_palette | | 'Paired' | Seaborn color palette name to use for the plot bars. Defaults to 'Paired'. |
fill_transparency | | 0.8 | Transparency level for the bars in the plot, ranging from 0 (transparent) to 1 (opaque). Defaults to 0.8. |
figure_size | | (6, 8) | Tuple specifying the (width, height) of each subplot in inches. Defaults to (6, 8). |
title_for_plot | | 'Chi-Square Test of Independence' | Main title text to display at the top of the plot. Defaults to 'Chi-Square Test of Independence'. |
subtitle_for_plot | | 'Shows observed vs. expected counts' | Subtitle text to display below the main title. Defaults to 'Shows observed vs. expected counts'. |
caption_for_plot | | 'Expected counts are based on the null hypothesis of no association between the two variables.' | Caption text to display at the bottom of the plot explaining the visualization. |
data_source_for_plot | | None | Optional text identifying the data source, displayed in the caption area. If None, no data source is shown. Defaults to None. |
x_indent | | -0.95 | Horizontal position for left-aligning title, subtitle, and caption text. Defaults to -0.95. |
title_y_indent | | 1.15 | Vertical position for the main title relative to the plot. Defaults to 1.15. |
title_font_size | | 14 | Font size in points for the main title. Defaults to 14. |
subtitle_y_indent | | 1.1 | Vertical position for the subtitle relative to the plot. Defaults to 1.1. |
subtitle_font_size | | 11 | Font size in points for the subtitle. Defaults to 11. |
caption_y_indent | | -0.15 | Vertical position for the caption relative to the plot. Defaults to -0.15. |
caption_font_size | | 8 | Font size in points for the caption text. Defaults to 8. |
decimal_places_for_data_label | | 1 | Number of decimal places to display in the bar chart data labels. Defaults to 1. |
Returns
A pandas DataFrame with the observed count, expected count, and the difference (observed minus expected) for each combination of the outcome and predictor categories, alongside columns for the outcome variable and predictor variable.
Example
python
from analysistoolbox.hypothesis_testing import ChiSquareTestOfIndependence
import pandas as pd
# Test independence between gender and product preference
df = pd.DataFrame({
'gender': ['Male', 'Male', 'Female', 'Female', 'Male', 'Female'] * 20,
'product': ['A', 'B', 'A', 'B', 'A', 'B'] * 20
})
results = ChiSquareTestOfIndependence(
dataframe=df,
categorical_outcome_column='product',
categorical_predictor_column='gender'
)