CreateAssociationRules — Analysis Tool Box

Introduction

Which items get bought together often enough to matter — and is that co-occurrence a real signal or just what you'd expect by chance? CreateAssociationRules runs market basket analysis with the Apriori algorithm on transactional data, surfacing "if a customer buys X, they also tend to buy Y" rules along with the metrics needed to judge whether each rule is worth acting on: support (how common the pattern is), confidence (how reliable it is), and lift (how much more likely the items are to co-occur than chance would predict). It also produces a scatter plot that separates genuinely positive associations from negative or coincidental ones.

Teaching Note

Association rule mining is essential for:

Retail product placement and store layout optimization
E-commerce recommendation engines and "customers who bought X also bought Y"
Cross-selling and upselling strategies
Inventory management and demand forecasting
Marketing campaign targeting and bundle pricing
Customer behavior analysis and segmentation
Fraud detection in financial transactions
Medical diagnosis and treatment pattern discovery

Parameters

Parameter	Default	Description
`dataframe`required	—	A pandas DataFrame in long format where each row represents a single item within a transaction. Must contain columns for transaction IDs and item names.
`transaction_id_column`required	—	Name of the column containing transaction identifiers. Multiple rows with the same transaction ID represent items purchased together in one transaction.
`items_column`required	—	Name of the column containing item names or product identifiers that will be analyzed for co-occurrence patterns.
`support_threshold`	`0.01`	Minimum support value (0-1) for an itemset to be considered frequent. Support is the proportion of transactions containing the itemset. Lower values find more rules but increase computation time. Defaults to 0.01 (1%).
`confidence_threshold`	`0.05`	Minimum confidence value (0-1) for a rule to be included. Confidence is the probability that the consequent occurs given the antecedent. Higher values yield stronger rules. Defaults to 0.05 (5%).
`plot_lift`	`True`	Whether to generate a scatter plot visualizing the association rules with confidence vs. consequent support, color-coded by lift. Defaults to True.
`dot_fill_color`	`'#999999'`	Hex color code for the scatter plot points representing association rules. Defaults to '#999999' (gray).
`upper_left_quadrant_fill_color`	`'#32a852'`	Hex color code for shading the high-lift region (where confidence > consequent support). Defaults to '#32a852' (green).
`lower_right_quadrant_fill_color`	`'#d14a41'`	Hex color code for shading the low-lift region (where confidence < consequent support). Defaults to '#d14a41' (red).
`draw_life_equals_1_line`	`True`	Whether to draw a diagonal reference line where lift equals 1 (independence). Defaults to True.
`title_for_plot`	`'Association Rules'`	Main title text for the visualization. Defaults to 'Association Rules'.
`subtitle_for_plot`	`'Confidence vs. Consequent Support'`	Subtitle text providing additional context. Defaults to 'Confidence vs. Consequent Support'.
`caption_for_plot`	`'Lift is a measure of how much more likely it is for two items to occur together than expected by chance...'`	Explanatory caption describing lift interpretation. Defaults to a detailed explanation of lift values.
`data_source_for_plot`	`None`	Optional attribution text for data source, appended to caption. Defaults to None.
`x_indent`	`-0.128`	Horizontal position adjustment for plot title, subtitle, and caption. Defaults to -0.128.
`title_y_indent`	`1.125`	Vertical position for the plot title relative to axes. Defaults to 1.125.
`subtitle_y_indent`	`1.05`	Vertical position for the plot subtitle relative to axes. Defaults to 1.05.
`caption_y_indent`	`-0.3`	Vertical position for the plot caption relative to axes. Defaults to -0.3.

Returns

A pandas DataFrame of discovered association rules with columns (in title case): Antecedents, Consequents, Antecedent Support, Consequent Support, Support, Confidence, Lift, Leverage, and Conviction. Sorted by confidence (descending) and consequents (ascending).

Example

python

from analysistoolbox.descriptive_analytics import CreateAssociationRules
import pandas as pd

# E-commerce product recommendations
orders_df = pd.DataFrame({
    'order_id': [1, 1, 1, 2, 2, 3, 3, 3, 4, 4],
    'product': ['laptop', 'mouse', 'keyboard', 'laptop', 'mouse',
                'monitor', 'keyboard', 'mouse', 'laptop', 'keyboard']
})
rules_df = CreateAssociationRules(
    orders_df,
    transaction_id_column='order_id',
    items_column='product',
    support_threshold=0.2,
    confidence_threshold=0.5,
    plot_lift=True
)
# Discover which products are frequently bought together