gsppy 3.4.3__tar.gz → 3.6.0__tar.gz

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

@@ -1,6 +1,86 @@
 # 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
+
+- Address code review feedback
+  ([`1e7cf86`](https://github.com/jacksonpradolima/gsp-py/commit/1e7cf8681b3cd0432e6d1608187b7d518c27fcc0))
+
+- Remove root logger modifications to prevent global side effects - Fix redundant logger
+  configuration in CLI - Remove redundant subprocess imports in tests - Revert unrelated formatting
+  changes in temporal constraints tests - Replace future dates with YYYY-MM-DD placeholders in
+  documentation - Add explanation for not using Loguru in logging documentation
+
+All changes address feedback from code review while maintaining backward compatibility and test
+  coverage.
+
+Co-authored-by: jacksonpradolima <7774063+jacksonpradolima@users.noreply.github.com>
+
+- Specify logger name in caplog for verbose tests
+  ([`cb477b0`](https://github.com/jacksonpradolima/gsp-py/commit/cb477b0f040ce38b60b6e3d485536e79d6d3ea19))
+
+Update test_verbose_initialization, test_non_verbose_initialization, and
+  test_verbose_override_in_search to use caplog.at_level(logging.DEBUG, logger='gsppy.gsp') instead
+  of just caplog.at_level(logging.DEBUG). This ensures tests only capture logs from the gsppy.gsp
+  logger, preventing interference from other loggers and making tests more reliable.
+
+Co-authored-by: jacksonpradolima <7774063+jacksonpradolima@users.noreply.github.com>
+
+- Update test_setup_logging_verbose to match refactored logging
+  ([`ab78c33`](https://github.com/jacksonpradolima/gsp-py/commit/ab78c33ee1c09964773b1af835c9bb133a778824))
+
+Update test to verify logging.basicConfig is called with DEBUG level instead of checking the removed
+  explicit logger.setLevel call. This aligns with the refactored logging configuration that removed
+  redundant logger level setting.
+
+Co-authored-by: jacksonpradolima <7774063+jacksonpradolima@users.noreply.github.com>
+
+### Chores
+
+- Update uv.lock for version 3.4.3
+  ([`6a78997`](https://github.com/jacksonpradolima/gsp-py/commit/6a789979fd6a7422c063dbe5b2ff46cd0d2141c6))
+
+### Features
+
+- Add explicit verbosity control and structured logging
+  ([`44f56d9`](https://github.com/jacksonpradolima/gsp-py/commit/44f56d947978ddad1b7f2a2cca00f59def0ce4e4))
+
+feat: add explicit verbosity control and structured logging
+
+### Refactoring
+
+- Gsp initialization in tests to handle constraints explicitly and improve verbosity handling
+  ([`ced0243`](https://github.com/jacksonpradolima/gsp-py/commit/ced0243e58ff444988e37f5ae472f58d4478498e))
+
+- Gsp initialization in tests to handle constraints explicitly and improve verbosity handling
+  ([`479f305`](https://github.com/jacksonpradolima/gsp-py/commit/479f305aae02217ce7b75fede5e0fb249fd1b477))
+
+
 ## v3.4.3 (2026-01-25)
 
 ### Bug Fixes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gsppy
-Version: 3.4.3
+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'
@@ -105,6 +106,7 @@ Sequence Pattern (GSP)** algorithm. Ideal for market basket analysis, temporal m
 6. [💡 Usage](#usage)
     - [✅ Example: Analyzing Sales Data](#example-analyzing-sales-data)
     - [📊 Explanation: Support and Results](#explanation-support-and-results)
+    - [⏱️ Temporal Constraints](#temporal-constraints)
 7. [⌨️ Typing](#typing)
 8. [🌟 Planned Features](#planned-features)
 9. [🤝 Contributing](#contributing)
@@ -123,6 +125,7 @@ principles**. Using support thresholds, GSP identifies frequent sequences of ite
 - **Ordered (non-contiguous) matching**: Detects patterns where items appear in order but not necessarily adjacent, following standard GSP semantics. For example, the pattern `('A', 'C')` is found in the sequence `['A', 'B', 'C']`.
 - **Support-based pruning**: Only retains sequences that meet the minimum support threshold.
 - **Candidate generation**: Iteratively generates candidate sequences of increasing length.
+- **Temporal constraints**: Support for time-constrained pattern mining with `mingap`, `maxgap`, and `maxspan` parameters to find patterns within specific time windows.
 - **General-purpose**: Useful in retail, web analytics, social networks, temporal sequence mining, and more.
 
 For example:
@@ -373,7 +376,28 @@ gsppy --file path/to/transactions.csv --min_support 0.3 --backend rust
 - `--file`: Path to your input file (JSON or CSV). **Required**.
 - `--min_support`: Minimum support threshold as a fraction (e.g., `0.3` for 30%). Default is `0.2`.
 - `--backend`: Backend to use for support counting. One of `auto` (default), `python`, `rust`, or `gpu`.
-- `--verbose`: (Optional) Enable detailed output for debugging.
+- `--verbose`: Enable detailed logging with timestamps, log levels, and process IDs for debugging and traceability.
+- `--mingap`, `--maxgap`, `--maxspan`: Temporal constraints for time-aware pattern mining (requires timestamped transactions).
+
+#### Verbose Mode
+
+For debugging or to track execution in CI/CD pipelines, use the `--verbose` flag:
+
+```bash
+gsppy --file transactions.json --min_support 0.3 --verbose
+```
+
+This produces structured logging output with timestamps, log levels, and process information:
+
+```
+YYYY-MM-DDTHH:MM:SS | INFO     | PID:4179 | gsppy.gsp | Pre-processing transactions...
+YYYY-MM-DDTHH:MM:SS | DEBUG    | PID:4179 | gsppy.gsp | Unique candidates: [('Bread',), ('Milk',), ...]
+YYYY-MM-DDTHH:MM:SS | INFO     | PID:4179 | gsppy.gsp | Starting GSP algorithm with min_support=0.3...
+YYYY-MM-DDTHH:MM:SS | INFO     | PID:4179 | gsppy.gsp | Run 1: 6 candidates filtered to 5.
+...
+```
+
+For complete logging documentation, see [docs/logging.md](docs/logging.md).
 
 #### Example
 
@@ -470,6 +494,30 @@ result = GSP(transactions).search(min_support)
 print(result)
 ```
 
+### Verbose Mode for Debugging
+
+Enable detailed logging to track algorithm progress and debug issues:
+
+```python
+from gsppy.gsp import GSP
+
+# Enable verbose logging for the entire instance
+gsp = GSP(transactions, verbose=True)
+result = gsp.search(min_support=0.3)
+
+# Or enable verbose for a specific search only
+gsp = GSP(transactions)
+result = gsp.search(min_support=0.3, verbose=True)
+```
+
+Verbose mode provides:
+- Detailed progress information during execution
+- Candidate generation and filtering statistics
+- Preprocessing and validation details
+- Useful for debugging, research, and CI/CD integration
+
+For complete documentation on logging, see [docs/logging.md](docs/logging.md).
+
 ### Output
 
 The algorithm will return a list of patterns with their corresponding support.
@@ -536,6 +584,262 @@ result = gsp.search(min_support=0.5)  # Need at least 2/4 sequences
 
 ---
 
+## ⏱️ 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.
+
+### Temporal Constraint Parameters
+
+- **`mingap`**: Minimum time gap required between consecutive items in a pattern
+- **`maxgap`**: Maximum time gap allowed between consecutive items in a pattern  
+- **`maxspan`**: Maximum time span from the first to the last item in a pattern
+
+### Using Temporal Constraints
+
+To use temporal constraints, your transactions must include timestamps as (item, timestamp) tuples:
+
+```python
+from gsppy.gsp import GSP
+
+# Transactions with timestamps (e.g., in seconds, hours, days, etc.)
+timestamped_transactions = [
+    [("Login", 0), ("Browse", 2), ("AddToCart", 5), ("Purchase", 7)],
+    [("Login", 0), ("Browse", 1), ("AddToCart", 15), ("Purchase", 20)],
+    [("Login", 0), ("Browse", 3), ("AddToCart", 6), ("Purchase", 8)],
+]
+
+# Find patterns where consecutive events occur within 10 time units
+gsp = GSP(timestamped_transactions, maxgap=10)
+patterns = gsp.search(min_support=0.6)
+
+# The pattern ("Browse", "AddToCart", "Purchase") will:
+# - Be found in transaction 1: gaps are 3 and 2 (both ≤ 10) ✅
+# - NOT be found in transaction 2: gap between Browse→AddToCart is 14 (exceeds maxgap) ❌
+# - Be found in transaction 3: gaps are 3 and 2 (both ≤ 10) ✅
+# Result: Support = 2/3 = 67% (above threshold of 60%)
+```
+
+### CLI Usage with Temporal Constraints
+
+```bash
+# Find patterns with maximum gap of 5 time units
+gsppy --file temporal_data.json --min_support 0.3 --maxgap 5
+
+# Find patterns with minimum gap of 2 time units
+gsppy --file temporal_data.json --min_support 0.3 --mingap 2
+
+# Find patterns that complete within 10 time units
+gsppy --file temporal_data.json --min_support 0.3 --maxspan 10
+
+# Combine multiple constraints
+gsppy --file temporal_data.json --min_support 0.3 --mingap 1 --maxgap 5 --maxspan 10
+```
+
+### Real-World Examples
+
+#### Medical Event Mining
+
+```python
+from gsppy.gsp import GSP
+
+# Medical events with timestamps in days
+medical_sequences = [
+    [("Symptom", 0), ("Diagnosis", 2), ("Treatment", 5), ("Recovery", 15)],
+    [("Symptom", 0), ("Diagnosis", 1), ("Treatment", 20), ("Recovery", 30)],
+    [("Symptom", 0), ("Diagnosis", 3), ("Treatment", 6), ("Recovery", 18)],
+]
+
+# Find patterns where treatment follows diagnosis within 10 days
+gsp = GSP(medical_sequences, maxgap=10)
+result = gsp.search(min_support=0.5)
+
+# Pattern ("Diagnosis", "Treatment") found in sequences 1 & 3 only
+# (sequence 2 has gap of 19 days, exceeding maxgap)
+```
+
+#### Retail Analytics
+
+```python
+from gsppy.gsp import GSP
+
+# Customer purchases with timestamps in hours
+purchase_sequences = [
+    [("Browse", 0), ("AddToCart", 0.5), ("Purchase", 1)],
+    [("Browse", 0), ("AddToCart", 1), ("Purchase", 25)],  # Long delay
+    [("Browse", 0), ("AddToCart", 0.3), ("Purchase", 0.8)],
+]
+
+# Find purchase journeys that complete within 2 hours
+gsp = GSP(purchase_sequences, maxspan=2)
+result = gsp.search(min_support=0.5)
+
+# Full sequence found in 2 out of 3 transactions
+# (sequence 2 has span of 25 hours, exceeding maxspan)
+```
+
+#### User Journey Discovery
+
+```python
+from gsppy.gsp import GSP
+
+# Website navigation with timestamps in seconds
+navigation_sequences = [
+    [("Home", 0), ("Search", 5), ("Product", 10), ("Checkout", 15)],
+    [("Home", 0), ("Search", 3), ("Product", 8), ("Checkout", 180)],
+    [("Home", 0), ("Search", 4), ("Product", 9), ("Checkout", 14)],
+]
+
+# Find navigation patterns with:
+# - Minimum 2 seconds between steps (mingap)
+# - Maximum 20 seconds between steps (maxgap)
+# - Complete within 30 seconds total (maxspan)
+gsp = GSP(navigation_sequences, mingap=2, maxgap=20, maxspan=30)
+result = gsp.search(min_support=0.5)
+```
+
+### Important Notes
+
+- Temporal constraints require timestamped transactions (item-timestamp tuples)
+- If temporal constraints are specified but transactions don't have timestamps, a warning is logged and constraints are ignored
+- When using temporal constraints, the Python backend is automatically used (accelerated backends don't yet support temporal constraints)
+- Timestamps can be in any unit (seconds, minutes, hours, days) as long as they're consistent within your dataset
+
+---
+
+## 🔧 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
@@ -549,17 +853,9 @@ 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.
 
-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!](https://github.com/jacksonpradolima/gsp-py/issues)