gsppy 3.5.0__tar.gz → 3.6.0__tar.gz

{gsppy-3.5.0 → gsppy-3.6.0}/CHANGELOG.md

@@ -1,6 +1,29 @@
 # CHANGELOG
 
 
+## v3.6.0 (2026-01-26)
+
+### Chores
+
+- Update uv.lock for version 3.5.0
+  ([`e2c1be0`](https://github.com/jacksonpradolima/gsp-py/commit/e2c1be0945b0b124d8afa8981877513449b29ff0))
+
+### Features
+
+- Add flexible pruning strategy system to GSP algorithm
+  ([`94089cc`](https://github.com/jacksonpradolima/gsp-py/commit/94089cc5716ec6d7c7a6e0720843162db116fca2))
+
+feat: add flexible pruning strategy system to GSP algorithm
+
+- Add typing-extensions as a dependency
+  ([`6222945`](https://github.com/jacksonpradolima/gsp-py/commit/62229455ef3976c405d96e5ea9d5cafaf5eee6e3))
+
+### Refactoring
+
+- Pruning strategy initialization and enhance type hints; add typing_extensions dependency
+  ([`ddc0abd`](https://github.com/jacksonpradolima/gsp-py/commit/ddc0abd9352797dd19988f60d6287da421ef60cf))
+
+
 ## v3.5.0 (2026-01-26)
 
 ### Bug Fixes

{gsppy-3.5.0 → gsppy-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gsppy
-Version: 3.5.0
+Version: 3.6.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>
@@ -40,6 +40,7 @@ Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0.0
+Requires-Dist: typing-extensions>=4.0.0
 Provides-Extra: dev
 Requires-Dist: cython==3.2.4; extra == 'dev'
 Requires-Dist: hatch==1.16.3; extra == 'dev'
@@ -705,6 +706,140 @@ result = gsp.search(min_support=0.5)
 
 ---
 
+## 🔧 Flexible Candidate Pruning
+
+GSP-Py supports **flexible candidate pruning strategies** that allow you to customize how candidate sequences are filtered during pattern mining. This enables optimization for different dataset characteristics and mining requirements.
+
+### Built-in Pruning Strategies
+
+#### 1. Support-Based Pruning (Default)
+
+The standard GSP pruning based on minimum support threshold:
+
+```python
+from gsppy.gsp import GSP
+from gsppy.pruning import SupportBasedPruning
+
+# Explicit support-based pruning
+pruner = SupportBasedPruning(min_support_fraction=0.3)
+gsp = GSP(transactions, pruning_strategy=pruner)
+result = gsp.search(min_support=0.3)
+```
+
+#### 2. Frequency-Based Pruning
+
+Prunes candidates based on absolute frequency (minimum number of occurrences):
+
+```python
+from gsppy.pruning import FrequencyBasedPruning
+
+# Require patterns to appear at least 5 times
+pruner = FrequencyBasedPruning(min_frequency=5)
+gsp = GSP(transactions, pruning_strategy=pruner)
+result = gsp.search(min_support=0.2)
+```
+
+**Use case**: When you need patterns to occur a minimum absolute number of times, regardless of dataset size.
+
+#### 3. Temporal-Aware Pruning
+
+Optimizes pruning for time-constrained pattern mining by pre-filtering infeasible patterns:
+
+```python
+from gsppy.pruning import TemporalAwarePruning
+
+# Prune patterns that cannot satisfy temporal constraints
+pruner = TemporalAwarePruning(
+    mingap=1,
+    maxgap=5,
+    maxspan=10,
+    min_support_fraction=0.3
+)
+gsp = GSP(timestamped_transactions, mingap=1, maxgap=5, maxspan=10, pruning_strategy=pruner)
+result = gsp.search(min_support=0.3)
+```
+
+**Use case**: Improves performance for temporal pattern mining by eliminating patterns that cannot satisfy temporal constraints.
+
+#### 4. Combined Pruning
+
+Combines multiple pruning strategies for aggressive filtering:
+
+```python
+from gsppy.pruning import CombinedPruning, SupportBasedPruning, FrequencyBasedPruning
+
+# Apply both support and frequency constraints
+strategies = [
+    SupportBasedPruning(min_support_fraction=0.3),
+    FrequencyBasedPruning(min_frequency=5)
+]
+pruner = CombinedPruning(strategies)
+gsp = GSP(transactions, pruning_strategy=pruner)
+result = gsp.search(min_support=0.3)
+```
+
+**Use case**: When you want to combine multiple filtering criteria for more selective pattern discovery.
+
+### Custom Pruning Strategies
+
+You can create custom pruning strategies by implementing the `PruningStrategy` interface:
+
+```python
+from gsppy.pruning import PruningStrategy
+from typing import Dict, Optional, Tuple
+
+class MyCustomPruner(PruningStrategy):
+    def should_prune(
+        self,
+        candidate: Tuple[str, ...],
+        support_count: int,
+        total_transactions: int,
+        context: Optional[Dict] = None
+    ) -> bool:
+        # Custom pruning logic
+        # Return True to prune (filter out), False to keep
+        pattern_length = len(candidate)
+        # Example: Prune very long patterns with low support
+        if pattern_length > 5 and support_count < 10:
+            return True
+        return False
+
+# Use your custom pruner
+custom_pruner = MyCustomPruner()
+gsp = GSP(transactions, pruning_strategy=custom_pruner)
+result = gsp.search(min_support=0.2)
+```
+
+### Performance Characteristics
+
+Different pruning strategies have different performance tradeoffs:
+
+| Strategy | Pruning Aggressiveness | Use Case | Performance Impact |
+|----------|----------------------|----------|-------------------|
+| **SupportBased** | Moderate | General-purpose mining | Baseline performance |
+| **FrequencyBased** | High (for large datasets) | Require absolute frequency | Faster on large datasets |
+| **TemporalAware** | High (for temporal data) | Time-constrained patterns | Significant speedup for temporal mining |
+| **Combined** | Very High | Selective pattern discovery | Fastest, but may miss edge cases |
+
+### Benchmarking Pruning Strategies
+
+To compare pruning strategies on your dataset:
+
+```bash
+# Compare all strategies
+python benchmarks/bench_pruning.py --n_tx 1000 --vocab 100 --min_support 0.2 --strategy all
+
+# Benchmark a specific strategy
+python benchmarks/bench_pruning.py --n_tx 1000 --vocab 100 --min_support 0.2 --strategy frequency
+
+# Run multiple rounds for averaging
+python benchmarks/bench_pruning.py --n_tx 1000 --vocab 100 --min_support 0.2 --strategy all --rounds 3
+```
+
+See `benchmarks/bench_pruning.py` for the complete benchmarking script.
+
+---
+
 ## ⌨️ Typing
 
 `gsppy` ships inline type information (PEP 561) via a bundled `py.typed` marker. The public API is re-exported from
@@ -718,10 +853,7 @@ larger applications.
 
 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**:
+1. **Support for Preprocessing and Postprocessing**:
     - Add hooks to allow users to transform datasets before mining and customize the output results.
 
 Want to contribute or suggest an

{gsppy-3.5.0 → gsppy-3.6.0}/README.md

@@ -638,6 +638,140 @@ result = gsp.search(min_support=0.5)
 
 ---
 
+## 🔧 Flexible Candidate Pruning
+
+GSP-Py supports **flexible candidate pruning strategies** that allow you to customize how candidate sequences are filtered during pattern mining. This enables optimization for different dataset characteristics and mining requirements.
+
+### Built-in Pruning Strategies
+
+#### 1. Support-Based Pruning (Default)
+
+The standard GSP pruning based on minimum support threshold:
+
+```python
+from gsppy.gsp import GSP
+from gsppy.pruning import SupportBasedPruning
+
+# Explicit support-based pruning
+pruner = SupportBasedPruning(min_support_fraction=0.3)
+gsp = GSP(transactions, pruning_strategy=pruner)
+result = gsp.search(min_support=0.3)
+```
+
+#### 2. Frequency-Based Pruning
+
+Prunes candidates based on absolute frequency (minimum number of occurrences):
+
+```python
+from gsppy.pruning import FrequencyBasedPruning
+
+# Require patterns to appear at least 5 times
+pruner = FrequencyBasedPruning(min_frequency=5)
+gsp = GSP(transactions, pruning_strategy=pruner)
+result = gsp.search(min_support=0.2)
+```
+
+**Use case**: When you need patterns to occur a minimum absolute number of times, regardless of dataset size.
+
+#### 3. Temporal-Aware Pruning
+
+Optimizes pruning for time-constrained pattern mining by pre-filtering infeasible patterns:
+
+```python
+from gsppy.pruning import TemporalAwarePruning
+
+# Prune patterns that cannot satisfy temporal constraints
+pruner = TemporalAwarePruning(
+    mingap=1,
+    maxgap=5,
+    maxspan=10,
+    min_support_fraction=0.3
+)
+gsp = GSP(timestamped_transactions, mingap=1, maxgap=5, maxspan=10, pruning_strategy=pruner)
+result = gsp.search(min_support=0.3)
+```
+
+**Use case**: Improves performance for temporal pattern mining by eliminating patterns that cannot satisfy temporal constraints.
+
+#### 4. Combined Pruning
+
+Combines multiple pruning strategies for aggressive filtering:
+
+```python
+from gsppy.pruning import CombinedPruning, SupportBasedPruning, FrequencyBasedPruning
+
+# Apply both support and frequency constraints
+strategies = [
+    SupportBasedPruning(min_support_fraction=0.3),
+    FrequencyBasedPruning(min_frequency=5)
+]
+pruner = CombinedPruning(strategies)
+gsp = GSP(transactions, pruning_strategy=pruner)
+result = gsp.search(min_support=0.3)
+```
+
+**Use case**: When you want to combine multiple filtering criteria for more selective pattern discovery.
+
+### Custom Pruning Strategies
+
+You can create custom pruning strategies by implementing the `PruningStrategy` interface:
+
+```python
+from gsppy.pruning import PruningStrategy
+from typing import Dict, Optional, Tuple
+
+class MyCustomPruner(PruningStrategy):
+    def should_prune(
+        self,
+        candidate: Tuple[str, ...],
+        support_count: int,
+        total_transactions: int,
+        context: Optional[Dict] = None
+    ) -> bool:
+        # Custom pruning logic
+        # Return True to prune (filter out), False to keep
+        pattern_length = len(candidate)
+        # Example: Prune very long patterns with low support
+        if pattern_length > 5 and support_count < 10:
+            return True
+        return False
+
+# Use your custom pruner
+custom_pruner = MyCustomPruner()
+gsp = GSP(transactions, pruning_strategy=custom_pruner)
+result = gsp.search(min_support=0.2)
+```
+
+### Performance Characteristics
+
+Different pruning strategies have different performance tradeoffs:
+
+| Strategy | Pruning Aggressiveness | Use Case | Performance Impact |
+|----------|----------------------|----------|-------------------|
+| **SupportBased** | Moderate | General-purpose mining | Baseline performance |
+| **FrequencyBased** | High (for large datasets) | Require absolute frequency | Faster on large datasets |
+| **TemporalAware** | High (for temporal data) | Time-constrained patterns | Significant speedup for temporal mining |
+| **Combined** | Very High | Selective pattern discovery | Fastest, but may miss edge cases |
+
+### Benchmarking Pruning Strategies
+
+To compare pruning strategies on your dataset:
+
+```bash
+# Compare all strategies
+python benchmarks/bench_pruning.py --n_tx 1000 --vocab 100 --min_support 0.2 --strategy all
+
+# Benchmark a specific strategy
+python benchmarks/bench_pruning.py --n_tx 1000 --vocab 100 --min_support 0.2 --strategy frequency
+
+# Run multiple rounds for averaging
+python benchmarks/bench_pruning.py --n_tx 1000 --vocab 100 --min_support 0.2 --strategy all --rounds 3
+```
+
+See `benchmarks/bench_pruning.py` for the complete benchmarking script.
+
+---
+
 ## ⌨️ Typing
 
 `gsppy` ships inline type information (PEP 561) via a bundled `py.typed` marker. The public API is re-exported from
@@ -651,10 +785,7 @@ larger applications.
 
 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**:
+1. **Support for Preprocessing and Postprocessing**:
     - Add hooks to allow users to transform datasets before mining and customize the output results.
 
 Want to contribute or suggest an

{gsppy-3.5.0 → gsppy-3.6.0}/gsppy/__init__.py

@@ -13,6 +13,14 @@ from gsppy.cli import (
     read_transactions_from_json,
 )
 from gsppy.gsp import GSP
+from gsppy.pruning import (
+    PruningStrategy,
+    SupportBasedPruning,
+    FrequencyBasedPruning,
+    TemporalAwarePruning,
+    CombinedPruning,
+    create_default_pruning_strategy,
+)
 
 try:
     __version__ = importlib_metadata.version("gsppy")
@@ -26,4 +34,10 @@ __all__ = [
     "read_transactions_from_json",
     "setup_logging",
     "__version__",
+    "PruningStrategy",
+    "SupportBasedPruning",
+    "FrequencyBasedPruning",
+    "TemporalAwarePruning",
+    "CombinedPruning",
+    "create_default_pruning_strategy",
 ]

{gsppy-3.5.0 → gsppy-3.6.0}/gsppy/gsp.py

@@ -99,6 +99,7 @@ from gsppy.utils import (
     generate_candidates_from_previous,
     is_subsequence_in_list_with_time_constraints,
 )
+from gsppy.pruning import PruningStrategy, create_default_pruning_strategy
 from gsppy.accelerate import support_counts as support_counts_accel
 
 logger: logging.Logger = logging.getLogger(__name__)
@@ -130,6 +131,7 @@ class GSP:
         maxgap: Optional[float] = None,
         maxspan: Optional[float] = None,
         verbose: bool = False,
+        pruning_strategy: Optional[PruningStrategy] = None,
     ):
         """
         Initialize the GSP algorithm with raw transactional data.
@@ -144,6 +146,9 @@ class GSP:
             maxspan (Optional[float]): Maximum time span from first to last item in patterns.
             verbose (bool): Enable verbose logging output with detailed progress information.
                            Default is False (minimal output).
+            pruning_strategy (Optional[PruningStrategy]): Custom pruning strategy for candidate filtering.
+                                                          If None, a default strategy is created based on
+                                                          temporal constraints.
 
         Attributes Initialized:
             - Processes the input raw transaction dataset.
@@ -162,9 +167,18 @@ class GSP:
         self.maxgap = maxgap
         self.maxspan = maxspan
         self.verbose = verbose
+        self.pruning_strategy: PruningStrategy
         self._configure_logging()
         self._validate_temporal_constraints()
         self._pre_processing(raw_transactions)
+        # Initialize default pruning strategy if none provided
+        if pruning_strategy is None:
+            self.pruning_strategy = create_default_pruning_strategy(
+                mingap=self.mingap, maxgap=self.maxgap, maxspan=self.maxspan
+            )
+            logger.debug("Using default pruning strategy: %s", self.pruning_strategy.get_description())
+        else:
+            self.pruning_strategy = pruning_strategy
 
     def _configure_logging(self) -> None:
         """
@@ -389,6 +403,39 @@ class GSP:
             # Fallback to Python implementation on any acceleration failure
             return self._support_python(items, min_support, batch_size)
 
+    def _apply_pruning(
+        self, freq_patterns: Dict[Tuple[str, ...], int], min_support_count: int
+    ) -> Dict[Tuple[str, ...], int]:
+        """
+        Apply the configured pruning strategy to filter frequent patterns.
+
+        This method uses the pruning strategy to post-process patterns that have
+        already met the minimum support threshold. Additional pruning can be applied
+        based on other criteria such as temporal feasibility or frequency thresholds.
+
+        Parameters:
+            freq_patterns (Dict[Tuple[str, ...], int]): Dictionary of patterns and their support counts.
+            min_support_count (int): Absolute minimum support count threshold.
+
+        Returns:
+            Dict[Tuple[str, ...], int]: Filtered patterns after applying pruning strategy.
+        """
+        if not freq_patterns:
+            return freq_patterns
+
+        pruned_patterns: Dict[Tuple[str, ...], int] = {}
+        context = {"min_support_count": min_support_count}
+
+        for candidate, support_count in freq_patterns.items():
+            if not self.pruning_strategy.should_prune(candidate, support_count, len(self.transactions), context):
+                pruned_patterns[candidate] = support_count
+
+        num_pruned = len(freq_patterns) - len(pruned_patterns)
+        if num_pruned > 0:
+            logger.debug("Pruning strategy filtered out %d additional candidates", num_pruned)
+
+        return pruned_patterns
+
     def _print_status(self, run: int, candidates: List[Tuple[str, ...]]) -> None:
         """
         Log progress information for the current GSP iteration.
@@ -504,7 +551,10 @@ class GSP:
 
         # scan transactions to collect support count for each candidate
         # sequence & filter
-        self.freq_patterns.append(self._support(candidates, abs_min_support, backend=backend))
+        freq_1 = self._support(candidates, abs_min_support, backend=backend)
+        # Apply pruning strategy for additional filtering
+        freq_1 = self._apply_pruning(freq_1, abs_min_support)
+        self.freq_patterns.append(freq_1)
 
         # (k-itemsets/k-sequence = 1)
         k_items = 1
@@ -525,7 +575,10 @@ class GSP:
 
             # candidate pruning - eliminates candidates who are not potentially
             # frequent (using support as threshold)
-            self.freq_patterns.append(self._support(candidates, abs_min_support, backend=backend))
+            freq_k = self._support(candidates, abs_min_support, backend=backend)
+            # Apply pruning strategy for additional filtering
+            freq_k = self._apply_pruning(freq_k, abs_min_support)
+            self.freq_patterns.append(freq_k)
 
             self._print_status(k_items, candidates)
         logger.info("GSP algorithm completed.")