gsppy 4.0.0__tar.gz → 4.2.0__tar.gz

{gsppy-4.0.0 → gsppy-4.2.0}/CHANGELOG.md

@@ -1,6 +1,76 @@
 # CHANGELOG
 
 
+## 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
+
+- Address code review feedback - add type annotations and remove unused variables
+  ([`bf62d14`](https://github.com/jacksonpradolima/gsp-py/commit/bf62d144d8f1be1e7716291d41af955450612c81))
+
+Co-authored-by: jacksonpradolima <7774063+jacksonpradolima@users.noreply.github.com>
+
+### Chores
+
+- Update uv.lock for version 4.0.0
+  ([`f1ae2af`](https://github.com/jacksonpradolima/gsp-py/commit/f1ae2af2aa71ea44b9d8625ed647da79259ec096))
+
+### Documentation
+
+- Add Sequence documentation and examples to README
+  ([`62d0d02`](https://github.com/jacksonpradolima/gsp-py/commit/62d0d02c19c5751331df53e680cc0b9aee19677b))
+
+Co-authored-by: jacksonpradolima <7774063+jacksonpradolima@users.noreply.github.com>
+
+- Update docs/ with Sequence abstraction documentation
+  ([`2368cf3`](https://github.com/jacksonpradolima/gsp-py/commit/2368cf30239139e8e2af5457ee6acf14db30ef06))
+
+Co-authored-by: jacksonpradolima <7774063+jacksonpradolima@users.noreply.github.com>
+
+### Features
+
+- Add Sequence abstraction class with comprehensive tests
+  ([`6011bdb`](https://github.com/jacksonpradolima/gsp-py/commit/6011bdb7104755d109b58261b36e1dd1c36b2d61))
+
+Co-authored-by: jacksonpradolima <7774063+jacksonpradolima@users.noreply.github.com>
+
+- Integrate Sequence objects with GSP.search() via return_sequences parameter
+  ([`7476588`](https://github.com/jacksonpradolima/gsp-py/commit/7476588f2b277276748e0550366014f2a93d8ef5))
+
+Co-authored-by: jacksonpradolima <7774063+jacksonpradolima@users.noreply.github.com>
+
+- Introduce Sequence abstraction for typed pattern representation
+  ([`01ca37b`](https://github.com/jacksonpradolima/gsp-py/commit/01ca37b9bc4572eb7b1c1eaf6fdf26ca2324a3c5))
+
+### Refactoring
+
+- Address code review feedback - remove redundant checks
+  ([`621e940`](https://github.com/jacksonpradolima/gsp-py/commit/621e9403379ae0fd07bf45b97616b9979f2d4aa6))
+
+Co-authored-by: jacksonpradolima <7774063+jacksonpradolima@users.noreply.github.com>
+
+- Reduce cognitive complexity in sequence_example.py and fix f-string
+  ([`63ac4f9`](https://github.com/jacksonpradolima/gsp-py/commit/63ac4f9ceb869a5228cdccdcf6a9d0b9f46f0350))
+
+Co-authored-by: jacksonpradolima <7774063+jacksonpradolima@users.noreply.github.com>
+
+- Update type annotations and improve search method in GSP class
+  ([`e2e9a3f`](https://github.com/jacksonpradolima/gsp-py/commit/e2e9a3f473d1e0c5d6990c8b7c5837a251761032))
+
+
 ## v4.0.0 (2026-02-01)
 
 ### Chores

{gsppy-4.0.0 → gsppy-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gsppy
-Version: 4.0.0
+Version: 4.2.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)
@@ -559,6 +560,82 @@ Verbose mode provides:
 
 For complete documentation on logging, see [docs/logging.md](docs/logging.md).
 
+### Using Sequence Objects for Rich Pattern Representation
+
+GSP-Py 4.0+ introduces a **Sequence abstraction class** that provides a richer, more maintainable way to work with sequential patterns. The Sequence class encapsulates pattern items, support counts, and optional metadata in an immutable, hashable object.
+
+#### Traditional Dict-based Output (Default)
+
+```python
+from gsppy import GSP
+
+transactions = [
+    ['Bread', 'Milk'],
+    ['Bread', 'Diaper', 'Beer', 'Eggs'],
+    ['Milk', 'Diaper', 'Beer', 'Coke']
+]
+
+gsp = GSP(transactions)
+result = gsp.search(min_support=0.3)
+
+# Returns: [{('Bread',): 4, ('Milk',): 4, ...}, {('Bread', 'Milk'): 3, ...}, ...]
+for level_patterns in result:
+    for pattern, support in level_patterns.items():
+        print(f"Pattern: {pattern}, Support: {support}")
+```
+
+#### Sequence Objects (New Feature)
+
+```python
+from gsppy import GSP
+
+transactions = [
+    ['Bread', 'Milk'],
+    ['Bread', 'Diaper', 'Beer', 'Eggs'],
+    ['Milk', 'Diaper', 'Beer', 'Coke']
+]
+
+gsp = GSP(transactions)
+result = gsp.search(min_support=0.3, return_sequences=True)
+
+# Returns: [[Sequence(('Bread',), support=4), ...], [Sequence(('Bread', 'Milk'), support=3), ...], ...]
+for level_patterns in result:
+    for seq in level_patterns:
+        print(f"Pattern: {seq.items}, Support: {seq.support}, Length: {seq.length}")
+        # Access sequence properties
+        print(f"  First item: {seq.first_item}, Last item: {seq.last_item}")
+        # Check if item is in sequence
+        if "Milk" in seq:
+            print(f"  Contains Milk!")
+```
+
+#### Key Benefits of Sequence Objects
+
+1. **Rich API**: Access pattern properties like `length`, `first_item`, `last_item`
+2. **Type Safety**: IDE autocomplete and better type hints
+3. **Immutable & Hashable**: Can be used as dictionary keys
+4. **Extensible**: Add metadata for confidence, lift, or custom properties
+5. **Backward Compatible**: Convert to/from dict format as needed
+
+```python
+from gsppy import Sequence, sequences_to_dict, dict_to_sequences
+
+# Create custom sequences
+seq = Sequence.from_tuple(("A", "B", "C"), support=5)
+
+# Extend sequences
+extended = seq.extend("D")  # Creates Sequence(("A", "B", "C", "D"))
+
+# Add metadata
+seq_with_meta = seq.with_metadata(confidence=0.85, lift=1.5)
+
+# Convert between formats for compatibility
+seq_result = gsp.search(min_support=0.3, return_sequences=True)
+dict_format = sequences_to_dict(seq_result[0])  # Convert to dict
+```
+
+For a complete example, see [examples/sequence_example.py](examples/sequence_example.py).
+
 ### Loading SPM/GSP Format Files
 
 GSP-Py supports loading datasets in the classical SPM/GSP delimiter format, which is widely used in sequential pattern mining research. This format uses:
@@ -904,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.0.0 → gsppy-4.2.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)
@@ -486,6 +487,82 @@ Verbose mode provides:
 
 For complete documentation on logging, see [docs/logging.md](docs/logging.md).
 
+### Using Sequence Objects for Rich Pattern Representation
+
+GSP-Py 4.0+ introduces a **Sequence abstraction class** that provides a richer, more maintainable way to work with sequential patterns. The Sequence class encapsulates pattern items, support counts, and optional metadata in an immutable, hashable object.
+
+#### Traditional Dict-based Output (Default)
+
+```python
+from gsppy import GSP
+
+transactions = [
+    ['Bread', 'Milk'],
+    ['Bread', 'Diaper', 'Beer', 'Eggs'],
+    ['Milk', 'Diaper', 'Beer', 'Coke']
+]
+
+gsp = GSP(transactions)
+result = gsp.search(min_support=0.3)
+
+# Returns: [{('Bread',): 4, ('Milk',): 4, ...}, {('Bread', 'Milk'): 3, ...}, ...]
+for level_patterns in result:
+    for pattern, support in level_patterns.items():
+        print(f"Pattern: {pattern}, Support: {support}")
+```
+
+#### Sequence Objects (New Feature)
+
+```python
+from gsppy import GSP
+
+transactions = [
+    ['Bread', 'Milk'],
+    ['Bread', 'Diaper', 'Beer', 'Eggs'],
+    ['Milk', 'Diaper', 'Beer', 'Coke']
+]
+
+gsp = GSP(transactions)
+result = gsp.search(min_support=0.3, return_sequences=True)
+
+# Returns: [[Sequence(('Bread',), support=4), ...], [Sequence(('Bread', 'Milk'), support=3), ...], ...]
+for level_patterns in result:
+    for seq in level_patterns:
+        print(f"Pattern: {seq.items}, Support: {seq.support}, Length: {seq.length}")
+        # Access sequence properties
+        print(f"  First item: {seq.first_item}, Last item: {seq.last_item}")
+        # Check if item is in sequence
+        if "Milk" in seq:
+            print(f"  Contains Milk!")
+```
+
+#### Key Benefits of Sequence Objects
+
+1. **Rich API**: Access pattern properties like `length`, `first_item`, `last_item`
+2. **Type Safety**: IDE autocomplete and better type hints
+3. **Immutable & Hashable**: Can be used as dictionary keys
+4. **Extensible**: Add metadata for confidence, lift, or custom properties
+5. **Backward Compatible**: Convert to/from dict format as needed
+
+```python
+from gsppy import Sequence, sequences_to_dict, dict_to_sequences
+
+# Create custom sequences
+seq = Sequence.from_tuple(("A", "B", "C"), support=5)
+
+# Extend sequences
+extended = seq.extend("D")  # Creates Sequence(("A", "B", "C", "D"))
+
+# Add metadata
+seq_with_meta = seq.with_metadata(confidence=0.85, lift=1.5)
+
+# Convert between formats for compatibility
+seq_result = gsp.search(min_support=0.3, return_sequences=True)
+dict_format = sequences_to_dict(seq_result[0])  # Convert to dict
+```
+
+For a complete example, see [examples/sequence_example.py](examples/sequence_example.py).
+
 ### Loading SPM/GSP Format Files
 
 GSP-Py supports loading datasets in the classical SPM/GSP delimiter format, which is widely used in sequential pattern mining research. This format uses:
@@ -831,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.0.0 → gsppy-4.2.0}/gsppy/__init__.py

@@ -24,6 +24,12 @@ from gsppy.pruning import (
     FrequencyBasedPruning,
     create_default_pruning_strategy,
 )
+from gsppy.sequence import (
+    Sequence,
+    sequences_to_dict,
+    dict_to_sequences,
+    to_sequence,
+)
 from gsppy.token_mapper import TokenMapper
 
 # DataFrame adapters are optional - import only if dependencies are available
@@ -63,6 +69,10 @@ __all__ = [
     "TemporalAwarePruning",
     "CombinedPruning",
     "create_default_pruning_strategy",
+    "Sequence",
+    "sequences_to_dict",
+    "dict_to_sequences",
+    "to_sequence",
     "TokenMapper",
 ]
 

{gsppy-4.0.0 → gsppy-4.2.0}/gsppy/cli.py

@@ -35,7 +35,7 @@ import csv
 import sys
 import json
 import logging
-from typing import Any, Dict, List, Tuple, Union, Optional, cast
+from typing import Any, List, Tuple, Union, Optional, cast
 
 import click
 
@@ -608,7 +608,7 @@ def main(
     # Initialize and run GSP algorithm
     try:
         gsp = GSP(transactions, mingap=mingap, maxgap=maxgap, maxspan=maxspan, verbose=verbose)
-        patterns: List[Dict[Tuple[str, ...], int]] = gsp.search(min_support=min_support)
+        patterns = gsp.search(min_support=min_support, return_sequences=False)
         logger.info("Frequent Patterns Found:")
         for i, level in enumerate(patterns, start=1):
             logger.info(f"\n{i}-Sequence Patterns:")