polars-sgt 0.1.0__cp39-abi3-win_amd64.whl

polars_sgt/namespace.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+import polars as pl
+
+from polars_sgt import functions
+
+
+@pl.api.register_expr_namespace("xdt")
+class ExprXDTNamespace:
+    """eXtra stuff for DateTimes."""
+
+    def __init__(self, expr: pl.Expr) -> None:
+        self._expr = expr
+
+    def __getattr__(self, function_name: str) -> Callable[[Any], pl.Expr]:
+        def func(*args: Any, **kwargs: Any) -> pl.Expr:
+            return getattr(functions, function_name)(
+                self._expr, *args, **kwargs
+            )
+
+        return func

polars_sgt/ranges.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Literal, Union, overload
+from typing import TYPE_CHECKING, Literal, overload
+
+import polars as pl
+
+mapping = {"Mon": 1, "Tue": 2, "Wed": 3, "Thu": 4, "Fri": 5, "Sat": 6, "Sun": 7}
+
+if TYPE_CHECKING:
+    import sys
+    from collections.abc import Sequence
+    from datetime import date, datetime, timedelta
+
+    if sys.version_info >= (3, 10):
+        from typing import TypeAlias
+    else:
+        from typing_extensions import TypeAlias
+
+    ClosedInterval: TypeAlias = Literal[
+        "left", "right", "both", "none"
+    ]  # ClosedWindow
+    IntoExprColumn: TypeAlias = "pl.Expr" | "pl.Series" | str
+
+from polars_sgt.typing import IntoExprColumn
+from polars_sgt.utils import parse_into_expr
+
+
+@overload
+def date_range(
+    start: date | datetime | IntoExprColumn,
+    end: date | datetime | IntoExprColumn,
+    interval: str | timedelta = "1d",
+    *,
+    closed: ClosedInterval = ...,
+    eager: Literal[False] = ...,
+    weekend: Sequence[str] = ...,
+    holidays: Sequence[date] | None = ...,
+) -> pl.Expr: ...
+
+
+@overload
+def date_range(
+    start: date | IntoExprColumn,
+    end: date | IntoExprColumn,
+    interval: str | timedelta = "1d",
+    *,
+    closed: ClosedInterval = ...,
+    eager: Literal[True],
+    weekend: Sequence[str] = ...,
+    holidays: Sequence[date] | None = ...,
+) -> pl.Series: ...
+
+
+@overload
+def date_range(
+    start: date | IntoExprColumn,
+    end: date | IntoExprColumn,
+    interval: str | timedelta = "1d",
+    *,
+    closed: ClosedInterval = ...,
+    eager: bool = ...,
+    weekend: Sequence[str] = ...,
+    holidays: Sequence[date] | None = ...,
+) -> pl.Series | pl.Expr: ...
+
+
+def date_range(  # noqa: PLR0913
+    start: date | IntoExprColumn,
+    end: date | IntoExprColumn,
+    interval: str | timedelta = "1bd",
+    *,
+    closed: ClosedInterval = "both",
+    eager: bool = False,
+    weekend: Sequence[str] = ("Sat", "Sun"),
+    holidays: Sequence[date] | None = None,
+) -> pl.Series | pl.Expr:
+    """
+    Create a range of dates with a given interval and filter out weekends and holidays.
+
+    Parameters
+    ----------
+    start
+        Lower bound of the date range.
+    end
+        Upper bound of the date range.
+    interval
+        Interval of the range periods, specified as a Python ``timedelta`` object
+        or using the Polars duration string language (see "Notes" section below).
+
+        To create a month-end date series, combine with :meth:`Expr.dt.month_end` (see
+        "Examples" section below).
+    closed : {'both', 'left', 'right', 'none'}
+        Define which sides of the range are closed (inclusive).
+    eager
+        Evaluate immediately and return a ``Series``.
+        If set to ``False`` (default), return an expression instead.
+    weekend
+        The days of the week that are considered weekends. Defaults to ("Sat", "Sun").
+    holidays
+        The holidays to exclude from the calculation. Defaults to None. This should
+        be a list of ``datetime.date`` s.
+
+    Returns
+    -------
+    Expr or Series
+        Column of data type :class:`Date`.
+
+    Examples
+    --------
+    >>> from datetime import date
+    >>> import polars as pl
+    >>> import polars_sgt
+    >>> pl.DataFrame(
+    ...     {
+    ...         "date": polars_sgt.date_range(
+    ...             date(2023, 1, 1), date(2023, 1, 10), "1bd", eager=True
+    ...         ),
+    ...     }
+    ... )
+    shape: (7, 1)
+    ┌────────────┐
+    │ date       │
+    │ ---        │
+    │ date       │
+    ╞════════════╡
+    │ 2023-01-02 │
+    │ 2023-01-03 │
+    │ 2023-01-04 │
+    │ 2023-01-05 │
+    │ 2023-01-06 │
+    │ 2023-01-09 │
+    │ 2023-01-10 │
+    └────────────┘
+
+    """
+    if weekend == ("Sat", "Sun"):
+        weekend_int = [6, 7]
+    else:
+        weekend_int = sorted({mapping[name] for name in weekend})
+    if holidays is None:
+        holidays = []
+
+    if not (isinstance(interval, str) and re.match(r"^-?\d+bd$", interval)):
+        msg = "Only intervals of the form 'nbd' (where n is an integer) are supported."
+        raise ValueError(msg)
+    interval = interval.replace("bd", "d")
+
+    expr = pl.date_range(
+        start,
+        end,
+        interval,
+        closed=closed,
+        eager=False,
+    )
+    expr = expr.filter(~expr.dt.date().is_in(holidays))
+    expr = expr.filter(~expr.dt.weekday().is_in(weekend_int))
+    if eager:
+        df = pl.select(expr)
+        return df[df.columns[0]]
+    return expr

polars_sgt/typing.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Union
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+if TYPE_CHECKING:
+    import polars as pl
+    from polars.type_aliases import PolarsDataType
+
+IntoExprColumn: TypeAlias = Union["pl.Expr", "pl.Series", str]
+
+__all__ = ["IntoExprColumn", "PolarsDataType"]

polars_sgt/utils.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import polars as pl
+
+if TYPE_CHECKING:
+    from polars_sgt.typing import IntoExprColumn, PolarsDataType
+
+
+def parse_into_expr(
+    expr: IntoExprColumn,
+    *,
+    str_as_lit: bool = False,
+    list_as_lit: bool = True,
+    dtype: PolarsDataType | None = None,
+) -> pl.Expr:
+    """
+    Parse a single input into an expression.
+
+    Parameters
+    ----------
+    expr
+        The input to be parsed as an expression.
+    str_as_lit
+        Interpret string input as a string literal. If set to `False` (default),
+        strings are parsed as column names.
+    list_as_lit
+        Interpret list input as a lit literal, If set to `False`,
+        lists are parsed as `Series` literals.
+    dtype
+        If the input is expected to resolve to a literal with a known dtype, pass
+        this to the `lit` constructor.
+
+    Returns
+    -------
+    polars.Expr
+
+    """
+    if isinstance(expr, pl.Expr):
+        pass
+    elif isinstance(expr, str) and not str_as_lit:
+        expr = pl.col(expr)
+    elif isinstance(expr, list) and not list_as_lit:
+        expr = pl.lit(pl.Series(expr), dtype=dtype)
+    else:
+        expr = pl.lit(expr, dtype=dtype)
+
+    return expr

polars_sgt-0.1.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: polars-sgt
+Version: 0.1.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Dist: maturin>=1.11.5
+Requires-Dist: polars>=1.36.1
+Requires-Dist: pytest>=8.4.2
+License-File: LICENSE
+Summary: Sequence Graph Transform (SGT) for Polars - Transform sequential data into weighted n-gram representations
+Author-email: Zedd <lytran14789@gmail.com>, Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Change Log, https://github.com/4ursmile/polars-sgt/releases
+Project-URL: Documentation, https://github.com/4ursmile/polars-sgt
+Project-URL: Issue Tracker, https://github.com/4ursmile/polars-sgt/issues
+Project-URL: Repository, https://github.com/4ursmile/polars-sgt
+
+# polars-sgt
+
+## Sequence Graph Transform for Polars
+
+
+
+[![PyPI version](https://badge.fury.io/py/polars-sgt.svg)](https://badge.fury.io/py/polars-sgt)
+
+Transform sequential data into powerful n-gram representations with [Polars](https://www.pola.rs/).
+
+**polars-sgt** brings Sequence Graph Transform (SGT) to Polars, enabling you to:
+- ✅ Transform sequences into weighted n-gram features
+- ✅ Capture temporal patterns with time-based weighting
+- ✅ Apply flexible normalization strategies (L1, L2, or none)
+- ✅ Handle datetime, date, duration, and numeric time columns
+- ✅ Blazingly fast, written in Rust
+- ✅ Compatible with Polars lazy evaluation and streaming
+
+## What is SGT?
+
+Sequence Graph Transform converts sequential data (like user clickstreams, sensor readings, or transaction histories) into weighted n-gram representations. It captures:
+
+- **Sequential patterns**: Unigrams, bigrams, trigrams, and higher-order n-grams
+- **Temporal dynamics**: Time-based weighting with multiple decay functions
+- **Normalized features**: L1/L2 normalization for comparable feature spaces
+
+Perfect for:
+- User behavior analysis
+- Time series feature engineering
+- Sequential pattern mining
+- Anomaly detection in sequences
+
+## Installation
+
+
+
+Then install `polars-sgt`:
+
+```console
+pip install polars-sgt
+```
+
+## Quick Start
+
+### Basic Example
+
+```python
+import polars as pl
+import polars_sgt as sgt
+
+# User clickstream data
+df = pl.DataFrame({
+    "user_id": [1, 1, 1, 2, 2, 2],
+    "action": ["login", "view_product", "purchase", "login", "view_product", "logout"],
+    "timestamp": [0, 10, 20, 0, 5, 15],
+})
+
+# Generate bigrams with exponential time decay
+result = df.select(
+    sgt.sgt_transform(
+        "user_id",
+        "action",
+        time_col="timestamp",
+        kappa=2,  # bigrams
+        time_penalty="exponential",
+        alpha=0.1,
+        mode="l1"  # L1 normalization
+    ).alias("sgt_features")
+)
+
+# Extract features
+features = result.select([
+    pl.col("sgt_features").struct.field("sequence_id"),
+    pl.col("sgt_features").struct.field("ngram_keys").alias("ngrams"),
+    pl.col("sgt_features").struct.field("ngram_values").alias("weights"),
+]).explode(["ngrams", "weights"])
+
+print(features)
+```
+
+### With DateTime Columns
+
+```python
+from datetime import datetime
+
+df = pl.DataFrame({
+    "session_id": ["A", "A", "A", "A"],
+    "event": ["start", "click", "scroll", "exit"],
+    "time": [
+        datetime(2024, 1, 1, 10, 0),
+        datetime(2024, 1, 1, 10, 5),
+        datetime(2024, 1, 1, 10, 7),
+        datetime(2024, 1, 1, 10, 15),
+    ],
+})
+
+result = df.select(
+    sgt.sgt_transform(
+        "session_id",
+        "event",
+        time_col="time",
+        deltatime="m",  # minutes
+        kappa=3,  # trigrams
+        time_penalty="inverse",
+    )
+)
+```
+
+### Lazy Evaluation & Streaming
+
+```python
+result = (
+    pl.scan_csv("large_sequences.csv")
+    .with_columns(pl.col("timestamp").str.to_datetime())
+    .select(
+        sgt.sgt_transform(
+            "user_id",
+            "action",
+            time_col="timestamp",
+            kappa=2,
+            deltatime="h",
+        )
+    )
+    .collect(streaming=True)
+)
+```
+
+## Parameters
+
+### Required
+- `sequence_id_col`: Column with sequence identifiers (groups)
+- `state_col`: Column with state/event values
+
+### Optional
+- `time_col`: Timestamp column (datetime, date, duration, or numeric)
+- `kappa`: Maximum n-gram size (default: 1)
+  - 1 = unigrams only
+  - 2 = unigrams + bigrams
+  - 3 = unigrams + bigrams + trigrams, etc.
+  
+- `time_penalty`: Time decay function (default: "inverse")
+  - `"inverse"`: weight = alpha / time_diff
+  - `"exponential"`: weight = exp(-alpha × time_diff)
+  - `"linear"`: weight = max(0, 1 - alpha × time_diff)
+  - `"power"`: weight = 1 / time_diff^beta
+  - `"none"`: No time penalty
+
+- `mode`: Normalization mode (default: "l1")
+  - `"l1"`: Sum of weights = 1
+  - `"l2"`: L2 norm = 1
+  - `"none"`: No normalization
+
+- `length_sensitive`: Apply length normalization (default: False)
+- `alpha`: Time penalty scale parameter (default: 1.0)
+- `beta`: Power parameter for "power" penalty (default: 2.0)
+- `deltatime`: Time unit for datetime columns
+  - `"s"`, `"m"`, `"h"`, `"d"`, `"w"`, `"month"`, `"q"`, `"y"`
+
+## Output
+
+Returns a Struct with three fields:
+- `sequence_id`: Original sequence identifier
+- `ngram_keys`: List of n-gram strings (e.g., "login -> view -> purchase")
+- `ngram_values`: List of corresponding weights
+
+## Additional DateTime Utilities
+
+While SGT is the primary focus, polars-sgt also includes helpful datetime utilities from the original polars-xdt:
+- Timezone conversions
+- Localized date formatting  
+- Julian date conversion
+- Month delta calculations
+
+See the [full API documentation](https://github.com/Zedd-L/polars-sgt) for details.
+
+## Author & Acknowledgments
+
+**Author:** Zedd (lytran14789@gmail.com)
+
+**Special Thanks:** This project is built upon [polars-xdt](https://github.com/MarcoGorelli/polars-xdt) 
+created by [Marco Gorelli](https://github.com/MarcoGorelli). We are grateful for his excellent foundation.
+
+## License
+
+MIT
+

polars_sgt-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+polars_sgt\.mypy.ini,sha256=5mJftXUSCrV-3kIF5PBb8zdS955xTJp0K373cqIs-KI,21
+polars_sgt\__init__.py,sha256=8Xs67DT-X1ehNxiawFMDvr3wx8oXkdSpavlmFf3j814,717
+polars_sgt\_internal.pyd,sha256=Vt1ztpOBU8Wggl7BDW1hYw5XigBfi0iq0DY9JHF3wgk,23472640
+polars_sgt\_internal.pyi,sha256=xq3DTJlvvVHWjbZ1EvMjKJBpN-UQO3z1Rulqaz2NN6w,18
+polars_sgt\functions.py,sha256=u5eoNwafTxkbFzU-o3RzyMca8oE2DPpXNaY2sfUd7Wg,31161
+polars_sgt\namespace.py,sha256=pSsy2oeHx6wo_DNbL9wmoi_5AhyuJAt-MBEZAVY04QY,588
+polars_sgt\py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+polars_sgt\ranges.py,sha256=Gd00LnGrer5vqNI3z9ocQkaoIUoZpDScGXm1xlGXEt4,4747
+polars_sgt\typing.py,sha256=ERDcKyZpgtrN4tzm-sXgLnufk-Kllo8WKloruFY12MM,426
+polars_sgt\utils.py,sha256=kQujAa3Ddpt3aEyvwIXqcNgD4tQKVJnalmh9vgvunqE,1285
+polars_sgt-0.1.0.dist-info\METADATA,sha256=slJnjv8Q3g0p7UGr632asDhZNVwr7pI57ym07AL1p_Q,6224
+polars_sgt-0.1.0.dist-info\WHEEL,sha256=OD0Is1kLHE07aD7XukSVDFU8ymUMI4Fdg0tKYWce3N0,95
+polars_sgt-0.1.0.dist-info\licenses\LICENSE,sha256=N2uLjQs8DWUxWQieXP8Hpq6Q1IXIUVJqZj8KKMe4jTA,1098
+polars_sgt-0.1.0.dist-info\RECORD,,

polars_sgt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.5)
+Root-Is-Purelib: false
+Tag: cp39-abi3-win_amd64

polars_sgt-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Marco Edward Gorelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.