Metadata-Version: 2.4
Name: so4gp
Version: 0.9.7
Summary: A Python library for gradual pattern mining algorithms.
Author-email: Dickson Owuor <owuordickson@gmail.com>, Anne Laurent <laurent@lirmm.fr>
Maintainer-email: Dickson Owuor <owuordickson@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/owuordickson/gp-mining
Project-URL: Documentation, http://so4gp.readthedocs.io
Project-URL: Repository, https://github.com/owuordickson/gp-mining.git
Project-URL: Bug Tracker, https://github.com/owuordickson/gp-mining/issues
Project-URL: Changelog, https://github.com/owuordickson/gp-mining/blob/main/CHANGELOG.md
Keywords: gradual patterns,GRAANK,ant-colony-optimization,data-mining,swarm-intelligence
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy~=2.5.0
Requires-Dist: pandas~=3.0.3
Requires-Dist: tabulate~=0.10.0
Requires-Dist: scikit-fuzzy~=0.5.0
Requires-Dist: scikit-learn~=1.9.0
Requires-Dist: seaborn~=0.13.2
Requires-Dist: matplotlib~=3.11.0
Requires-Dist: python-dateutil~=2.9.0
Requires-Dist: mcp~=1.28.1
Dynamic: license-file


<div align="center">

<strong>Python implementation of Gradual Pattern (GP) mining algorithms</strong>

[![PyPI][pypi-badge]][pypi-url]
[![Licence][licence-badge]][licence-url]
[![Python Version][python-badge]][python-url]
[![Documentation][docs-badge]][docs-url]

</div>

<div align="center">

[![Downloads][downloads-badge]][downloads-url] 
[![Downloads][weekly-downloads-badge]][weekly-downloads-url] 
![Dependents][dependents-badge]
[![DOI][doi-badge]][doi-url]

</div>

**SO4GP** is a high-performance Python library designed to optimize the extraction of gradual patterns from large-scale 
datasets. By integrating advanced computation techniques and data management strategies, the library significantly 
reduces processing time and memory overhead during knowledge discovery. 

## Implemented Extraction Algorithms
The library provides native Python implementations for the core and meta-heuristic gradual pattern mining algorithms. Here are some examples:

* **GRAANK**: The foundational classical approach for mining gradual patterns.
* **Ant Colony Optimization (AntGRAANK)**: Meta-heuristic ACO algorithm for search-space pruning GP candidates.
* **Genetic Algorithm (GeneticGRAANK)**: Meta-heuristic GA for search-space pruning GP candidates.
* **Particle Swarm Optimization (ParticleGRAANK)**: Meta-heuristic PSO algorithm for search-space pruning GP candidates.
* **Random Search (HillClimbingGRAANK)**: Baseline stochastic search variant for pruning GP candidates.
* **Clustering-based Mining (ClusterGP)**: Applies K-Means clustering approximation to mine GPs.
* **TGRAANK**: extends GRAANK to mine GPs with temporal lags.

### What are Gradual Patterns?
A **Gradual Pattern (GP)** is a co-occurring set of **gradual items (GI)** that captures covariations between attributes. 
A pattern's quality is measured quantitatively by its computed **support value**.

#### Example
Consider a dataset containing 10 objects with 3 attributes: `age`, `salary`, and `cars`. An extracted GP might look like:

$$\{\text{age}^+, \text{salary}^-\} \quad [\text{Support} = 0.8]$$

This output explicitly reveals that in **80% of the dataset** (8 out of 10 objects), an increase in `age` ($^+$) strongly 
correlates with a simultaneous decrease in `salary` ($^-$).


## Installation

```shell
pip install so4gp
```

## Usage
To use any algorithm to mine GPs, follow the instructions that follow.

First and foremost, import the **so4gp** python package via:

```python
import so4gp as sgp
# OR 
from so4gp.algorithms import GRAANK, TGRAANK, ClusterGP
```

### GRAdual rANKing Algorithm for GPs (GRAANK)

This is the classical approach (initially proposed by Anne Laurent) for mining gradual patterns. All the remaining algorithms 
are variants of this algorithm.

```python
import pandas as pd
from so4gp.algorithms import GRAANK

df = pd.DataFrame(
    [
        [30, 3, 1, 10],
        [35, 2, 2, 8],
        [40, 4, 2, 7],
        [50, 1, 1, 6],
        [52, 7, 1, 2],
    ],
    columns=["Age", "Salary", "Cars", "Expenses"],
)

miner_gp = GRAANK(
    data_source=df,
    min_sup=0.5,
)

results = miner_gp.discover()

print(results)

```

where you specify the parameters as follows:

* **data_source** - *[required]* data source {either a ```file in csv format``` or a ```Pandas DataFrame```}
* **min_sup** - *[optional]* minimum support ```default = 0.5```
* **eq** - *[optional]* encode equal values as gradual ```default = False```


### Sample Output
The default output is the format of JSON:

```json
{
	"Algorithm": "GRAANK",
	"Patterns": [
            [["Age+", "Salary+"], 0.6], 
            [["Expenses-", "Age+", "Salary+"], 0.6]
	]
}
```

## Contributors ✨

Thanks go to these incredible people:

<a href="https://github.com/owuordickson/gp-mining/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=owuordickson/gp-mining" />
</a>

Made with [contrib.rocks](https://contrib.rocks).

## References
* Owuor, D., Runkler T., Laurent A., Menya E., Orero J (2021), Ant Colony Optimization for Mining Gradual Patterns. International Journal of Machine Learning and Cybernetics. https://doi.org/10.1007/s13042-021-01390-w
* Dickson Owuor, Anne Laurent, and Joseph Orero (2019). Mining Fuzzy-temporal Gradual Patterns. In the proceedings of the 2019 IEEE International Conference on Fuzzy Systems (FuzzIEEE). IEEE. https://doi.org/10.1109/FUZZ-IEEE.2019.8858883.
* Laurent A., Lesot MJ., Rifqi M. (2009) GRAANK: Exploiting Rank Correlations for Extracting Gradual Itemsets. In: Andreasen T., Yager R.R., Bulskov H., Christiansen H., Larsen H.L. (eds) Flexible Query Answering Systems. FQAS 2009. Lecture Notes in Computer Science, vol 5822. Springer, Berlin, Heidelberg. https://doi.org/10.1007/978-3-642-04957-6_33


**See Docs for more details**

[pypi-badge]: https://img.shields.io/pypi/v/so4gp.svg
[pypi-url]: https://pypi.org/project/so4gp/
[licence-badge]: https://img.shields.io/pypi/l/so4gp.svg
[licence-url]: https://github.com/owuordickson/gp-mining/blob/main/LICENSE
[python-badge]: https://img.shields.io/pypi/pyversions/so4gp.svg
[python-url]: https://www.python.org/downloads/
[docs-badge]: https://img.shields.io/badge/docs-so4gp-blue.svg
[docs-url]: http://so4gp.readthedocs.io

[downloads-badge]: https://pepy.tech/badge/so4gp
[downloads-url]: https://pepy.tech/project/so4gp
[weekly-downloads-badge]: https://pepy.tech/badge/so4gp/week
[weekly-downloads-url]: https://pepy.tech/project/so4gp
[dependents-badge]: https://badgen.net/github/dependents-repo/owuordickson/gp-mining/?icon=github
[dependents-url]: https://github.com/owuordickson/gp-mining/network/dependents
[doi-badge]: https://zenodo.org/badge/388183952.svg
[doi-url]: https://doi.org/10.5281/zenodo.16281808

