Metadata-Version: 2.4
Name: action-rules
Version: 1.1.0
Summary: The package for action rules mining using Action-Apriori (Apriori Modified for Action Rules Mining)..
License: MIT
License-File: LICENSE
Author: Lukas Sykora
Author-email: lukas.sykora@vse.cz
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: dev
Provides-Extra: doc
Provides-Extra: inference
Provides-Extra: test
Provides-Extra: viz
Requires-Dist: black (>=24.4.2,<25.0.0) ; extra == "test"
Requires-Dist: bump2version (>=1.0.1,<2.0.0) ; extra == "dev"
Requires-Dist: click (==8.0.1)
Requires-Dist: flake8 (>=7.0.0,<8.0.0) ; extra == "test"
Requires-Dist: flake8-docstrings (>=1.7.0,<2.0.0) ; extra == "test"
Requires-Dist: isort (>=5.13.2,<6.0.0) ; extra == "test"
Requires-Dist: matplotlib (>=3.7,<4.0) ; extra == "test" or extra == "viz"
Requires-Dist: mkdocs (>=1.6.0,<2.0.0) ; extra == "doc"
Requires-Dist: mkdocs-autorefs (>=1.0.1,<2.0.0) ; extra == "doc"
Requires-Dist: mkdocs-include-markdown-plugin (>=6.1.1,<7.0.0) ; extra == "doc"
Requires-Dist: mkdocs-material (>=9.5.25,<10.0.0) ; extra == "doc"
Requires-Dist: mkdocstrings (>=0.25.1,<0.26.0) ; extra == "doc"
Requires-Dist: mkdocstrings-python (>=1.10.3,<2.0.0)
Requires-Dist: mypy (>=1.10.0,<2.0.0) ; extra == "test"
Requires-Dist: numpy (>=1.24,<2.0)
Requires-Dist: pandas (>=2.2.2,<3.0.0)
Requires-Dist: pip (>=24.0,<25.0) ; extra == "dev"
Requires-Dist: pre-commit (>=3.7.1,<4.0.0) ; extra == "dev"
Requires-Dist: pytest (>=8.2.1,<9.0.0) ; extra == "test"
Requires-Dist: pytest-cov (>=5.0.0,<6.0.0) ; extra == "test"
Requires-Dist: scipy (>=1.10,<2.0) ; extra == "test" or extra == "inference" or extra == "viz"
Requires-Dist: toml (>=0.10.2,<0.11.0) ; extra == "dev"
Requires-Dist: tox (>=4.15.0,<5.0.0) ; extra == "dev"
Requires-Dist: twine (>=5.1.0,<6.0.0) ; extra == "dev"
Requires-Dist: virtualenv (>=20.26.2,<21.0.0) ; extra == "dev"
Project-URL: Homepage, https://github.com/lukassykora/action-rules
Description-Content-Type: text/markdown

# Action Rules

[![pypi](https://img.shields.io/pypi/v/action-rules.svg)](https://pypi.org/project/action-rules/)
[![python](https://img.shields.io/pypi/pyversions/action-rules.svg)](https://pypi.org/project/action-rules/)
[![Build Status](https://github.com/lukassykora/action-rules/actions/workflows/dev.yml/badge.svg)](https://github.com/lukassykora/action-rules/actions/workflows/dev.yml)
[![codecov](https://codecov.io/gh/lukassykora/action-rules/branch/main/graphs/badge.svg)](https://codecov.io/github/lukassykora/action-rules)

The package for action rules mining using Action-Apriori (Apriori Modified for Action Rules Mining).

* Documentation: <https://lukassykora.github.io/action-rules>
* GitHub: <https://github.com/lukassykora/action-rules>
* PyPI: <https://pypi.org/project/action-rules/>
* Free software: MIT

## Installation

``` console
$ pip install action-rules
```

For command-line interface (CLI) usage, the action-rules package must be installed using pipx:
``` console
$ pipx install action-rules
```


## Features

### Action Rules API

```python
# Import Module
from action_rules import ActionRules
import pandas as pd

# Get Data
transactions = {'Sex': ['M', 'F', 'M', 'M', 'F', 'M', 'F'],
                'Age': ['Y', 'Y', 'O', 'Y', 'Y', 'O', 'Y'],
                'Class': [1, 1, 2, 2, 1, 1, 2],
                'Embarked': ['S', 'C', 'S', 'C', 'S', 'C', 'C'],
                'Survived': [1, 1, 0, 0, 1, 1, 0],
                }
data = pd.DataFrame.from_dict(transactions)
# Initialize ActionRules Miner with Parameters
stable_attributes = ['Age', 'Sex']
flexible_attributes = ['Embarked', 'Class']
target = 'Survived'
min_stable_attributes = 2
min_flexible_attributes = 1  # min 1
min_undesired_support = 1
min_undesired_confidence = 0.5  # min 0.5
min_desired_support = 1
min_desired_confidence = 0.5  # min 0.5
undesired_state = '0'
desired_state = '1'
# Action Rules Mining
action_rules = ActionRules(
    min_stable_attributes=min_stable_attributes,
    min_flexible_attributes=min_flexible_attributes,
    min_undesired_support=min_undesired_support,
    min_undesired_confidence=min_undesired_confidence,
    min_desired_support=min_desired_support,
    min_desired_confidence=min_desired_confidence,
    verbose=True
)
# Fit
action_rules.fit(
    data=data,  # cuDF or Pandas Dataframe
    stable_attributes=stable_attributes,
    flexible_attributes=flexible_attributes,
    target=target,
    target_undesired_state=undesired_state,
    target_desired_state=desired_state,
    use_sparse_matrix=True,  # needs SciPy or Cupyx (if use_gpu is True) installed
    use_gpu=False,  # needs Cupy installed
)
# Print rules
# Example: [(Age: O) ∧ (Sex: M) ∧ (Embarked: S → C)] ⇒ [Survived: 0 → 1], support of undesired part: 1, confidence of undesired part: 1.0, support of desired part: 1, confidence of desired part: 1.0, uplift: 1.0
for action_rule in action_rules.get_rules().get_ar_notation():
    print(action_rule)
# Print rules (pretty notation)
# Example: If attribute 'Age' is 'O', attribute 'Sex' is 'M', attribute 'Embarked' value 'S' is changed to 'C', then 'Survived' value '0' is changed to '1 with uplift: 1.0.
for action_rule in action_rules.get_rules().get_pretty_ar_notation():
    print(action_rule)
# JSON export
print(action_rules.get_rules().get_export_notation())
```

### Action Rules CLI

``` console
$ action-rules --min_stable_attributes 2 --min_flexible_attributes 1 --min_undesired_support 1 --min_undesired_confidence 0.5 --min_desired_support 1 --min_desired_confidence 0.5 --csv_path 'data.csv' --stable_attributes 'Sex, Age' --flexible_attributes 'Class, Embarked' --target 'Survived' --undesired_state '0' --desired_state '1' --output_json_path 'output.json'
```

### Confidence Intervals

Compute confidence intervals for uplift and realistic rule gain using one of three methods: **bootstrap**, **analytic** (Wald), or **Bayesian**.

```console
$ pip install action-rules[inference]   # adds scipy
$ pip install action-rules[viz]         # adds matplotlib + scipy
```

```python
from action_rules import ActionRules

# After fitting action rules...
action_rules = ActionRules(
    min_stable_attributes=2, min_flexible_attributes=1,
    min_undesired_support=1, min_undesired_confidence=0.5,
    min_desired_support=1, min_desired_confidence=0.5,
)
action_rules.fit(data, stable_attributes, flexible_attributes, target, '0', '1')

# Compute bootstrap confidence intervals
results = action_rules.confidence_intervals(
    data,
    method="bootstrap",      # "bootstrap", "analytic", "wald", or "bayesian"
    confidence_level=0.95,
    threshold=0.0,           # categorize rules as Accept/Reject/Uncertain
    n_bootstrap=1000,        # bootstrap resamples (bootstrap only)
    random_state=42,
)

# Each result contains: uplift_point, uplift_ci_lower, uplift_ci_upper, uplift_se,
# realistic_rule_gain_point/ci_lower/ci_upper/se (if utility tables provided),
# category (RuleCategory.ACCEPT / REJECT / UNCERTAIN)
for r in results:
    print(f"Rule {r.rule_index}: uplift = {r.uplift_point:.4f} "
          f"[{r.uplift_ci_lower:.4f}, {r.uplift_ci_upper:.4f}] → {r.category.value}")

# JSON export now includes CI data
print(action_rules.get_rules().get_export_notation())
```

#### Visualization

```python
from action_rules.visualization import bootstrap_histogram, forest_plot, grouped_forest_plot

# Single-rule distribution (bootstrap or Bayesian)
fig = bootstrap_histogram(results[0], metric="uplift", threshold=0.0)
fig.savefig("distribution.png")

# Forest plot: all rules with CI bars
fig = forest_plot(results, metric="uplift", threshold=0.0)
fig.savefig("forest.png")

# Compare methods side-by-side
results_boot = action_rules.confidence_intervals(data, method="bootstrap", random_state=42)
results_anal = action_rules.confidence_intervals(data, method="analytic")
results_bayes = action_rules.confidence_intervals(data, method="bayesian", random_state=42)

fig = grouped_forest_plot(
    {"bootstrap": results_boot, "analytic": results_anal, "bayesian": results_bayes},
    metric="uplift",
    threshold=0.0,
)
fig.savefig("comparison.png")
```

#### CLI with Confidence Intervals

``` console
$ action-rules --min_stable_attributes 2 --min_flexible_attributes 1 \
    --min_undesired_support 1 --min_undesired_confidence 0.5 \
    --min_desired_support 1 --min_desired_confidence 0.5 \
    --csv_path data.csv --stable_attributes 'Sex, Age' \
    --flexible_attributes 'Class, Embarked' --target Survived \
    --undesired_state 0 --desired_state 1 \
    --ci_method bootstrap --confidence_level 0.95 --n_bootstrap 1000 \
    --ci_threshold 0.0 --random_state 42 \
    --output_json_path output.json
```

Available CI options:
- `--ci_method` — `bootstrap`, `analytic`, `wald`, or `bayesian`
- `--confidence_level` — confidence level (default: 0.95)
- `--ci_threshold` — threshold for Accept/Reject/Uncertain categorization
- `--n_bootstrap` — number of bootstrap resamples (default: 1000)
- `--n_mc` — number of Monte Carlo draws for Bayesian (default: 10000)
- `--random_state` — random seed for reproducibility

## Jupyter Notebook Examples

* [Confidence Intervals (Bootstrap, Analytic, Bayesian)](https://github.com/lukassykora/action-rules/blob/main/notebooks/ConfidenceIntervals.ipynb)
* [Titanic Dataset (GPU accelerated)](https://github.com/lukassykora/action-rules/blob/main/notebooks/Example.ipynb)
* [Customer Churn (easy workflow)](https://github.com/lukassykora/action-rules/blob/main/notebooks/ExampleCustomerChurn.ipynb)
* [High-Utility Action Rules Mining Example](https://github.com/lukassykora/action-rules/blob/main/notebooks/Utility.ipynb)

## Hands-On Telco Tour

A two-notebook end-to-end walkthrough on the Telco Customer Churn dataset. Run them in order; together they take under a minute. ([folder README](https://github.com/lukassykora/action-rules/blob/main/notebooks/telco_tour/README.md))

* [End-to-end mining with utility tables, confidence intervals, and JSON export](https://github.com/lukassykora/action-rules/blob/main/notebooks/telco_tour/01_end_to_end_telco.ipynb)
* [Visual diagnostics: churn-rate panel, bootstrap distribution, forest plot, bootstrap vs analytic CI scatter](https://github.com/lukassykora/action-rules/blob/main/notebooks/telco_tour/02_visual_diagnostics.ipynb)

## Inference and Validation Studies

A self-contained suite of replicability notebooks for the package's confidence-interval and cross-validation tooling. Each notebook persists a CSV under `notebooks/inference_studies/results/` so the studies can be inspected without rerunning. ([folder README](https://github.com/lukassykora/action-rules/blob/main/notebooks/inference_studies/README.md))

* [Per-rule confidence intervals across five inference methods (bootstrap percentile/BCa, Wald, Wilson, Bayesian) on four benchmark datasets](https://github.com/lukassykora/action-rules/blob/main/notebooks/inference_studies/01_rule_level_confidence_intervals.ipynb)
* [Empirical coverage simulation: do the nominal 95% intervals actually cover 95% of the time?](https://github.com/lukassykora/action-rules/blob/main/notebooks/inference_studies/02_coverage_simulation.ipynb)
* [Runtime benchmark of every CI method on every dataset](https://github.com/lukassykora/action-rules/blob/main/notebooks/inference_studies/03_runtime_benchmark.ipynb)
* [Rule categorization (Accept / Reject / Uncertain) for uplift and realistic rule gain](https://github.com/lukassykora/action-rules/blob/main/notebooks/inference_studies/04_rule_categorization.ipynb)
* [Stratified K-fold cross-validation with four targeting strategies and three reliability views](https://github.com/lukassykora/action-rules/blob/main/notebooks/inference_studies/05_cross_validation.ipynb)
* [Sensitivity of the categorization to support-threshold perturbations](https://github.com/lukassykora/action-rules/blob/main/notebooks/inference_studies/06_threshold_sensitivity.ipynb)
* [Sensitivity of realistic rule gain to a uniform cost-side rescaling of the utility tables](https://github.com/lukassykora/action-rules/blob/main/notebooks/inference_studies/07_utility_table_sensitivity.ipynb)

## Performance

* [Customer Churn (GPU vs. CPU, sparse matrix vs. dense matrix, Pandas vs. cuDF)](https://github.com/lukassykora/action-rules/blob/main/notebooks/Performance.ipynb)
* [Scalene Profiling](https://github.com/lukassykora/action-rules/blob/main/notebooks/profiling/plot.ipynb)
* [GPU Memory Usage - Sparse vs. Dense Matrix](https://github.com/lukassykora/action-rules/blob/main/notebooks/gpu_sparse_vs_dense/process_logs.ipynb)
* [CPU Usage](https://github.com/lukassykora/action-rules/blob/main/notebooks/cpu_cores/cpu_usage.ipynb)
* [Compare the Action-Rules package with ActionRulesDiscovery package](https://github.com/lukassykora/action-rules/blob/main/notebooks/Comparison.ipynb) - link to ActionRulesDiscovery package: <https://github.com/lukassykora/actionrules>

## Credits

This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and
the [waynerv/cookiecutter-pypackage](https://github.com/waynerv/cookiecutter-pypackage) project template.

