dycw-utilities 0.112.9__py3-none-any.whl → 0.112.10__py3-none-any.whl

{dycw_utilities-0.112.9.dist-info → dycw_utilities-0.112.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.112.9
+Version: 0.112.10
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -24,7 +24,7 @@ Provides-Extra: zzz-test-altair
 Requires-Dist: altair<5.6,>=5.5.0; extra == 'zzz-test-altair'
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-altair'
 Requires-Dist: img2pdf<0.7,>=0.6.0; extra == 'zzz-test-altair'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-altair'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-altair'
 Requires-Dist: vl-convert-python<1.8,>=1.7.0; extra == 'zzz-test-altair'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-altair'
 Provides-Extra: zzz-test-astor
@@ -48,7 +48,7 @@ Provides-Extra: zzz-test-cvxpy
 Requires-Dist: cvxpy<1.7,>=1.6.5; extra == 'zzz-test-cvxpy'
 Provides-Extra: zzz-test-dataclasses
 Requires-Dist: orjson<3.11,>=3.10.15; extra == 'zzz-test-dataclasses'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-dataclasses'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-dataclasses'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-dataclasses'
 Provides-Extra: zzz-test-datetime
 Requires-Dist: tzlocal<5.4,>=5.3.1; extra == 'zzz-test-datetime'
@@ -70,7 +70,7 @@ Provides-Extra: zzz-test-getpass
 Provides-Extra: zzz-test-git
 Provides-Extra: zzz-test-hashlib
 Requires-Dist: orjson<3.11,>=3.10.15; extra == 'zzz-test-hashlib'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-hashlib'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-hashlib'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-hashlib'
 Provides-Extra: zzz-test-http
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-http'
@@ -92,12 +92,12 @@ Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-hypothesis'
 Provides-Extra: zzz-test-ipython
 Requires-Dist: ipython<9.1,>=9.0.1; extra == 'zzz-test-ipython'
 Provides-Extra: zzz-test-iterables
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-iterables'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-iterables'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-iterables'
 Provides-Extra: zzz-test-jupyter
 Requires-Dist: jupyterlab<4.3,>=4.2.0; extra == 'zzz-test-jupyter'
 Requires-Dist: pandas<2.3,>=2.2.2; extra == 'zzz-test-jupyter'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-jupyter'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-jupyter'
 Provides-Extra: zzz-test-logging
 Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-logging'
 Requires-Dist: coloredlogs<15.1,>=15.0.1; extra == 'zzz-test-logging'
@@ -121,13 +121,13 @@ Requires-Dist: more-itertools<10.8,>=10.7.0; extra == 'zzz-test-more-itertools'
 Provides-Extra: zzz-test-numpy
 Requires-Dist: numpy<2.3,>=2.2.5; extra == 'zzz-test-numpy'
 Provides-Extra: zzz-test-operator
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-operator'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-operator'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-operator'
 Provides-Extra: zzz-test-optuna
 Requires-Dist: optuna<4.4,>=4.3.0; extra == 'zzz-test-optuna'
 Provides-Extra: zzz-test-orjson
 Requires-Dist: orjson<3.11,>=3.10.15; extra == 'zzz-test-orjson'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-orjson'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-orjson'
 Requires-Dist: rich<14.1,>=14.0.0; extra == 'zzz-test-orjson'
 Requires-Dist: tzlocal<5.4,>=5.3.1; extra == 'zzz-test-orjson'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-orjson'
@@ -138,7 +138,7 @@ Requires-Dist: atomicwrites<1.5,>=1.4.1; extra == 'zzz-test-pickle'
 Provides-Extra: zzz-test-platform
 Provides-Extra: zzz-test-polars
 Requires-Dist: dacite<1.10,>=1.9.2; extra == 'zzz-test-polars'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-polars'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-polars'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-polars'
 Provides-Extra: zzz-test-pqdm
 Requires-Dist: pqdm<0.3,>=0.2.0; extra == 'zzz-test-pqdm'
@@ -164,7 +164,7 @@ Provides-Extra: zzz-test-random
 Provides-Extra: zzz-test-re
 Provides-Extra: zzz-test-redis
 Requires-Dist: orjson<3.11,>=3.10.15; extra == 'zzz-test-redis'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-redis'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-redis'
 Requires-Dist: redis<5.3,>=5.2.1; extra == 'zzz-test-redis'
 Requires-Dist: rich<14.1,>=14.0.0; extra == 'zzz-test-redis'
 Requires-Dist: tenacity<9.0,>=8.5.0; extra == 'zzz-test-redis'
@@ -192,7 +192,7 @@ Requires-Dist: aiosqlite<0.22,>=0.21.0; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: asyncpg<0.31,>=0.30.0; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: greenlet<3.3,>=3.2.0; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: nest-asyncio<1.7,>=1.6.0; extra == 'zzz-test-sqlalchemy-polars'
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-sqlalchemy-polars'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: sqlalchemy<2.1,>=2.0.40; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: tenacity<9.0,>=8.5.0; extra == 'zzz-test-sqlalchemy-polars'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-sqlalchemy-polars'
@@ -217,7 +217,7 @@ Requires-Dist: tzlocal<5.4,>=5.3.1; extra == 'zzz-test-traceback'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-traceback'
 Provides-Extra: zzz-test-types
 Provides-Extra: zzz-test-typing
-Requires-Dist: polars-lts-cpu<1.29,>=1.28.1; extra == 'zzz-test-typing'
+Requires-Dist: polars-lts-cpu<1.30,>=1.29.0; extra == 'zzz-test-typing'
 Requires-Dist: whenever<0.8,>=0.7.3; extra == 'zzz-test-typing'
 Provides-Extra: zzz-test-tzlocal
 Requires-Dist: tzlocal<5.4,>=5.3.1; extra == 'zzz-test-tzlocal'

{dycw_utilities-0.112.9.dist-info → dycw_utilities-0.112.10.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=4oIYPUfPGTr8vXSSPtcMMTgcanNRfFAjAkM3ufwN-Mg,60
+utilities/__init__.py,sha256=mALrkpjRtE0nW8tAmwclFaEZyShTCa75IjKVwftuFOc,61
 utilities/altair.py,sha256=Gpja-flOo-Db0PIPJLJsgzAlXWoKUjPU1qY-DQ829ek,9156
 utilities/astor.py,sha256=xuDUkjq0-b6fhtwjhbnebzbqQZAjMSHR1IIS5uOodVg,777
 utilities/asyncio.py,sha256=41oQUurWMvadFK5gFnaG21hMM0Vmfn2WS6OpC0R9mas,14757
@@ -36,7 +36,7 @@ utilities/math.py,sha256=TexfvLCI12d9Sw5_W4pKVBZ3nRr3zk2iPkcEU7xdEWU,26771
 utilities/memory_profiler.py,sha256=tf2C51P2lCujPGvRt2Rfc7VEw5LDXmVPCG3z_AvBmbU,962
 utilities/modules.py,sha256=iuvLluJya-hvl1Q25-Jk3dLgx2Es3ck4SjJiEkAlVTs,3195
 utilities/more_itertools.py,sha256=CPUxrMAcTwRxbzbhiqPKi3Xx9hxqI0t6gkWjutaibGk,5534
-utilities/numpy.py,sha256=cBgCBet8YfZP_rb4nkCJHZx9_03qPEinVENMk1dGVYQ,25683
+utilities/numpy.py,sha256=Xn23sA2ZbVNqwUYEgNJD3XBYH6IbCri_WkHSNhg3NkY,26122
 utilities/operator.py,sha256=0M2yZJ0PODH47ogFEnkGMBe_cfxwZR02T_92LZVZvHo,3715
 utilities/optuna.py,sha256=loyJGWTzljgdJaoLhP09PT8Jz6o_pwBOwehY33lHkhw,1923
 utilities/orjson.py,sha256=DBm2zPP04kcHpY3l1etL24ksNynu-R3duFyx3U-RjqQ,36948
@@ -46,7 +46,7 @@ utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=RWfcNVoNlW07RNdU47g_zuLZMKbtgfK4bE6G-9tVjY8,11024
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
 utilities/platform.py,sha256=NU7ycTvAXAG-fdYmDXaM1m4EOml2cGiaYwaUzfzSqyU,1767
-utilities/polars.py,sha256=q8a2hTX9tyPxtxUarIm2BxlnckIwF1RCpcJz03OoIoY,58458
+utilities/polars.py,sha256=ZdhGu9qMlgbwfdYYDEV3Pk3kfJr1V5FSolfCWHI3Nxc,63283
 utilities/polars_ols.py,sha256=efhXf0gjrHUpQrvS6a7g8yJQJWf_ATKtJnqqF2inCOU,5680
 utilities/pqdm.py,sha256=foRytQybmOQ05pjt5LF7ANyzrIa--4ScDE3T2wd31a4,3118
 utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -87,7 +87,7 @@ utilities/warnings.py,sha256=un1LvHv70PU-LLv8RxPVmugTzDJkkGXRMZTE2-fTQHw,1771
 utilities/whenever.py,sha256=iLRP_-8CZtBpHKbGZGu-kjSMg1ZubJ-VSmgSy7Eudxw,17787
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-Xm57PMMwDTYpxJdkiJG13wnbwK--I7XItBh5WVhD-o,1874
-dycw_utilities-0.112.9.dist-info/METADATA,sha256=w5dmojTlh4MG3_sA2rTFFQLP-BclPCLPCQ98Rf4RF-o,13004
-dycw_utilities-0.112.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.112.9.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.112.9.dist-info/RECORD,,
+dycw_utilities-0.112.10.dist-info/METADATA,sha256=HXZIn_uHvb-xc5-RuCEn_T8pPkJ58gnElO7ootr182o,13005
+dycw_utilities-0.112.10.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.112.10.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.112.10.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.112.9"
+__version__ = "0.112.10"

utilities/numpy.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
 from functools import partial, reduce
 from itertools import repeat
-from typing import TYPE_CHECKING, Any, overload, override
+from typing import TYPE_CHECKING, Any, SupportsIndex, overload, override
 
 import numpy as np
 from numpy import (
@@ -46,6 +47,9 @@ if TYPE_CHECKING:
     from utilities.types import MaybeIterable
 
 
+type ShapeLike = SupportsIndex | Sequence[SupportsIndex]
+
+
 ##
 
 
@@ -136,6 +140,19 @@ class AsIntError(Exception): ...
 ##
 
 
+def bernoulli(
+    *, true: float = 0.5, seed: int | None = None, size: ShapeLike = ()
+) -> NDArrayB:
+    """Return a set of Bernoulli random variates."""
+    from numpy.random import default_rng
+
+    rng = default_rng(seed=seed)
+    return rng.binomial(1, true, size=size).astype(bool)
+
+
+##
+
+
 def boxcar(
     array: NDArrayF,
     /,
@@ -980,11 +997,13 @@ __all__ = [
     "NDArrayF",
     "NDArrayI",
     "NDArrayO",
+    "ShapeLike",
     "ShiftError",
     "SigmoidError",
     "adjust_frequencies",
     "array_indexer",
     "as_int",
+    "bernoulli",
     "boxcar",
     "datetime64D",
     "datetime64M",

utilities/polars.py

@@ -39,17 +39,20 @@ from polars import (
     Series,
     String,
     Struct,
+    UInt32,
     all_horizontal,
     col,
     concat,
     int_range,
     lit,
     struct,
+    sum_horizontal,
     when,
 )
 from polars.datatypes import DataType, DataTypeClass
 from polars.exceptions import (
     ColumnNotFoundError,
+    NoRowsReturnedError,
     OutOfBoundsError,
     PolarsInefficientMapWarning,
 )
@@ -337,6 +340,102 @@ def are_frames_equal(
 ##
 
 
+def bernoulli(
+    obj: int | Series | DataFrame,
+    /,
+    *,
+    true: float = 0.5,
+    seed: int | None = None,
+    name: str | None = None,
+) -> Series:
+    """Construct a series of Bernoulli-random variables."""
+    match obj:
+        case int() as height:
+            import utilities.numpy
+
+            values = utilities.numpy.bernoulli(true=true, seed=seed, size=height)
+            return Series(name=name, values=values)
+        case Series() as series:
+            return bernoulli(series.len(), true=true, seed=seed, name=name)
+        case DataFrame() as df:
+            return bernoulli(df.height, true=true, seed=seed, name=name)
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
+def boolean_value_counts(
+    obj: Series | DataFrame, /, *exprs: IntoExprColumn, **named_exprs: IntoExprColumn
+) -> DataFrame:
+    """Conduct a set of boolean value counts."""
+    match obj:
+        case Series() as series:
+            return boolean_value_counts(series.to_frame(), *exprs, **named_exprs)
+        case DataFrame() as df:
+            all_exprs = ensure_expr_or_series_many(*exprs, **named_exprs)
+            rows = [_boolean_value_counts_one(df, expr) for expr in all_exprs]
+            true, false, null = [col(c) for c in ["true", "false", "null"]]
+            total = sum_horizontal(true, false, null).alias("total")
+            return DataFrame(
+                rows,
+                schema={
+                    "name": String,
+                    "true": UInt32,
+                    "false": UInt32,
+                    "null": UInt32,
+                },
+                orient="row",
+            ).with_columns(
+                total,
+                (true / total).alias("true (%)"),
+                (false / total).alias("false (%)"),
+                (null / total).alias("null (%)"),
+            )
+        case _ as never:
+            assert_never(never)
+
+
+def _boolean_value_counts_one(
+    df: DataFrame, expr: IntoExprColumn, /
+) -> Mapping[str, Any]:
+    name = get_expr_name(df, expr)
+    sr = df.select(expr)[name]
+    if not isinstance(sr.dtype, Boolean):
+        raise BooleanValueCountsError(name=name, dtype=sr.dtype)
+    counts = sr.value_counts()
+    truth = col(name)
+    try:
+        true = counts.row(by_predicate=truth.is_not_null() & truth, named=True)["count"]
+    except NoRowsReturnedError:
+        true = 0
+    try:
+        false = counts.row(by_predicate=(truth.is_not_null() & ~truth), named=True)[
+            "count"
+        ]
+    except NoRowsReturnedError:
+        false = 0
+    try:
+        null = counts.row(by_predicate=truth.is_null(), named=True)["count"]
+    except NoRowsReturnedError:
+        null = 0
+    return {"name": name, "true": true, "false": false, "null": null}
+
+
+@dataclass(kw_only=True, slots=True)
+class BooleanValueCountsError(Exception):
+    name: str
+    dtype: DataType
+
+    @override
+    def __str__(self) -> str:
+        return f"Column {self.name!r} must be Boolean; got {self.dtype!r}"
+
+
+##
+
+
 @overload
 def ceil_datetime(column: ExprLike, every: ExprLike, /) -> Expr: ...
 @overload
@@ -637,6 +736,54 @@ class _CheckPolarsDataFrameWidthError(CheckPolarsDataFrameError):
 ##
 
 
+def choice(
+    obj: int | Series | DataFrame,
+    elements: Iterable[Any],
+    /,
+    *,
+    replace: bool = True,
+    p: Iterable[float] | None = None,
+    seed: int | None = None,
+    name: str | None = None,
+    dtype: PolarsDataType = Float64,
+) -> Series:
+    """Construct a series of random samples."""
+    match obj:
+        case int() as height:
+            from numpy.random import default_rng
+
+            rng = default_rng(seed=seed)
+            elements = list(elements)
+            p = None if p is None else list(p)
+            values = rng.choice(elements, size=height, replace=replace, p=p)
+            return Series(name=name, values=values.tolist(), dtype=dtype)
+        case Series() as series:
+            return choice(
+                series.len(),
+                elements,
+                replace=replace,
+                p=p,
+                seed=seed,
+                name=name,
+                dtype=dtype,
+            )
+        case DataFrame() as df:
+            return choice(
+                df.height,
+                elements,
+                replace=replace,
+                p=p,
+                seed=seed,
+                name=name,
+                dtype=dtype,
+            )
+        case _ as never:
+            assert_never(never)
+
+
+##
+
+
 def collect_series(expr: Expr, /) -> Series:
     """Collect a column expression into a Series."""
     data = DataFrame().with_columns(expr)
@@ -1053,6 +1200,18 @@ def ensure_expr_or_series(column: IntoExprColumn, /) -> Expr | Series:
 ##
 
 
+def ensure_expr_or_series_many(
+    *columns: IntoExprColumn, **named_columns: IntoExprColumn
+) -> Sequence[Expr | Series]:
+    """Ensure a set of column expressions and/or Series are returned."""
+    args = map(ensure_expr_or_series, columns)
+    kwargs = (ensure_expr_or_series(v).alias(k) for k, v in named_columns.items())
+    return list(chain(args, kwargs))
+
+
+##
+
+
 @overload
 def finite_ewm_mean(
     column: ExprLike,
@@ -1227,7 +1386,7 @@ class _GetDataTypeOrSeriesTimeZoneNotZonedError(GetDataTypeOrSeriesTimeZoneError
 ##
 
 
-def get_expr_name(obj: Series | DataFrame, expr: Expr, /) -> str:
+def get_expr_name(obj: Series | DataFrame, expr: IntoExprColumn, /) -> str:
     """Get the name of an expression."""
     match obj:
         case Series() as series:
@@ -1948,6 +2107,7 @@ def zoned_datetime(
 
 
 __all__ = [
+    "BooleanValueCountsError",
     "CheckPolarsDataFrameError",
     "ColumnsToDictError",
     "DataClassToDataFrameError",
@@ -1971,8 +2131,11 @@ __all__ = [
     "adjust_frequencies",
     "append_dataclass",
     "are_frames_equal",
+    "bernoulli",
+    "boolean_value_counts",
     "ceil_datetime",
     "check_polars_dataframe",
+    "choice",
     "collect_series",
     "columns_to_dict",
     "concat_series",
@@ -1983,6 +2146,7 @@ __all__ = [
     "drop_null_struct_series",
     "ensure_data_type",
     "ensure_expr_or_series",
+    "ensure_expr_or_series_many",
     "finite_ewm_mean",
     "floor_datetime",
     "get_data_type_or_series_time_zone",