Python interface to the R package arules

arulespy is a Python package available from PyPI. Its arules module provides a Python interface to the popular R package arules for association rule mining built with rpy2.

The R arules package implements a comprehensive infrastructure for representing, manipulating and analyzing transaction data and patterns using frequent itemsets and association rules. The package also provides a wide range of interest measures and mining algorithms including the code of Christian Borgelt’s popular and efficient C implementations of the association mining algorithms Apriori and Eclat, and optimized C/C++ code for mining and manipulating association rules using sparse matrix representation.

The arulesViz module provides plot() for visualizing association rules using the R package arulesViz.

arulespy provides Python classes for:

• Transactions: transaction data, including conversion from pandas DataFrames
• Rules: association rules
• Itemsets: itemsets
• ItemMatrix: sparse representations of sets of items

These classes support len(), integer indexing, negative indexing, integer sequences, boolean masks, and Python-style slicing.

Python-style snake-case names are available for APIs inherited from R, such as item_frequency(), item_info(), item_labels(), interest_measure(), add_quality(), arules_to_py(), discretize_df(), inspect_dt(), and rule_explorer(). Interactive R HTML widgets can be embedded reliably in notebooks with html_widget(). The original R-style names remain available for compatibility.

Most arules operations are exposed as methods on these classes, with common R results converted into pandas, NumPy, or SciPy objects. API documentation is available through Python's help(). See the arules reference manual for details about the underlying R operations.

The documentation site includes examples and installation instructions.

For low-level access, import R_arules and call translated R function names, for example R_arules.random_transactions(...). These calls return rpy2 objects. Convert supported R objects into arulespy or standard Python objects with arules_to_py().

To cite the Python module ‘arulespy’ in publications use:

Michael Hahsler. ARULESPY: Exploring association rules and frequent itemsets in Python. arXiv:2305.15263 [cs.DB], May 2023. DOI: 10.48550/arXiv.2305.15263

arulespy supports Python 3.11 through 3.14. It uses rpy2 and requires R 4.5 or later with the R package arules. The R package arulesViz is optional and is needed only for visualization functions.

Importing arulespy by itself does not initialize R or install R packages. When arulespy.arules is first imported, a missing arules package is installed automatically from CRAN. Importing arulespy.arulesViz likewise installs arulesViz if needed.

Installing R packages from source can take some time. Conda is recommended for the compatible Python, R, arules, and rpy2 core environment.

Using conda (for example, Miniconda) is recommended because it installs compatible versions of Python, R, arules, and rpy2 together. Create and activate a dedicated environment:

conda create --name arulespy -c conda-forge \
    python=3.13 r-base r-arules rpy2 pip
conda activate arulespy

Then install arulespy from PyPI:

python -m pip install arulespy

The optional arulesViz package can be installed with:

conda install -c conda-forge \
      r-dt r-ggraph r-igraph r-plotly r-visnetwork
Rscript -e 'install.packages("arulesViz", repos="https://cloud.r-project.org")'

Note: arulesViz is installed from CRAN since r-arulesViz is currently not available for this Python 3.13 Conda environment due to conflicts with the newer R required by current rpy2. Once it becomes available, then it can be installed with conda.

conda install -c conda-forge r-arulesviz

Make sure that R 4.5 or later is available on PATH, then install the Python package:

python -m pip install arulespy

The required R packages will be installed automatically when their respective interfaces are imported. To avoid installation during import, preinstall them with R:

Rscript -e 'install.packages(c("arules", "arulesViz"), repos="https://cloud.r-project.org")'

If rpy2 cannot find R or its shared library, inspect the configuration with python -m rpy2.situation. From a Python session or notebook, use:

from rpy2 import situation

for row in situation.iter_info():
    print(row)

The output should contain Loading R library from rpy2: OK.

On Linux, if R is on PATH but its shared library cannot be loaded, set the library path reported by rpy2 before starting Python:

export LD_LIBRARY_PATH="$(python -m rpy2.situation LD_LIBRARY_PATH):${LD_LIBRARY_PATH}"

On Windows, the conda installation above is recommended. For a separate R installation, make sure R's binary directory is on PATH and, if needed, that R_HOME points to the R installation directory. Consult the current rpy2 installation documentation when diagnosing native installation problems.

import pandas as pd

from arulespy import Transactions, apriori, parameters

# Define transaction data as a pandas DataFrame.
df = pd.DataFrame(
    [
        [True, True, True],
        [True, False, False],
        [True, True, True],
        [True, False, False],
        [True, True, True],
    ],
    columns=list("ABC"),
)

# Convert the DataFrame to transactions.
transactions = Transactions.from_df(df)

# Mine association rules.
rules = apriori(
    transactions,
    parameter=parameters({"supp": 0.1, "conf": 0.8}),
    control=parameters({"verbose": False}),
)

# Display the rules as a pandas DataFrame.
rules.as_df()

Complete examples:

• Using arules
• Using arulesViz

The site is built with Material for MkDocs and deployed to GitHub Pages by the Docs workflow. To preview the Markdown pages locally:

python -m pip install -r requirements-docs.txt
python -m mkdocs serve

The workflow builds the site with python -m mkdocs build --strict and copies the exported HTML examples and Zoo.csv into site/examples/ before publishing. In the repository's GitHub Pages settings, select GitHub Actions as the build and deployment source.

• Michael Hahsler. ARULESPY: Exploring association rules and frequent itemsets in Python. arXiv:2305.15263 [cs.DB], May 2023. DOI: 10.48550/arXiv.2305.15263
• Michael Hahsler, Sudheer Chelluboina, Kurt Hornik, and Christian Buchta. The arules R-package ecosystem: Analyzing interesting patterns from large transaction datasets. Journal of Machine Learning Research, 12:1977-1981, 2011.
• Michael Hahsler, Bettina Grün and Kurt Hornik. arules - A Computational Environment for Mining Association Rules and Frequent Item Sets. Journal of Statistical Software, 14(15), 2005. DOI: 10.18637/jss.v014.i15
• Hahsler, Michael. A Probabilistic Comparison of Commonly Used Interest Measures for Association Rules, 2015, URL: https://mhahsler.github.io/arules/docs/measures.
• Michael Hahsler. An R Companion for Introduction to Data Mining: Chapter 5, 2021, URL: https://mhahsler.github.io/Introduction_to_Data_Mining_R_Examples/book/