pyaerial: scalable association rule mining

---

<div align="center"> <img src="https://img.shields.io/badge/python-3.9%2C3.10%2C3.11%2C3.12-blue" alt="Python Versions"> <img src="https://img.shields.io/pypi/v/pyaerial.svg" alt="PyPI Version"> <img src="https://static.pepy.tech/badge/pyaerial" alt="Downloads"> <img src="https://github.com/DiTEC-project/pyaerial/actions/workflows/tests.yml/badge.svg" alt="Build Status"> <img src="https://readthedocs.org/projects/pyaerial/badge/?version=latest" alt="Documentation Status"> <img src="https://img.shields.io/badge/license-MIT-green" alt="License"> <img src="https://img.shields.io/github/stars/DiTEC-project/pyaerial.svg?style=social&label=Stars" alt="GitHub Stars"> </div>

---

<p align="center"> <a href="#installation">📥 Install</a> | <a href="#quick-start">🚀 Quick Start</a> | <a href="#features">✨ Features</a> | <a href="https://pyaerial.readthedocs.io">📚 Documentation</a> | <a href="https://github.com/DiTEC-project/pyaerial/releases">📋 Releases</a> | <a href="#citation">📄 Cite</a> | <a href="#contribute">🤝 Contribute</a> | <a href="LICENSE">🔑 License</a> </p>

PyAerial finds human-readable IF-THEN rules in tabular data:

Congressional voting records dataset:
IF adoption-of-the-budget-resolution=No AND physician-fee-freeze=Yes THEN Class=republican  (support=0.32, confidence=0.96, zhangs=0.90)
IF adoption-of-the-budget-resolution=y AND physician-fee-freeze=n THEN Class=democrat  (support=0.50, confidence=1.00, zhangs=0.78)

Iris dataset (plants) - numerical:
IF sepal width=(2, 2.9] AND petal width=(1.6, 2.5] THEN class=Iris-virginica  (support=0.12, confidence=1.00, zhangs=0.76)
IF petal length=(1, 2.63] AND petal width=(0.1, 0.87] THEN class=Iris-setosa  (support=0.33, confidence=1.00, zhangs=1.00)

Mushroom dataset:
IF odor=none AND gill-size=broad THEN poisonous=No  (support=0.40, confidence=0.98, zhangs=0.79)
IF gill-spacing=close AND stalk-surface-above-ring=silky THEN edibility=poisonous  (support=0.27, confidence=1.00, zhangs=0.71)

Datasets are from the UCI ML Repository.

It is the Python implementation of Aerial, a scalable neurosymbolic association rule miner: an under-complete Autoencoder learns a compact representation of the data, and rules are extracted from the trained model. This avoids the rule explosion and execution time problems of exhaustive miners (Apriori, FP-Growth, ECLAT), making rule mining practical on large datasets such as health records, retail baskets, and sensor data, wherever you want interpretable patterns next to black-box models.

Learn more about the architecture, training, and rule extraction in our paper: Neurosymbolic Association Rule Mining from Tabular Data

---

Why PyAerial?

| | PyAerial | Exhaustive miners (e.g., Mlxtend, SPMF) | |----------------------------------------|----------------------------------------------------------------------|------------------------------------------------| | Execution time on large data | 100-1000x faster, also on CPU | Grows steeply with columns and thresholds | | Number of rules | Concise, high-quality set with full data coverage | Rule explosion (easily millions) | | Input format | pandas DataFrame, one-hot encoding handled internally | Manual one-hot encoding or custom text formats | | Rule quality metrics | Calculated automatically (support, confidence, Zhang's metric, ...) | Requires extra steps | | Item constraints, classification rules | Built-in | Limited or unavailable | | GPU support | Optional | Not available |

For comprehensive benchmarks against Mlxtend, SPMF and other ARM tools, see our software paper: PyAerial: Scalable association rule mining from tabular data (SoftwareX, 2025)

<div align="center"> <img src="https://raw.githubusercontent.com/DiTEC-project/pyaerial/main/docs/source/_static/assets/benchmark.png" alt="PyAerial performance comparison" width="700"> <p><i>Execution time comparison across datasets of varying sizes. PyAerial scales linearly while traditional methods (e.g., Mlxtend, SPMF) exhibit exponential growth.</i></p> </div>

---

Installation

pip install pyaerial

Note: Examples in the documentation use ucimlrepo to fetch sample datasets. Install it to run the examples:

pip install ucimlrepo

Data Requirements: PyAerial works with categorical data. Numerical columns must be discretized first, using the built-in discretization module. There is no need to one-hot encode your data; PyAerial handles that automatically.

---

Quick Start

Or try it directly in your browser:

Basic Association Rule Mining

from aerial import model, rule_extraction
from ucimlrepo import fetch_ucirepo

# Load a categorical tabular dataset
breast_cancer = fetch_ucirepo(id=14).data.features

# Train an autoencoder on the loaded table
trained_autoencoder = model.train(breast_cancer)

# Extract association rules with quality metrics calculated automatically
result = rule_extraction.generate_rules(trained_autoencoder, min_rule_frequency=0.1, min_rule_strength=0.8)

print(f"Overall statistics: {result['statistics']}\n")
print(f"Sample rule: {result['rules'][0]}")

Output:

Overall statistics: {
    "rule_count": 15,
    "average_support": 0.448,
    "average_confidence": 0.881,
    "average_coverage": 0.860,
    "data_coverage": 0.923,
    "average_zhangs_metric": 0.318
}

Sample rule: {
    "antecedents": [{"feature": "inv-nodes", "value": "0-2"}],
    "consequent": {"feature": "node-caps", "value": "no"},
    "support": 0.702,
    "confidence": 0.943,
    "zhangs_metric": 0.69,
    "rule_coverage": 0.744
}

Interpretation: When inv-nodes is between 0-2, there's 94.3% confidence that node-caps equals no, covering 70.2% of the dataset.

Quality metrics explained:

• Support: Frequency of the rule in the dataset (how often the pattern occurs)
• Confidence: How often the consequent is true when antecedent is true (rule reliability)
• Zhang's Metric: Correlation measure between antecedent and consequent (-1 to 1; positive values indicate positive correlation)
• Rule Coverage: Proportion of transactions containing the antecedents
• Data Coverage (in statistics): Overall proportion of the dataset covered by at least one rule

Rules are plain dictionaries, so working with them is straightforward:

for rule in result['rules']:
    antecedents = " AND ".join(f"{a['feature']}={a['value']}" for a in rule['antecedents'])
    consequent = f"{rule['consequent']['feature']}={rule['consequent']['value']}"
    print(f"IF {antecedents} THEN {consequent} (support: {rule['support']:.2f}, conf: {rule['confidence']:.2f})")

Working with Numerical Data

For datasets with numerical columns, use PyAerial's built-in discretization methods:

from aerial import model, rule_extraction, discretization
from ucimlrepo import fetch_ucirepo

# Load a numerical dataset (e.g., Iris)
iris = fetch_ucirepo(id=53).data.features

# Discretize numerical columns into categorical bins
# Before: sepal_length = 5.1, 4.9, 7.0, ...  After: sepal_length = (4.8, 5.5], (4.8, 5.5], (6.4, 7.9], ...
iris_discretized = discretization.equal_frequency_discretization(iris, n_bins=3)

# Train and extract rules as usual
trained_autoencoder = model.train(iris_discretized, epochs=10)
result = rule_extraction.generate_rules(trained_autoencoder, min_rule_frequency=0.1)

Eight discretization methods are available: unsupervised (equal-frequency, equal-width, k-means, quantile, custom bins) and supervised (entropy-based, ChiMerge, decision tree), each documented with academic references in the User Guide.

More Recipes

| Goal | How | Details | |--------------------------------------------------|----------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------| | Focus mining on features of interest | generate_rules(model, features_of_interest=["age", {"menopause": "premeno"}]) | Item constraints | | Classification rules (class label as consequent) | generate_rules(model, target_classes=["Class"]) | Classification rules | | Keep only high-quality rules | generate_rules(model, filter_min_confidence=0.7, filter_min_support=0.1) | Parameter guide | | Frequent itemsets instead of rules | `generate_frequent_itemsets(model)