View on GitHub

arulespy

Python interface to arules for association rule mining

Python interface to the R package arules

PyPI package version number Actions Status License

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:

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.

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

Installation

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

Using an existing R installation

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")'

Troubleshooting

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.

Example

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()
LHS RHS support confidence coverage lift count
{} {A} 1.0 1.0 1.0 1.000000 5
{B} {C} 0.6 1.0 0.6 1.666667 3
{C} {B} 0.6 1.0 0.6 1.666667 3
{B} {A} 0.6 1.0 0.6 1.000000 3
{C} {A} 0.6 1.0 0.6 1.000000 3
{B,C} {A} 0.6 1.0 0.6 1.000000 3
{A,B} {C} 0.6 1.0 0.6 1.666667 3
{A,C} {B} 0.6 1.0 0.6 1.666667 3

Complete examples:

References