Introduction
Sometimes the data you have to work with is already a published cross-tabulation, not raw records — a table from a report, a summary from another team, a historical dataset where only the counts survive. ChiSquareTestOfIndependenceFromTable runs the chi-square test of independence directly on that summarized contingency table, computing the chi-square statistic, degrees of freedom, and p-value without needing the underlying rows, and produces the same observed-vs-expected bar chart you'd get from raw data.
Teaching Note
The chi-square test of independence from a table is essential for:
- Analyzing research results presented in summary format
- Validating published findings from cross-tabulations
- Comparing experimental results against theoretical distributions
- Assessing associations in historical data where raw records are unavailable
- Evaluating market share distributions across different segments
- Performing meta-analysis on aggregated categorical data
- Conducting quick diagnostic tests on frequency counts
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
contingency_tablerequired | | — | A pandas DataFrame representing the contingency table. The rows should represent one categorical variable (accessible via the index) and the columns should represent another. The values must be non-negative frequency counts. |
column_wise_variable_namerequired | | — | A descriptive name for the categorical variable represented by the columns of the contingency table. This name will be used in the visualization and results. |
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. 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 categories, plus columns for both categorical variables.
Example
python
from analysistoolbox.hypothesis_testing import ChiSquareTestOfIndependenceFromTable
import pandas as pd
# Test independence between hair color and eye color from a summary table
data = {
'Blue Eyes': [10, 15, 5],
'Brown Eyes': [12, 10, 25]
}
table = pd.DataFrame(data, index=['Blonde Hair', 'Brown Hair', 'Black Hair'])
table.index.name = 'Hair Color'
results = ChiSquareTestOfIndependenceFromTable(
contingency_table=table,
column_wise_variable_name='Eye Color'
)