gsppy 4.1.0__tar.gz → 5.0.0__tar.gz

{gsppy-4.1.0 → gsppy-5.0.0}/CHANGELOG.md

@@ -1,6 +1,37 @@
 # CHANGELOG
 
 
+## v5.0.0 (2026-02-06)
+
+### Chores
+
+- Adds support for optional types in item filters and ignores types in metadata printouts.
+  ([`79111b4`](https://github.com/jacksonpradolima/gsp-py/commit/79111b4c781a65b21a17f85b0b507b41ba6e51f9))
+
+- Update uv.lock for version 4.2.0
+  ([`f8f690f`](https://github.com/jacksonpradolima/gsp-py/commit/f8f690f7f0304dc4331c17c68487fe3411436149))
+
+### Features
+
+- Add preprocessing, postprocessing, and candidate filtering hooks to GSP algorithm
+  ([`495d290`](https://github.com/jacksonpradolima/gsp-py/commit/495d29009abe862bf992831bd276181efa40c99d))
+
+feat!: add preprocessing, postprocessing, and candidate filtering hooks to GSP algorithm
+
+
+## v4.2.0 (2026-02-01)
+
+### Chores
+
+- Update uv.lock for version 4.1.0
+  ([`5ed3d9e`](https://github.com/jacksonpradolima/gsp-py/commit/5ed3d9e46cf158a2261462cb8974b6bbb452f32e))
+
+### Features
+
+- Add itemset support for co-occurrence semantics in sequence mining
+  ([`90805b1`](https://github.com/jacksonpradolima/gsp-py/commit/90805b190f40ebf34a72da0bbe949cb627140337))
+
+
 ## v4.1.0 (2026-02-01)
 
 ### Bug Fixes

{gsppy-4.1.0 → gsppy-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gsppy
-Version: 4.1.0
+Version: 5.0.0
 Summary: GSP (Generalized Sequence Pattern) algorithm in Python
 Project-URL: Homepage, https://github.com/jacksonpradolima/gsp-py
 Author-email: Jackson Antonio do Prado Lima <jacksonpradolima@gmail.com>
@@ -112,6 +112,7 @@ Sequence Pattern (GSP)** algorithm. Ideal for market basket analysis, temporal m
     - [✅ Example: Analyzing Sales Data](#example-analyzing-sales-data)
     - [📊 Explanation: Support and Results](#explanation-support-and-results)
     - [📊 DataFrame Input Support](#dataframe-input-support)
+    - [🔗 Itemset Support](#itemset-support)
     - [⏱️ Temporal Constraints](#temporal-constraints)
 7. [⌨️ Typing](#typing)
 8. [🌟 Planned Features](#planned-features)
@@ -980,6 +981,150 @@ For complete examples and edge cases, see:
 
 ---
 
+## 🔗 Itemset Support
+
+GSP-Py supports **itemsets** within sequence elements, enabling you to capture **co-occurrence** of multiple items at the same time step. This is crucial for applications where items occur together rather than in strict sequential order.
+
+### What are Itemsets?
+
+- **Flat sequences**: `['A', 'B', 'C']` - each item occurs at a separate time step
+- **Itemset sequences**: `[['A', 'B'], ['C']]` - items A and B occur together at the first time step, then C occurs later
+
+### Why Use Itemsets?
+
+Itemsets are essential when temporal co-occurrence matters in your domain:
+
+- **Market basket analysis**: Customers buy multiple items in a single shopping trip, then return for more items later
+- **Web analytics**: Users open multiple pages in parallel tabs before moving to the next set of pages
+- **Event logs**: Multiple events can occur simultaneously in complex systems
+- **Purchase patterns**: Items bought together vs. items bought in sequence
+
+### Using Itemsets
+
+#### Basic Example
+
+```python
+from gsppy import GSP
+
+# Itemset format: nested lists where inner lists are items that occur together
+transactions = [
+    [['Bread', 'Milk'], ['Eggs']],  # Bought Bread & Milk together, then Eggs later
+    [['Bread', 'Milk', 'Butter']],  # Bought all three items together
+    [['Bread', 'Milk'], ['Eggs']],  # Same pattern as customer 1
+]
+
+gsp = GSP(transactions)
+patterns = gsp.search(min_support=0.5)
+
+# Pattern ('Bread',) will match any itemset containing Bread
+# Pattern ('Bread', 'Eggs') will match sequences where Bread appears before Eggs
+# (even if they're in different itemsets)
+```
+
+#### Backward Compatibility with Flat Sequences
+
+GSP-Py automatically normalizes flat sequences to itemsets internally, ensuring full backward compatibility:
+
+```python
+from gsppy import GSP
+
+# These are equivalent after normalization:
+flat_transactions = [['A', 'B', 'C']]  # Flat format
+itemset_transactions = [[['A'], ['B'], ['C']]]  # Equivalent itemset format
+
+# Both produce the same results
+gsp1 = GSP(flat_transactions)
+gsp2 = GSP(itemset_transactions)
+
+# Patterns are identical
+patterns1 = gsp1.search(min_support=0.5)
+patterns2 = gsp2.search(min_support=0.5)
+```
+
+### Itemset Matching Semantics
+
+Pattern matching with itemsets uses **subset semantics**:
+
+- A pattern element matches a sequence element if all items in the pattern element are present in the sequence element
+- Example: Pattern `[['A', 'B']]` matches sequence element `['A', 'B', 'C']` because {A, B} ⊆ {A, B, C}
+- Pattern elements must appear in order across the sequence
+
+```python
+from gsppy import GSP
+
+transactions = [
+    [['A', 'B', 'D'], ['E'], ['C', 'F']],  # A,B,D together, then E, then C,F together
+]
+
+gsp = GSP(transactions)
+
+# Pattern ('A', 'C') will match because:
+# - 'A' is in first itemset ['A', 'B', 'D'] ✓
+# - 'C' appears later in third itemset ['C', 'F'] ✓
+# - Order is preserved ✓
+```
+
+### Reading Itemsets from SPM Format
+
+The SPM/GSP format supports itemsets using delimiters:
+
+- `-1`: End of itemset
+- `-2`: End of sequence
+
+```python
+from gsppy.utils import read_transactions_from_spm
+
+# SPM file content:
+# 1 2 -1 3 -1 -2
+# 1 -1 3 4 -1 -2
+
+# Read with itemsets preserved
+transactions = read_transactions_from_spm("data.txt", preserve_itemsets=True)
+# Result: [[['1', '2'], ['3']], [['1'], ['3', '4']]]
+
+# Read with itemsets flattened (backward compatible)
+transactions = read_transactions_from_spm("data.txt", preserve_itemsets=False)
+# Result: [['1', '2', '3'], ['1', '3', '4']]
+```
+
+### Itemsets with Timestamps
+
+Itemsets work seamlessly with temporal constraints:
+
+```python
+from gsppy import GSP
+
+# Itemsets with timestamps: [(item, timestamp), ...]
+transactions = [
+    [[('Login', 0), ('Home', 0)], [('Product', 5)], [('Checkout', 10)]],
+    [[('Login', 0)], [('Home', 2), ('Product', 2)], [('Checkout', 15)]],
+]
+
+# Find patterns where events in the same itemset occur together
+# and subsequent itemsets occur within maxgap time units
+gsp = GSP(transactions, maxgap=10)
+patterns = gsp.search(min_support=0.5)
+```
+
+### Complete Example
+
+See [examples/itemset_example.py](examples/itemset_example.py) for comprehensive examples including:
+
+- Market basket analysis with itemsets
+- Web clickstream with parallel page views
+- Comparison of flat vs. itemset semantics
+- Reading and processing SPM format files
+
+### Key Takeaways
+
+✓ **Itemsets capture co-occurrence** of items at the same time step  
+✓ **Flat sequences are automatically normalized** to itemsets internally  
+✓ **Both formats work seamlessly** with GSP-Py  
+✓ **Use itemsets when temporal co-occurrence matters** in your domain  
+✓ **SPM format supports** both flat and itemset representations
+
+---
+
 ## ⏱️ Temporal Constraints
 
 GSP-Py supports **time-constrained sequential pattern mining** with three powerful temporal constraints: `mingap`, `maxgap`, and `maxspan`. These constraints enable domain-specific applications such as medical event mining, retail analytics, and temporal user journey discovery.

{gsppy-4.1.0 → gsppy-5.0.0}/README.md

@@ -39,6 +39,7 @@ Sequence Pattern (GSP)** algorithm. Ideal for market basket analysis, temporal m
     - [✅ Example: Analyzing Sales Data](#example-analyzing-sales-data)
     - [📊 Explanation: Support and Results](#explanation-support-and-results)
     - [📊 DataFrame Input Support](#dataframe-input-support)
+    - [🔗 Itemset Support](#itemset-support)
     - [⏱️ Temporal Constraints](#temporal-constraints)
 7. [⌨️ Typing](#typing)
 8. [🌟 Planned Features](#planned-features)
@@ -907,6 +908,150 @@ For complete examples and edge cases, see:
 
 ---
 
+## 🔗 Itemset Support
+
+GSP-Py supports **itemsets** within sequence elements, enabling you to capture **co-occurrence** of multiple items at the same time step. This is crucial for applications where items occur together rather than in strict sequential order.
+
+### What are Itemsets?
+
+- **Flat sequences**: `['A', 'B', 'C']` - each item occurs at a separate time step
+- **Itemset sequences**: `[['A', 'B'], ['C']]` - items A and B occur together at the first time step, then C occurs later
+
+### Why Use Itemsets?
+
+Itemsets are essential when temporal co-occurrence matters in your domain:
+
+- **Market basket analysis**: Customers buy multiple items in a single shopping trip, then return for more items later
+- **Web analytics**: Users open multiple pages in parallel tabs before moving to the next set of pages
+- **Event logs**: Multiple events can occur simultaneously in complex systems
+- **Purchase patterns**: Items bought together vs. items bought in sequence
+
+### Using Itemsets
+
+#### Basic Example
+
+```python
+from gsppy import GSP
+
+# Itemset format: nested lists where inner lists are items that occur together
+transactions = [
+    [['Bread', 'Milk'], ['Eggs']],  # Bought Bread & Milk together, then Eggs later
+    [['Bread', 'Milk', 'Butter']],  # Bought all three items together
+    [['Bread', 'Milk'], ['Eggs']],  # Same pattern as customer 1
+]
+
+gsp = GSP(transactions)
+patterns = gsp.search(min_support=0.5)
+
+# Pattern ('Bread',) will match any itemset containing Bread
+# Pattern ('Bread', 'Eggs') will match sequences where Bread appears before Eggs
+# (even if they're in different itemsets)
+```
+
+#### Backward Compatibility with Flat Sequences
+
+GSP-Py automatically normalizes flat sequences to itemsets internally, ensuring full backward compatibility:
+
+```python
+from gsppy import GSP
+
+# These are equivalent after normalization:
+flat_transactions = [['A', 'B', 'C']]  # Flat format
+itemset_transactions = [[['A'], ['B'], ['C']]]  # Equivalent itemset format
+
+# Both produce the same results
+gsp1 = GSP(flat_transactions)
+gsp2 = GSP(itemset_transactions)
+
+# Patterns are identical
+patterns1 = gsp1.search(min_support=0.5)
+patterns2 = gsp2.search(min_support=0.5)
+```
+
+### Itemset Matching Semantics
+
+Pattern matching with itemsets uses **subset semantics**:
+
+- A pattern element matches a sequence element if all items in the pattern element are present in the sequence element
+- Example: Pattern `[['A', 'B']]` matches sequence element `['A', 'B', 'C']` because {A, B} ⊆ {A, B, C}
+- Pattern elements must appear in order across the sequence
+
+```python
+from gsppy import GSP
+
+transactions = [
+    [['A', 'B', 'D'], ['E'], ['C', 'F']],  # A,B,D together, then E, then C,F together
+]
+
+gsp = GSP(transactions)
+
+# Pattern ('A', 'C') will match because:
+# - 'A' is in first itemset ['A', 'B', 'D'] ✓
+# - 'C' appears later in third itemset ['C', 'F'] ✓
+# - Order is preserved ✓
+```
+
+### Reading Itemsets from SPM Format
+
+The SPM/GSP format supports itemsets using delimiters:
+
+- `-1`: End of itemset
+- `-2`: End of sequence
+
+```python
+from gsppy.utils import read_transactions_from_spm
+
+# SPM file content:
+# 1 2 -1 3 -1 -2
+# 1 -1 3 4 -1 -2
+
+# Read with itemsets preserved
+transactions = read_transactions_from_spm("data.txt", preserve_itemsets=True)
+# Result: [[['1', '2'], ['3']], [['1'], ['3', '4']]]
+
+# Read with itemsets flattened (backward compatible)
+transactions = read_transactions_from_spm("data.txt", preserve_itemsets=False)
+# Result: [['1', '2', '3'], ['1', '3', '4']]
+```
+
+### Itemsets with Timestamps
+
+Itemsets work seamlessly with temporal constraints:
+
+```python
+from gsppy import GSP
+
+# Itemsets with timestamps: [(item, timestamp), ...]
+transactions = [
+    [[('Login', 0), ('Home', 0)], [('Product', 5)], [('Checkout', 10)]],
+    [[('Login', 0)], [('Home', 2), ('Product', 2)], [('Checkout', 15)]],
+]
+
+# Find patterns where events in the same itemset occur together
+# and subsequent itemsets occur within maxgap time units
+gsp = GSP(transactions, maxgap=10)
+patterns = gsp.search(min_support=0.5)
+```
+
+### Complete Example
+
+See [examples/itemset_example.py](examples/itemset_example.py) for comprehensive examples including:
+
+- Market basket analysis with itemsets
+- Web clickstream with parallel page views
+- Comparison of flat vs. itemset semantics
+- Reading and processing SPM format files
+
+### Key Takeaways
+
+✓ **Itemsets capture co-occurrence** of items at the same time step  
+✓ **Flat sequences are automatically normalized** to itemsets internally  
+✓ **Both formats work seamlessly** with GSP-Py  
+✓ **Use itemsets when temporal co-occurrence matters** in your domain  
+✓ **SPM format supports** both flat and itemset representations
+
+---
+
 ## ⏱️ Temporal Constraints
 
 GSP-Py supports **time-constrained sequential pattern mining** with three powerful temporal constraints: `mingap`, `maxgap`, and `maxspan`. These constraints enable domain-specific applications such as medical event mining, retail analytics, and temporal user journey discovery.

{gsppy-4.1.0 → gsppy-5.0.0}/gsppy/cli.py

@@ -35,7 +35,8 @@ import csv
 import sys
 import json
 import logging
-from typing import Any, List, Tuple, Union, Optional, cast
+import importlib
+from typing import Any, List, Tuple, Union, Callable, Optional, cast
 
 import click
 
@@ -51,6 +52,54 @@ from gsppy.enums import (
 from gsppy.utils import has_timestamps
 
 
+def _load_hook_function(import_path: str, hook_type: str) -> Callable[..., Any]:
+    """
+    Load a hook function from a Python module import path.
+
+    Parameters:
+        import_path (str): Import path in format 'module.submodule.function_name'
+        hook_type (str): Type of hook for error messages ('preprocess', 'postprocess', 'candidate_filter')
+
+    Returns:
+        Callable: The loaded hook function
+
+    Raises:
+        ValueError: If the import path is invalid or function cannot be loaded
+    """
+    try:
+        # Split into module path and function name
+        parts = import_path.rsplit(".", 1)
+        if len(parts) != 2:
+            raise ValueError(f"Invalid import path format. Expected 'module.function', got '{import_path}'")
+
+        module_name, function_name = parts
+
+        # Import the module
+        module = importlib.import_module(module_name)
+
+        # Get the function from the module
+        if not hasattr(module, function_name):
+            raise ValueError(f"Function '{function_name}' not found in module '{module_name}'")
+
+        hook_fn = getattr(module, function_name)
+
+        # Verify it's callable
+        if not callable(hook_fn):
+            raise ValueError(f"'{import_path}' is not a callable function")
+
+        return hook_fn
+
+    except ImportError as e:
+        # Extract module name from import path for error message
+        module_part = import_path.rsplit(".", 1)[0] if "." in import_path else import_path
+        raise ValueError(f"Failed to import {hook_type} hook module '{module_part}': {e}") from e
+    except ValueError:
+        # Re-raise ValueError as-is
+        raise
+    except Exception as e:
+        raise ValueError(f"Failed to load {hook_type} hook function '{import_path}': {e}") from e
+
+
 def setup_logging(verbose: bool) -> None:
     """
     Configure logging with standardized format based on verbosity level.
@@ -515,20 +564,26 @@ def _load_transactions_by_format(
     help="File format to use. 'auto' detects format from file extension.",
 )
 @click.option("--verbose", is_flag=True, help="Enable verbose output for debugging purposes.")
-def main(
-    file_path: str,
-    min_support: float,
-    backend: str,
-    mingap: Optional[float],
-    maxgap: Optional[float],
-    maxspan: Optional[float],
-    transaction_col: Optional[str],
-    item_col: Optional[str],
-    timestamp_col: Optional[str],
-    sequence_col: Optional[str],
-    format: str,  # noqa: A002
-    verbose: bool,
-) -> None:
+@click.option(
+    "--preprocess-hook",
+    type=str,
+    default=None,
+    help="Python import path to preprocessing hook function (e.g., 'mymodule.preprocess_fn').",
+)
+@click.option(
+    "--postprocess-hook",
+    type=str,
+    default=None,
+    help="Python import path to postprocessing hook function (e.g., 'mymodule.postprocess_fn').",
+)
+@click.option(
+    "--candidate-filter-hook",
+    type=str,
+    default=None,
+    help="Python import path to candidate filter hook function (e.g., 'mymodule.filter_fn').",
+)
+@click.pass_context
+def main(ctx: click.Context, **kwargs: Any) -> None:
     """
     Run the GSP algorithm on transactional data from a file.
 
@@ -573,9 +628,59 @@ def main(
         ```bash
         gsppy --file data.txt --format spm --min_support 0.3
         ```
+
+        With custom hooks (requires Python module with hook functions):
+
+        ```bash
+        # Create a hooks module first (hooks.py):
+        # def my_filter(candidate, support, context):
+        #     return len(candidate) <= 2  # Keep only short patterns
+        #
+        # def my_postprocess(patterns):
+        #     return patterns[:2]  # Keep only first 2 levels
+
+        gsppy --file data.json --min_support 0.3 \
+              --candidate-filter-hook hooks.my_filter \
+              --postprocess-hook hooks.my_postprocess
+        ```
     """
+    # Extract parameters from kwargs
+    file_path = kwargs['file_path']
+    min_support = kwargs['min_support']
+    backend = kwargs['backend']
+    mingap = kwargs.get('mingap')
+    maxgap = kwargs.get('maxgap')
+    maxspan = kwargs.get('maxspan')
+    transaction_col = kwargs.get('transaction_col')
+    item_col = kwargs.get('item_col')
+    timestamp_col = kwargs.get('timestamp_col')
+    sequence_col = kwargs.get('sequence_col')
+    file_format = kwargs['format']
+    verbose = kwargs['verbose']
+    preprocess_hook = kwargs.get('preprocess_hook')
+    postprocess_hook = kwargs.get('postprocess_hook')
+    candidate_filter_hook = kwargs.get('candidate_filter_hook')
+    
     setup_logging(verbose)
 
+    # Load hook functions if specified
+    try:
+        preprocess_fn = _load_hook_function(preprocess_hook, "preprocess") if preprocess_hook else None
+        postprocess_fn = _load_hook_function(postprocess_hook, "postprocess") if postprocess_hook else None
+        candidate_filter_fn = (
+            _load_hook_function(candidate_filter_hook, "candidate_filter") if candidate_filter_hook else None
+        )
+
+        if preprocess_fn:
+            logger.info(f"Loaded preprocessing hook: {preprocess_hook}")
+        if postprocess_fn:
+            logger.info(f"Loaded postprocessing hook: {postprocess_hook}")
+        if candidate_filter_fn:
+            logger.info(f"Loaded candidate filter hook: {candidate_filter_hook}")
+    except ValueError as e:
+        logger.error(f"Error loading hook function: {e}")
+        sys.exit(1)
+
     # Detect file extension to determine if DataFrame column params are needed
     _, file_extension = os.path.splitext(file_path)
     file_extension = file_extension.lower()
@@ -583,10 +688,10 @@ def main(
 
     # Automatically detect and load transactions
     try:
-        file_format = format.lower()
+        file_format_lower = file_format.lower()
         transactions = _load_transactions_by_format(
             file_path,
-            file_format,
+            file_format_lower,
             file_extension,
             is_dataframe_format,
             transaction_col,
@@ -608,7 +713,13 @@ def main(
     # Initialize and run GSP algorithm
     try:
         gsp = GSP(transactions, mingap=mingap, maxgap=maxgap, maxspan=maxspan, verbose=verbose)
-        patterns = gsp.search(min_support=min_support, return_sequences=False)
+        patterns = gsp.search(
+            min_support=min_support,
+            return_sequences=False,
+            preprocess_fn=preprocess_fn,
+            postprocess_fn=postprocess_fn,
+            candidate_filter_fn=candidate_filter_fn,
+        )
         logger.info("Frequent Patterns Found:")
         for i, level in enumerate(patterns, start=1):
             logger.info(f"\n{i}-Sequence Patterns:")