association_rules is the mlxtend.frequent_patterns function that derives association rules from a DataFrame of frequent itemsets (as produced by apriori, fpgrowth, or fpmax) and computes rule “interestingness” metrics (e.g., confidence, lift).

from mlxtend.frequent_patterns import association_rules

1) Core Concept: What an Association Rule Is

An association rule is an implication of the form:

  • A → C
    where A (antecedent) and C (consequent) are disjoint itemsets (no overlapping items).

A concrete consumer example is:

  • {Diapers} → {Beer}

This is interpreted as: transactions containing Diapers are also likely to contain Beer (association, not causation).

2) Metrics Used to Evaluate Rules

The function can compute multiple metrics. In the rule A → C, A is the antecedent and C is the consequent.

Support

  • Definition: support(A → C) = support(A ∪ C)
  • Range: [0, 1]

In the output, you typically see:

  • antecedent support = support(A)
  • consequent support = support(C)
  • support = support(A ∪ C)

Support is primarily used to measure how common an itemset (or rule union) is. An itemset is “frequent” if its support is ≥ a minimum support threshold. By the downward-closure property, if an itemset is frequent, then all of its subsets are also frequent.

Confidence

  • Definition: confidence(A → C) = support(A ∪ C) / support(A)
  • Range: [0, 1]

Interpretation: among transactions containing A, the fraction that also contain C.
Confidence is directional: confidence(A → C) generally differs from confidence(C → A).
Confidence reaches 1 if C appears in every transaction where A appears.

Lift

  • Definition: lift(A → C) = confidence(A → C) / support(C)
  • Range: [0, ∞)

Lift measures how much more often A and C occur together than expected under independence:

  • If A and C are independent, lift = 1.
  • Lift > 1 suggests positive association (co-occurs more than expected).
  • Lift < 1 suggests negative association (co-occurs less than expected).

Leverage

  • Definition: leverage(A → C) = support(A ∪ C) − support(A) × support(C)
  • Range: [-1, 1]

Leverage is the difference between observed co-occurrence and expected co-occurrence under independence.

  • leverage = 0 indicates independence.

Conviction

  • Definition: conviction(A → C) = (1 − support(C)) / (1 − confidence(A → C))
  • Range: [0, ∞)

Conviction increases as the consequent becomes more dependent on the antecedent.
If confidence = 1, the denominator becomes 0 and conviction is reported as inf (infinite).

Zhang’s Metric

  • Definition (as given): compares confidence to the confidence under “not A” and scales it
  • Range: [-1, 1]

Positive values indicate association; negative values indicate dissociation.

Jaccard

  • Definition: support(A ∪ C) / (support(A) + support(C) − support(A ∪ C))
  • Range: [0, 1]

Measures similarity of A and C as sets of transactions.

Certainty

  • Definition: (confidence(A → C) − support(C)) / (1 − support(C))
  • Range: [-1, 1]

0 indicates independence under this scaling.

Kulczynski

  • Definition: average of conditional probabilities in both directions
  • Range: [0, 1]

Rules near 0 or 1 are interpreted as strongly negative/positive association; near ~0.5 are often considered uninteresting.

3) Basic Usage: From Frequent Itemsets to Rules

Inputs

association_rules expects a DataFrame of frequent itemsets with at least:

  • itemsets (typically frozensets)
  • support

This frequent-itemset DataFrame can be generated by:

  • apriori(df, ...)
  • fpgrowth(df, ...)
  • fpmax(df, ...)

Rule selection mechanism

You choose:

  • a metric (e.g., "confidence" or "lift")
  • a minimum threshold for that metric (min_threshold)

Examples conceptually:

  • “Keep only rules with confidence ≥ 0.7”
  • “Keep only rules with lift ≥ 1.2”

The output is a rule table including columns such as:

  • antecedents, consequents
  • antecedent support, consequent support, support
  • metric columns: confidence, lift, leverage, conviction, etc.

4) Filtering and Post-Processing Rules (Pandas Workflow)

Because the output is a pandas DataFrame, you commonly:

  1. Create derived columns (e.g., antecedent length)
  2. Filter by multiple conditions (e.g., antecedent length, confidence, lift)
  3. Subset columns to keep the rule table readable

A typical derived feature is:

  • antecedent_len = len(antecedents)

Then you can filter for rules such as:

  • at least 2 antecedent items
  • confidence > 0.75
  • lift > 1.2

5) Frozensets and Rule Matching

antecedents and consequents are typically stored as frozensets:

  • order does not matter
  • {'Eggs','Kidney Beans'} equals {'Kidney Beans','Eggs'}

So selecting a rule by exact antecedent set is order-invariant.

6) Incomplete Frequent-Itemset Input and support_only=True

The problem

Most metrics require subset supports (e.g., support(A) and support(C)).
If your frequent-itemset DataFrame is “cropped” and does not include subset supports, then metrics like confidence cannot be computed correctly because support(A) is missing.

The solution

Use:

  • support_only=True

This instructs the function to compute only:

  • support(A → C) = support(A ∪ C)

All other metric columns become NaN, because they depend on missing supports.

This is useful when:

  • you only trust or only have the support of combined itemsets,
  • or you intentionally want rule supports without additional assumptions.

7) Handling Missing Values (null_values=True) and “Representativity”

The documentation you provided describes an extension to generate rules when the transaction matrix contains missing values (NaNs).

Key idea

When values are missing, supports and confidences are redefined using counts that exclude disabled/unknown observations, tracking cases such as:

  • missing in antecedent
  • missing in consequent
  • missing in both
  • missing in consequent while antecedent is present (and vice versa)

In this mode, the function uses a “disabled” structure derived from the original DataFrame (conceptually: missing values flagged) and maintains counts needed to compute revised metrics.

Reformulated metrics (as provided)

  • Support(A → C) uses counts adjusted by the number of disabled (missing) cases relevant to A and/or C.
  • Confidence(A → C) similarly adjusts the denominator to avoid treating missing as false.
  • A new metric, representativity(A), is introduced to quantify how much usable information is present for itemset A across transactions:
    • representativity ranges in [0, 1]
    • lower representativity implies more missingness affecting that itemset

All other metrics keep their original functional forms but are computed from the redefined support and confidence.

8) Practical Notes on Warnings and “inf” Values

In the provided examples, warnings like:

  • RuntimeWarning: invalid value encountered in divide

can occur when denominators become 0 in certain metric formulas (e.g., certainty scaling or conviction when confidence = 1). In such cases:

  • some metrics may produce 0, NaN, or inf, depending on the internal safeguard used.

This is expected behavior for edge cases such as perfect confidence rules.

9) What You Typically Do in a Workflow

A standard association-rule workflow in mlxtend is:

  1. One-hot encode transactions (dense or sparse).
  2. Compute frequent itemsets (apriori / fpgrowth / fpmax) with min_support.
  3. Generate rules with association_rules(frequent_itemsets, metric=..., min_threshold=...).
  4. Filter by interpretability constraints (antecedent size, lift, confidence).
  5. Optionally prune specific rules using boolean masks.
  6. If input is incomplete, use support_only=True.
  7. If missing values exist, use the null_values=True pathway and interpret representativity.