pyaerial: scalable association rule mining

---

---

📥 Install | 🚀 Quick Start | ✨ Features | 📚 Documentation | 📋 Releases | 📄 Cite | 🤝 Contribute | 🔑 License

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)

Execution time comparison across datasets of varying sizes. PyAerial scales linearly while traditional methods (e.g., Mlxtend, SPMF) exhibit exponential growth.

---

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)	API reference
Antecedents of unlimited length	generate_rules(model, max_antecedents=None)	Parameter guide
Visualize rules	Via NiaARM	User guide

Can't get the results you're looking for?

• Parameter Tuning Guide: quick reference for high/low support, confidence, and rule count
• Troubleshooting: what to do when Aerial doesn't find rules or takes too long
• Training and Rule Quality: training duration and architecture optimization

Note on Parameter Names: The parameters min_rule_frequency and min_rule_strength correspond to ant_similarity and cons_similarity in the original Aerial and PyAerial papers.

---

Features

Rule mining

• Scalable association rule mining without rule explosion, with full data coverage
• Frequent itemset mining with the same neural approach
• Item constraints (features of interest) and classification rules (target classes)
• Quality metrics calculated automatically: support, confidence, Zhang's metric, lift, conviction, Yule's Q, interestingness, leverage

Data handling

• Direct pandas DataFrame input; one-hot encoding handled internally
• Eight discretization methods for numerical columns (unsupervised and supervised)

Performance

• Fast on CPU; optional GPU acceleration for very large datasets
• Post-filters (filter_min_confidence, filter_min_support) for high-quality rule sets

Customization and integration

• Customizable Autoencoder architecture and training (epochs, learning rate, batch size, masking window)
• Rule visualization via NiaARM; interpretable inference via imodels

---

How Aerial Works

Aerial employs a three-stage neurosymbolic pipeline:

1. Data Preparation. Categorical data is one-hot encoded while tracking feature relationships; numerical columns are pre-discretized. The encoded values form the input vectors of the Autoencoder.

2. Autoencoder Training. An under-complete Autoencoder is trained with a masking mechanism: each batch randomly corrupts a subset of features to a uniform "unknown" distribution, and the network learns to reconstruct them from the remaining unmasked features. Masking mirrors the antecedent to consequent query pattern used during rule extraction, an improvement over the Gaussian-noise-based denoising of the original Aerial+ paper.

3. Rule Extraction. Rules are extracted by querying the trained Autoencoder with test vectors:

1. Test vectors are created with equal probabilities across categories
2. Specific feature values are marked as antecedents while others remain at baseline
3. Forward runs through the network produce implication probabilities
4. Rules are extracted when implication probabilities exceed the rule frequency and strength thresholds
5. Antecedent combinations are searched with an FP-Growth-style growth strategy: only combinations whose estimated frequency passes the threshold are extended further, so forward runs scale with the number of frequent combinations rather than all possible combinations (max_antecedents=None mines antecedents of unlimited length)
6. Quality metrics (support, confidence, coverage, Zhang's metric, etc.) are calculated automatically using vectorized operations

Aerial+ replaces the counting operation of classical rule mining with the Autoencoder's implication probabilities, so in principle the search strategy of any rule miner can run on top of it. PyAerial adopts FP-Growth's, as it is among the fastest rule miners.

Example: Rule extraction process using weather and beverage features

Complete three-stage pipeline: data preparation → training → rule extraction

For the architecture, theoretical foundations, and experimental results, see How Aerial Works in the documentation and the paper.

---

Documentation

Read the full documentation on ReadTheDocs | Release notes on GitHub Releases

• Getting Started: installation and basic usage
• User Guide: detailed examples covering all features
• Parameter Tuning Guide: defaults, tuning for specific goals, troubleshooting
• Configuration: GPU usage, logging, custom Autoencoders
• API Reference: complete function and class documentation
• How Aerial Works: the neurosymbolic architecture and algorithm

---

Citation

If you use PyAerial in your work, please cite our research and software papers:

@InProceedings{pmlr-v284-karabulut25a,
  title         = {Neurosymbolic Association Rule Mining from Tabular Data},
  author        = {Karabulut, Erkan and Groth, Paul and Degeler, Victoria},
  booktitle     = {Proceedings of The 19th International Conference on Neurosymbolic Learning and Reasoning},
  pages         = {565--588},
  year          = {2025},
  editor        = {H. Gilpin, Leilani and Giunchiglia, Eleonora and Hitzler, Pascal and van Krieken, Emile},
  volume        = {284},
  series        = {Proceedings of Machine Learning Research},
  month         = {08--10 Sep},
  publisher     = {PMLR},
  url           = {https://proceedings.mlr.press/v284/karabulut25a.html}
}

@article{pyaerial,
  title         = {PyAerial: Scalable association rule mining from tabular data},
  journal       = {SoftwareX},
  volume        = {31},
  pages         = {102341},
  year          = {2025},
  issn          = {2352-7110},
  doi           = {https://doi.org/10.1016/j.softx.2025.102341},
  author        = {Erkan Karabulut and Paul Groth and Victoria Degeler},
}

---

Contact

For questions, suggestions, or collaborations: Erkan Karabulut, e.karabulut@uva.nl or erkankkarabulut@gmail.com

---

Contribute

Contributions are welcome: report bugs or suggest features by opening an issue, improve the documentation, or submit a pull request on GitHub.

Contributors

Made with contrib.rocks.

---

License

This project is licensed under the MIT License; see the LICENSE file for details.