gsppy 3.0.1__py3-none-any.whl → 3.1.1__py3-none-any.whl

gsppy/utils.py

@@ -5,14 +5,14 @@ and generating candidate patterns from previously frequent patterns.
 
 The key functionalities include:
 1. Splitting a list of items into smaller batches for easier processing.
-2. Checking for the existence of a contiguous subsequence within a sequence,
+2. Checking for the existence of an ordered (non-contiguous) subsequence within a sequence,
    with caching to optimize repeated comparisons.
 3. Generating candidate patterns from a dictionary of frequent patterns
    to support pattern generation tasks in algorithms like sequence mining.
 
 Main functionalities:
 - `split_into_batches`: Splits a list of items into smaller batches based on a specified batch size.
-- `is_subsequence_in_list`: Determines if a subsequence exists within another sequence,
+- `is_subsequence_in_list`: Determines if a subsequence exists within another sequence in order,
   using caching to improve performance.
 - `generate_candidates_from_previous`: Generates candidate patterns by joining previously
   identified frequent patterns.
@@ -46,7 +46,10 @@ def split_into_batches(
 @lru_cache(maxsize=None)
 def is_subsequence_in_list(subsequence: Tuple[str, ...], sequence: Tuple[str, ...]) -> bool:
     """
-    Check if a subsequence exists within a sequence as a contiguous subsequence.
+    Check if a subsequence exists within a sequence as an ordered (non-contiguous) subsequence.
+
+    This function implements the standard GSP semantics where items in the subsequence
+    must appear in the same order in the sequence, but not necessarily contiguously.
 
     Parameters:
         subsequence: (tuple): The sequence to search for.
@@ -54,6 +57,14 @@ def is_subsequence_in_list(subsequence: Tuple[str, ...], sequence: Tuple[str, ..
 
     Returns:
         bool: True if the subsequence is found, False otherwise.
+
+    Examples:
+        >>> is_subsequence_in_list(('a', 'c'), ('a', 'b', 'c'))
+        True
+        >>> is_subsequence_in_list(('a', 'c'), ('c', 'a'))
+        False
+        >>> is_subsequence_in_list(('a', 'b'), ('a', 'b', 'c'))
+        True
     """
     # Handle the case where the subsequence is empty - it should not exist in any sequence
     if not subsequence:
@@ -61,12 +72,18 @@ def is_subsequence_in_list(subsequence: Tuple[str, ...], sequence: Tuple[str, ..
 
     len_sub, len_seq = len(subsequence), len(sequence)
 
-    # Return False if the sequence is longer than the list
+    # Return False if the subsequence is longer than the sequence
     if len_sub > len_seq:
         return False
 
-    # Use any to check if any slice matches the sequence
-    return any(sequence[i : i + len_sub] == subsequence for i in range(len_seq - len_sub + 1))
+    # Use two-pointer approach to check if subsequence exists in order
+    sub_idx = 0
+    for seq_idx in range(len_seq):
+        if sequence[seq_idx] == subsequence[sub_idx]:
+            sub_idx += 1
+            if sub_idx == len_sub:
+                return True
+    return False
 
 
 def generate_candidates_from_previous(prev_patterns: Dict[Tuple[str, ...], int]) -> List[Tuple[str, ...]]:

{gsppy-3.0.1.dist-info → gsppy-3.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gsppy
-Version: 3.0.1
+Version: 3.1.1
 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>
@@ -41,21 +41,21 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0.0
 Provides-Extra: dev
-Requires-Dist: cython==3.1.3; extra == 'dev'
-Requires-Dist: hatch==1.14.1; extra == 'dev'
+Requires-Dist: cython==3.1.4; extra == 'dev'
+Requires-Dist: hatch==1.15.1; extra == 'dev'
 Requires-Dist: hatchling==1.27.0; extra == 'dev'
-Requires-Dist: mypy==1.18.1; extra == 'dev'
-Requires-Dist: pylint==3.3.8; extra == 'dev'
-Requires-Dist: pyright==1.1.405; extra == 'dev'
+Requires-Dist: mypy==1.18.2; extra == 'dev'
+Requires-Dist: pylint==4.0.2; extra == 'dev'
+Requires-Dist: pyright==1.1.406; extra == 'dev'
 Requires-Dist: pytest-benchmark==5.1.0; extra == 'dev'
 Requires-Dist: pytest-cov==7.0.0; extra == 'dev'
 Requires-Dist: pytest==8.4.2; extra == 'dev'
-Requires-Dist: ruff==0.13.0; extra == 'dev'
-Requires-Dist: tox==4.30.2; extra == 'dev'
+Requires-Dist: ruff==0.13.3; extra == 'dev'
+Requires-Dist: tox==4.32.0; extra == 'dev'
 Provides-Extra: gpu
 Requires-Dist: cupy<14,>=11; extra == 'gpu'
 Provides-Extra: rust
-Requires-Dist: maturin==1.9.4; extra == 'rust'
+Requires-Dist: maturin==1.9.6; extra == 'rust'
 Description-Content-Type: text/markdown
 
 [![PyPI License](https://img.shields.io/pypi/l/gsppy.svg?style=flat-square)]()
@@ -104,14 +104,15 @@ principles**. Using support thresholds, GSP identifies frequent sequences of ite
 
 ### Key Features:
 
+- **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.
 - **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."
+- In a shopping dataset, GSP can identify patterns like "Customers who buy bread and milk often purchase diapers next" - even if other items appear between bread and milk.
+- In a website clickstream, GSP might find patterns like "Users visit A, then eventually go to C" - capturing user journeys with intermediate steps.
 
 ---
 
@@ -427,24 +428,57 @@ Sample Output:
 ```python
 [
     {('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}
+    {('Bread', 'Milk'): 3, ('Bread', 'Diaper'): 3, ('Bread', 'Beer'): 2, ('Milk', 'Diaper'): 3, ('Milk', 'Beer'): 2, ('Milk', 'Coke'): 2, ('Diaper', 'Beer'): 3, ('Diaper', 'Coke'): 2},
+    {('Bread', 'Milk', 'Diaper'): 2, ('Bread', 'Diaper', 'Beer'): 2, ('Milk', 'Diaper', 'Beer'): 2, ('Milk', 'Diaper', 'Coke'): 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).
+  Bread → Milk" appears in 3 transactions). Note that patterns like `('Bread', 'Beer')` are detected even when they don't appear adjacent in transactions - they just need to appear in order.
 - 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%).
+> The **support** of a sequence is calculated as the fraction of transactions containing the sequence **in order** (not necessarily contiguously), 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.
 
+> [!IMPORTANT]
+> **Non-contiguous (ordered) matching**: GSP-Py detects patterns where items appear in the specified order but not necessarily adjacent. For example, the pattern `('Bread', 'Beer')` matches the transaction `['Bread', 'Milk', 'Diaper', 'Beer']` because Bread appears before Beer, even though they are not adjacent. This follows the standard GSP algorithm semantics for sequential pattern mining.
+
+### Understanding Non-Contiguous Pattern Matching
+
+GSP-Py follows the standard GSP algorithm semantics by detecting **ordered (non-contiguous)** subsequences. This means:
+
+- ✅ **Order matters**: Items must appear in the specified sequence order
+- ✅ **Gaps allowed**: Items don't need to be adjacent
+- ❌ **Wrong order rejected**: Items appearing in different order won't match
+
+**Example:**
+
+```python
+from gsppy.gsp import GSP
+
+sequences = [
+    ['a', 'b', 'c'],  # Contains: (a,b), (a,c), (b,c), (a,b,c)
+    ['a', 'c'],       # Contains: (a,c)
+    ['b', 'c', 'a'],  # Contains: (b,c), (b,a), (c,a)
+    ['a', 'b', 'c', 'd'],  # Contains: (a,b), (a,c), (a,d), (b,c), (b,d), (c,d), etc.
+]
+
+gsp = GSP(sequences)
+result = gsp.search(min_support=0.5)  # Need at least 2/4 sequences
+
+# Pattern ('a', 'c') is found with support=3 because:
+# - It appears in ['a', 'b', 'c'] (with 'b' in between)
+# - It appears in ['a', 'c'] (adjacent)
+# - It appears in ['a', 'b', 'c', 'd'] (with 'b' in between)
+# Total: 3 out of 4 sequences = 75% support ✅
+```
+
 
 > [!TIP]
 > For more complex examples, find example scripts in the [`gsppy/tests`](gsppy/tests) folder.

gsppy-3.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+gsppy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gsppy/accelerate.py,sha256=YO3YQFzo2VAC6IXOTnQnOajkZO7SabkieGb1IPgWdSI,10407
+gsppy/cli.py,sha256=wsGoc_utxpRfgCF9vPOAyLDTOJZ8NaiwiUny5VyIYvQ,6567
+gsppy/gsp.py,sha256=GCHFhOu-DyHEPsse_OXzf9IaZoigF8ouRqgn_OsZBvA,14855
+gsppy/utils.py,sha256=KtjfDgsTwvwxIyA2KCQmgu8cFkBqQvMZN8Ct5NB60Tc,3952
+gsppy-3.1.1.dist-info/METADATA,sha256=uN-rN-CzsrwW_uh4s60DUevIKjm5CuiYyHRh5cgyKqQ,19819
+gsppy-3.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+gsppy-3.1.1.dist-info/entry_points.txt,sha256=smvmcIWk424ARIGKOC_BM42hpT_SptKPcIeqs-8u8lM,41
+gsppy-3.1.1.dist-info/licenses/LICENSE,sha256=AlXanKSqFzo_o-87gp3Qw3XzbmnfxYy7O0xJOcQGWJo,1086
+gsppy-3.1.1.dist-info/RECORD,,

{gsppy-3.0.1.dist-info → gsppy-3.1.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

gsppy-3.0.1.dist-info/RECORD

@@ -1,10 +0,0 @@
-gsppy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-gsppy/accelerate.py,sha256=YO3YQFzo2VAC6IXOTnQnOajkZO7SabkieGb1IPgWdSI,10407
-gsppy/cli.py,sha256=wsGoc_utxpRfgCF9vPOAyLDTOJZ8NaiwiUny5VyIYvQ,6567
-gsppy/gsp.py,sha256=GCHFhOu-DyHEPsse_OXzf9IaZoigF8ouRqgn_OsZBvA,14855
-gsppy/utils.py,sha256=YlV0F64lnd2Xymf6XnYr6mMLYWV2f2yjaHkZbAS1Qs0,3362
-gsppy-3.0.1.dist-info/METADATA,sha256=vt35btl69hnEM4R1Kz-U5m-2MHEN5hdkHBk-uJ2eKAw,17670
-gsppy-3.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-gsppy-3.0.1.dist-info/entry_points.txt,sha256=smvmcIWk424ARIGKOC_BM42hpT_SptKPcIeqs-8u8lM,41
-gsppy-3.0.1.dist-info/licenses/LICENSE,sha256=AlXanKSqFzo_o-87gp3Qw3XzbmnfxYy7O0xJOcQGWJo,1086
-gsppy-3.0.1.dist-info/RECORD,,