gsppy 2.3.0

GSP (Generalized Sequence Pattern) algorithm in Python

GSP-Py

GSP-Py: A Python-powered library to mine sequential patterns in large datasets, based on the robust Generalized Sequence Pattern (GSP) algorithm. Ideal for market basket analysis, temporal mining, and user journey discovery.

[!IMPORTANT] GSP-Py is compatible with Python 3.8 and later versions!

---

📚 Table of Contents

1. 🔍 What is GSP?
2. 🔧 Requirements
3. 🚀 Installation
   • ❖ Clone Repository
   • ❖ Install via PyPI
4. 🛠️ Developer Installation
5. 💡 Usage
   • ✅ Example: Analyzing Sales Data
   • 📊 Explanation: Support and Results
6. 🌟 Planned Features
7. 🤝 Contributing
8. 📝 License
9. 📖 Citation

---

🔍 What is GSP?

The Generalized Sequential Pattern (GSP) algorithm is a sequential pattern mining technique based on Apriori principles. Using support thresholds, GSP identifies frequent sequences of items in transaction datasets.

Key Features:

• Support-based pruning: Only retains sequences that meet the minimum support threshold.
• Candidate generation: Iteratively generates candidate sequences of increasing length.
• General-purpose: Useful in retail, web analytics, social networks, temporal sequence mining, and more.

For example:

• In a shopping dataset, GSP can identify patterns like "Customers who buy bread and milk often purchase diapers next."
• In a website clickstream, GSP might find patterns like "Users visit A, then go to B, and later proceed to C."

---

🔧 Requirements

You will need Python installed on your system. On most Linux systems, you can install Python with:

sudo apt install python3

For package dependencies of GSP-Py, they will automatically be installed when using pip.

---

🚀 Installation

GSP-Py can be easily installed from either the repository or PyPI.

Option 1: Clone the Repository

To manually clone the repository and set up the environment:

git clone https://github.com/jacksonpradolima/gsp-py.git
cd gsp-py

Refer to the Developer Installation section and run:

rye sync

Option 2: Install via pip

Alternatively, install GSP-Py from PyPI with:

pip install gsppy

---

🛠️ Developer Installation

This project uses Rye for managing dependencies, running scripts, and setting up the environment. Follow these steps to install and set up Rye for this project:

1. Install Rye

Run the following command to install Rye:

curl -sSf https://rye.astral.sh/get | bash

If the ~/.rye/bin directory is not in your PATH, add the following line to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, etc.):

export PATH="$HOME/.rye/bin:$PATH"

Reload your shell configuration file:

source ~/.bashrc  # or `source ~/.zshrc`

2. Set Up the Project Environment

To configure the project environment and install its dependencies, run:

rye sync

3. Use Rye Scripts

Once the environment is set up, you can run the following commands to simplify project tasks:

• Run tests (in parallel): rye run test
• Format code: rye run format
• Lint code: rye run lint
• Type-check: rye run typecheck
• Add new dependencies: rye add <package-name>
  • Add new dependency to dev dependencies: rye add --dev <package-name>

Notes

• Rye automatically reads dependencies and scripts from the pyproject.toml file.
• No need for requirements.txt, as Rye manages all dependencies!

💡 Usage

The library is designed to be easy to use and integrate with your own projects. Below is an example of how you can configure and run GSP-Py.

Example Input Data

The input to the algorithm is a sequence of transactions, where each transaction contains a sequence of items:

transactions = [
    ['Bread', 'Milk'],
    ['Bread', 'Diaper', 'Beer', 'Eggs'],
    ['Milk', 'Diaper', 'Beer', 'Coke'],
    ['Bread', 'Milk', 'Diaper', 'Beer'],
    ['Bread', 'Milk', 'Diaper', 'Coke']
]

Importing and Initializing the GSP Algorithm

Import the GSP class from the gsppy package and call the search method to find frequent patterns with a support threshold (e.g., 0.3):

from gsppy.gsp import GSP

# Example transactions: customer purchases
transactions = [
    ['Bread', 'Milk'],  # Transaction 1
    ['Bread', 'Diaper', 'Beer', 'Eggs'],  # Transaction 2
    ['Milk', 'Diaper', 'Beer', 'Coke'],  # Transaction 3
    ['Bread', 'Milk', 'Diaper', 'Beer'],  # Transaction 4
    ['Bread', 'Milk', 'Diaper', 'Coke']  # Transaction 5
]

# Set minimum support threshold (30%)
min_support = 0.3

# Find frequent patterns
result = GSP(transactions).search(min_support)

# Output the results
print(result)

Output

The algorithm will return a list of patterns with their corresponding support.

Sample Output:

[
    {('Bread',): 4, ('Milk',): 4, ('Diaper',): 4, ('Beer',): 3, ('Coke',): 2},
    {('Bread', 'Milk'): 3, ('Milk', 'Diaper'): 3, ('Diaper', 'Beer'): 3},
    {('Bread', 'Milk', 'Diaper'): 2, ('Milk', 'Diaper', 'Beer'): 2}
]

• The first dictionary contains single-item sequences with their frequencies (e.g., ('Bread',): 4 means "Bread" appears in 4 transactions).
• The second dictionary contains 2-item sequential patterns (e.g., ('Bread', 'Milk'): 3 means the sequence " Bread → Milk" appears in 3 transactions).
• The third dictionary contains 3-item sequential patterns (e.g., ('Bread', 'Milk', 'Diaper'): 2 means the sequence "Bread → Milk → Diaper" appears in 2 transactions).

[!NOTE] The support of a sequence is calculated as the fraction of transactions containing the sequence, e.g., [Bread, Milk] appears in 3 out of 5 transactions → Support = 3 / 5 = 0.6 (60%). This insight helps identify frequently occurring sequential patterns in datasets, such as shopping trends or user behavior.

[!TIP] For more complex examples, find example scripts in the gsppy/tests folder.

---

🌟 Planned Features

We are actively working to improve GSP-Py. Here are some exciting features planned for future releases:

1. Custom Filters for Candidate Pruning:

   • Enable users to define their own pruning logic during the mining process.

2. Support for Preprocessing and Postprocessing:

   • Add hooks to allow users to transform datasets before mining and customize the output results.

3. Support for Time-Constrained Pattern Mining:

   • Extend GSP-Py to handle temporal datasets by allowing users to define time constraints (e.g., maximum time gaps between events, time windows) during the sequence mining process.
   • Enable candidate pruning and support calculations based on these temporal constraints.

Want to contribute or suggest an improvement? Open a discussion or issue!

---

🤝 Contributing

We welcome contributions from the community! If you'd like to help improve GSP-Py, read our CONTRIBUTING.md guide to get started.

Development dependencies (e.g., testing and linting tools) are automatically managed using Rye. To install these dependencies and set up the environment, run:

rye sync

After syncing, you can run the following scripts using Rye for development tasks:

• Run tests (in parallel): rye run test
• Lint code: rye run lint
• Type-check: rye run typecheck
• Format code: rye run format

General Steps:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/my-feature.
3. Commit your changes: git commit -m "Add my feature."
4. Push to your branch: git push origin feature/my-feature.
5. Submit a pull request to the main repository!

Looking for ideas? Check out our Planned Features section.

---

📝 License

This project is licensed under the terms of the MIT License. For more details, refer to the LICENSE file.

---

📖 Citation

If GSP-Py contributed to your research or project that led to a publication, we kindly ask that you cite it as follows:

@misc{pradolima_gsppy,
  author       = {Prado Lima, Jackson Antonio do},
  title        = {{GSP-Py - Generalized Sequence Pattern algorithm in Python}},
  month        = Dec,
  year         = 2025,
  doi          = {10.5281/zenodo.3333987},
  url          = {https://doi.org/10.5281/zenodo.3333987}
}