onekit 1.1.0__tar.gz → 1.2.0__tar.gz

{onekit-1.1.0 → onekit-1.2.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.1
 Name: onekit
-Version: 1.1.0
+Version: 1.2.0
 Summary: All-in-One Python Kit.
 Home-page: https://github.com/estripling/onekit
 License: BSD 3-Clause
 Keywords: onekit
 Author: Eugen Stripling
 Author-email: estripling042@gmail.com
-Requires-Python: >=3.8.1,<4.0
+Requires-Python: >=3.8.1
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.8
+Requires-Dist: pytz (>=2024.1,<2025.0)
 Requires-Dist: toolz (>=0.12.0,<0.13.0)
 Project-URL: Documentation, https://onekit.readthedocs.io/en/stable/
 Project-URL: Repository, https://github.com/estripling/onekit

{onekit-1.1.0 → onekit-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "onekit"
-version = "1.1.0"
+version = "1.2.0"
 description = "All-in-One Python Kit."
 authors = ["Eugen Stripling <estripling042@gmail.com>"]
 license = "BSD 3-Clause"
@@ -18,14 +18,15 @@ classifiers = [
 ]
 
 [tool.poetry.dependencies]
-python = ">=3.8.1,<4.0"
+python = ">=3.8.1"
 toolz = "^0.12.0"
+pytz = "^2024.1"
 
 [tool.poetry.group.precommit.dependencies]
 autoflake = "^2.2.1"
 black = {extras = ["jupyter"], version = "^23.11.0"}
 isort = "^5.12.0"
-flake8 = "^6.1.0"
+flake8 = ">=5.0.4"
 pre-commit = "^3.5.0"
 pre-commit-hooks = "^4.5.0"
 
@@ -33,6 +34,7 @@ pre-commit-hooks = "^4.5.0"
 pytest = "^7.4.3"
 pytest-cov = "^4.1.0"
 pytest-skip-slow = "^0.0.5"
+time-machine = "^2.13.0"
 
 [tool.poetry.group.docs.dependencies]
 furo = "^2023.9.10"
@@ -41,7 +43,6 @@ myst-parser = "^2.0.0"
 nbsphinx = "^0.9.3"
 sphinx-autoapi = "^3.0.0"
 sphinx-copybutton = "^0.5.2"
-time-machine = "^2.13.0"
 
 [tool.poetry.group.packaging.dependencies]
 python-semantic-release = "^8.3.0"
@@ -73,7 +74,10 @@ markers = [
     "slow: marks tests as slow (deselect with '-m \"not slow\"')",
     "serial",
 ]
-filterwarnings = ["ignore::DeprecationWarning"]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::RuntimeWarning",
+]
 
 [tool.semantic_release]
 branch = "main"

{onekit-1.1.0 → onekit-1.2.0}/src/onekit/mathkit.py

@@ -1,3 +1,4 @@
+import math
 from typing import (
     Generator,
     Union,
@@ -7,10 +8,12 @@ import toolz
 
 __all__ = (
     "collatz",
+    "digitscale",
     "fibonacci",
     "isdivisible",
     "iseven",
     "isodd",
+    "sign",
 )
 
 
@@ -79,6 +82,49 @@ def collatz(n: int, /) -> Generator:
         n = n // 2 if iseven(n) else 3 * n + 1
 
 
+def digitscale(x: Union[int, float], /) -> float:
+    """Scale :math:`x` such that its mapped integer part is its number of digits.
+
+    Given a number :math:`x \\in \\mathbb{R}`, the following function
+    :math:`f \\colon \\mathbb{R} \\rightarrow \\mathbb{R}_{\\ge 0}` scales it such that
+    its mapped integer part :math:`\\lfloor f(x) \\rfloor \\in \\mathbb{N}_{0}`
+    is the number of digits in :math:`[x]`:
+
+    .. math::
+
+        f(x) =
+        \\begin{cases}
+            1 + \\log_{10}|x| & \\text{ if } |x| \\ge 0.1 \\\\[6pt]
+            0 & \\text{ otherwise }
+        \\end{cases}
+
+    Notes
+    -----
+    - :math:`\\lfloor \\cdot \\rfloor`: floor function
+    - :math:`\\left[ \\, \\cdot \\, \\right]`: truncation function
+    - For any positive integer :math:`n`, the number of digits in :math:`n` is
+      :math:`1 + \\lfloor \\log_{10} n \\rfloor`
+
+    See Also
+    --------
+    onekit.numpykit.digitscale : NumPy version
+    onekit.sparkkit.with_digitscale : PySpark version
+
+    Examples
+    --------
+    >>> import onekit.mathkit as mk
+    >>> list(map(mk.digitscale, [0.1, 1, 10, 100, 1_000, 10_000, 100_000, 1_000_000]))
+    [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0]
+
+    >>> list(map(mk.digitscale, [0.2, 2, 20, 200]))
+    [0.30102999566398125, 1.3010299956639813, 2.3010299956639813, 3.3010299956639813]
+
+    >>> list(map(mk.digitscale, [-0.5, -5, -50, -500]))
+    [0.6989700043360187, 1.6989700043360187, 2.6989700043360187, 3.6989700043360187]
+    """
+    return 1 + math.log10(abs(x)) if abs(x) >= 0.1 else 0.0
+
+
 def fibonacci() -> Generator:
     """Generate the Fibonacci sequence.
 
@@ -182,3 +228,30 @@ def isodd(x: Union[int, float], /) -> bool:
     False
     """
     return toolz.complement(iseven)(x)
+
+
+def sign(x: Union[int, float], /) -> int:
+    """Sign function.
+
+    .. math::
+
+        f(x) =
+        \\begin{cases}
+            -1 & \\text{ if } x < 0 \\\\[6pt]
+            0 & \\text{ if } x = 0 \\\\[6pt]
+            1 & \\text{ if } x > 0
+        \\end{cases}
+
+    Examples
+    --------
+    >>> import onekit.mathkit as mk
+    >>> mk.sign(0)
+    0
+
+    >>> mk.sign(3.14)
+    1
+
+    >>> mk.sign(-10)
+    -1
+    """
+    return int(0 if math.isclose(x, 0) else math.copysign(1, x))

{onekit-1.1.0 → onekit-1.2.0}/src/onekit/numpykit.py

@@ -1,8 +1,11 @@
 import numpy as np
 import numpy.typing as npt
 
+import onekit.mathkit as mk
+
 __all__ = (
     "check_vector",
+    "digitscale",
     "stderr",
 )
 
@@ -49,6 +52,23 @@ def check_vector(x: ArrayLike, /, *, n_min: int = 1, n_max: int = np.inf) -> Vec
     return x
 
 
+def digitscale(x: ArrayLike, /) -> np.ndarray:
+    """NumPy version of digitscale.
+
+    See Also
+    --------
+    onekit.mathkit.digitscale : Python version
+    onekit.sparkkit.with_digitscale : PySpark version
+
+    Examples
+    --------
+    >>> import onekit.numpykit as npk
+    >>> npk.digitscale([0.1, 1, 10, 100, 1_000, 10_000, 100_000, 1_000_000])
+    array([0., 1., 2., 3., 4., 5., 6., 7.])
+    """
+    return np.vectorize(mk.digitscale, otypes=[float])(x)
+
+
 def stderr(x: ArrayLike, /) -> float:
     """Compute standard error of the mean.
 

{onekit-1.1.0 → onekit-1.2.0}/src/onekit/sparkkit.py

@@ -1,5 +1,6 @@
 import datetime as dt
 import functools
+import math
 import os
 from typing import (
     Callable,
@@ -49,6 +50,7 @@ __all__ = (
     "union",
     "with_date_diff_ago",
     "with_date_diff_ahead",
+    "with_digitscale",
     "with_endofweek_date",
     "with_increasing_id",
     "with_index",
@@ -667,7 +669,11 @@ def date_range(
     )
 
 
-def filter_date(date_col: str, d0: Union[str, dt.date], n: int) -> SparkDFTransformFunc:
+def filter_date(
+    date_col: str,
+    d0: Union[str, dt.date],
+    n: Union[int, float],
+) -> SparkDFTransformFunc:
     """Returns dataframe with rows such that date is in :math:`(d_{-n}, d_{0}]`.
 
     Notes
@@ -675,6 +681,7 @@ def filter_date(date_col: str, d0: Union[str, dt.date], n: int) -> SparkDFTransf
     - :math:`d_{0}`: reference date (inclusive)
     - :math:`d_{-n} < d_{0}`: relative date (exclusive)
     - :math:`n > 0`: number of dates from :math:`d_{-n}` to :math:`d_{0}`
+    - If `n=float("inf")`, returned dates are in :math:`(d_{-\\infty}, d_{0}]`
 
     Examples
     --------
@@ -702,10 +709,30 @@ def filter_date(date_col: str, d0: Union[str, dt.date], n: int) -> SparkDFTransf
     |2024-01-07|
     +----------+
     <BLANKLINE>
+
+    >>> df.transform(sk.filter_date("d", d0="2024-01-07", n=float("inf"))).show()
+    +----------+
+    |         d|
+    +----------+
+    |2024-01-01|
+    |2024-01-02|
+    |2024-01-03|
+    |2024-01-04|
+    |2024-01-05|
+    |2024-01-06|
+    |2024-01-07|
+    +----------+
+    <BLANKLINE>
     """
-    if not isinstance(n, int) or n < 1:
+    if not isinstance(n, (int, float)):
+        raise TypeError(f"{type(n)=} - must be an int or float")
+
+    if isinstance(n, int) and n < 1:
         raise ValueError(f"{n=} - must be a positive integer")
 
+    if isinstance(n, float) and not math.isinf(n):
+        raise ValueError(f'{n=} - only valid float value: float("inf")')
+
     def inner(df: SparkDF, /) -> SparkDF:
         date_diff_ago = "_date_diff_ago_"
         return (
@@ -1118,6 +1145,59 @@ def with_date_diff_ahead(
     return inner
 
 
+def with_digitscale(num_col: str, new_col: str) -> SparkDFTransformFunc:
+    """PySpark version of digitscale.
+
+    See Also
+    --------
+    onekit.mathkit.digitscale : Python version
+    onekit.numpykit.digitscale : NumPy version
+
+    Examples
+    --------
+    >>> from pyspark.sql import SparkSession
+    >>> import onekit.sparkkit as sk
+    >>> spark = SparkSession.builder.getOrCreate()
+    >>> df = spark.createDataFrame(
+    ...     [
+    ...         dict(x=0.1),
+    ...         dict(x=1.0),
+    ...         dict(x=10.0),
+    ...         dict(x=100.0),
+    ...         dict(x=1_000.0),
+    ...         dict(x=10_000.0),
+    ...         dict(x=100_000.0),
+    ...         dict(x=1_000_000.0),
+    ...         dict(x=None),
+    ...     ],
+    ... )
+    >>> df.transform(sk.with_digitscale("x", "fx")).show()
+    +---------+----+
+    |        x|  fx|
+    +---------+----+
+    |      0.1| 0.0|
+    |      1.0| 1.0|
+    |     10.0| 2.0|
+    |    100.0| 3.0|
+    |   1000.0| 4.0|
+    |  10000.0| 5.0|
+    | 100000.0| 6.0|
+    |1000000.0| 7.0|
+    |     null|null|
+    +---------+----+
+    <BLANKLINE>
+    """
+
+    def inner(df: SparkDF, /) -> SparkDF:
+        x = F.abs(num_col)
+        return df.withColumn(
+            new_col,
+            F.when(x.isNull(), None).when(x >= 0.1, 1 + F.log10(x)).otherwise(0.0),
+        )
+
+    return inner
+
+
 def with_endofweek_date(
     date_col: str,
     new_col: str,