dycw-utilities 0.109.17__py3-none-any.whl → 0.109.19__py3-none-any.whl

{dycw_utilities-0.109.17.dist-info → dycw_utilities-0.109.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.109.17
+Version: 0.109.19
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.109.17.dist-info → dycw_utilities-0.109.19.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=9W0BorEWmH8eCgNBXgx9zWKa3BNPPP1rlZfrx6qGCio,61
+utilities/__init__.py,sha256=NU7I4AynUyg4F6Vu4XytgM7aO4TDKxvPbBFKo638x30,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=SnhsRHRUS1po_acejrINauihGQpPvVsp8RDNCei1OLQ,3173
 utilities/more_itertools.py,sha256=CPUxrMAcTwRxbzbhiqPKi3Xx9hxqI0t6gkWjutaibGk,5534
-utilities/numpy.py,sha256=XMOaauVbssv_yrS1FdSnPExht3G4P8nAALmQsqHwp7w,25143
+utilities/numpy.py,sha256=cBgCBet8YfZP_rb4nkCJHZx9_03qPEinVENMk1dGVYQ,25683
 utilities/operator.py,sha256=0M2yZJ0PODH47ogFEnkGMBe_cfxwZR02T_92LZVZvHo,3715
 utilities/optuna.py,sha256=loyJGWTzljgdJaoLhP09PT8Jz6o_pwBOwehY33lHkhw,1923
 utilities/orjson.py,sha256=Wj5pzG_VdgoAy14a7Luhem-BgYrRtRFvvl_POiszRd0,36930
@@ -46,8 +46,8 @@ utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=ikHXsWtDLr553cfH6p9mMaiCnIAP69B7q84ckWV3HaA,10884
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
 utilities/platform.py,sha256=NU7ycTvAXAG-fdYmDXaM1m4EOml2cGiaYwaUzfzSqyU,1767
-utilities/polars.py,sha256=aOQNVyV04qYZjg7Exi6zYERhSQoCMzBP74oufxqANFY,52167
-utilities/polars_ols.py,sha256=Uc9V5kvlWZ5cU93lKZ-cfAKdVFFw81tqwLW9PxtUvMs,5618
+utilities/polars.py,sha256=UFrD7smyBROlIBaLD6tUFKGAPtwLfyHPHp6dJI9i-kQ,54961
+utilities/polars_ols.py,sha256=efhXf0gjrHUpQrvS6a7g8yJQJWf_ATKtJnqqF2inCOU,5680
 utilities/pqdm.py,sha256=foRytQybmOQ05pjt5LF7ANyzrIa--4ScDE3T2wd31a4,3118
 utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 utilities/pydantic.py,sha256=f6qtR5mO2YMuyvNmbaEj5YeD9eGA4YYfb7Bjzh9jUs0,1845
@@ -86,7 +86,7 @@ utilities/warnings.py,sha256=yUgjnmkCRf6QhdyAXzl7u0qQFejhQG3PrjoSwxpbHrs,1819
 utilities/whenever.py,sha256=TjoTAJ1R27-rKXiXzdE4GzPidmYqm0W58XydDXp-QZM,17786
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-DQz5a0Ikw9jfSZtL0BEQkXOMC9yGn_xiJYNCLMiqEc,1989
-dycw_utilities-0.109.17.dist-info/METADATA,sha256=9BOdlf6JtDA2hK4ElsW-HsjxWLvub9HUqc1ds9r2CkY,13005
-dycw_utilities-0.109.17.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.109.17.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.109.17.dist-info/RECORD,,
+dycw_utilities-0.109.19.dist-info/METADATA,sha256=nYNr6kZIYFI-2yrn7iwBAs_Axo9Zqi5-bKBZpNBc1Q0,13005
+dycw_utilities-0.109.19.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.109.19.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.109.19.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.109.17"
+__version__ = "0.109.19"

utilities/numpy.py

@@ -16,11 +16,10 @@ from numpy import (
     errstate,
     exp,
     flatnonzero,
-    float64,
     floating,
     full_like,
     inf,
-    int64,
+    integer,
     isclose,
     isfinite,
     isinf,
@@ -39,11 +38,13 @@ from numpy.linalg import det, eig
 from numpy.random import default_rng
 from numpy.typing import NDArray
 
-from utilities.iterables import is_iterable_not_str
+from utilities.iterables import always_iterable, is_iterable_not_str
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable
 
+    from utilities.types import MaybeIterable
+
 
 ##
 
@@ -89,8 +90,9 @@ timedelta64as = dtype("timedelta64[as]")
 
 NDArrayA = NDArray[Any]
 NDArrayB = NDArray[bool_]
-NDArrayF = NDArray[float64]
-NDArrayI = NDArray[int64]
+NDArrayC128 = NDArray[complex128]
+NDArrayF = NDArray[floating[Any]]
+NDArrayI = NDArray[integer[Any]]
 NDArrayO = NDArray[object_]
 
 
@@ -135,7 +137,7 @@ class AsIntError(Exception): ...
 
 
 def boxcar(
-    array: NDArray[floating[Any]],
+    array: NDArrayF,
     /,
     *,
     loc_low: float = -1.0,
@@ -144,7 +146,7 @@ def boxcar(
     slope_high: float = 1.0,
     rtol: float | None = None,
     atol: float | None = None,
-) -> NDArray[floating[Any]]:
+) -> NDArrayF:
     """Construct a boxcar function."""
     if not is_at_most(loc_low, loc_high, rtol=rtol, atol=atol):
         raise _BoxCarLocationsError(low=loc_low, high=loc_high)
@@ -224,28 +226,43 @@ def fillna(array: NDArrayF, /, *, value: float = 0.0) -> NDArrayF:
 ##
 
 
-def filter_frequencies(
+def adjust_frequencies(
     array: NDArrayF,
     /,
-    *filters: Callable[[NDArray[floating[Any]]], NDArrayB],
+    *,
+    filters: MaybeIterable[Callable[[NDArrayF], NDArrayB]] | None = None,
+    weights: MaybeIterable[Callable[[NDArrayF], NDArrayF]] | None = None,
     d: int = 1,
 ) -> NDArrayF:
-    """Filter an array by the frequencies of its FFT."""
+    """Adjust an array via its FFT frequencies."""
     (n,) = array.shape
-    fft_vals = fft(array)
+    amplitudes = fft(array)
     freqs = fftfreq(n, d=d)
-    reduced = reduce(partial(_filter_frequencies_one, freqs=freqs), filters, fft_vals)
-    return ifft(reduced).real
+    if filters is not None:
+        amplitudes = reduce(
+            partial(_adjust_frequencies_filter_one, freqs=freqs),
+            always_iterable(filters),
+            amplitudes,
+        )
+    if weights is not None:
+        amplitudes = reduce(
+            partial(_adjust_frequencies_weight_one, freqs=freqs),
+            always_iterable(weights),
+            amplitudes,
+        )
+    return ifft(amplitudes).real
+
+
+def _adjust_frequencies_filter_one(
+    acc: NDArrayC128, el: Callable[[NDArrayF], NDArrayB], /, *, freqs: NDArrayF
+) -> NDArrayC128:
+    return where(el(freqs), acc, 0.0)
 
 
-def _filter_frequencies_one(
-    acc: NDArray[complex128],
-    el: Callable[[NDArray[floating[Any]]], NDArrayB],
-    /,
-    *,
-    freqs: NDArray[floating[Any]],
-) -> NDArray[complex128]:
-    return where(el(freqs), acc, 0.0)
+def _adjust_frequencies_weight_one(
+    acc: NDArrayC128, el: Callable[[NDArrayF], NDArrayF], /, *, freqs: NDArrayF
+) -> NDArrayC128:
+    return acc * el(freqs)
 
 
 ##
@@ -284,12 +301,12 @@ class FlatN0MultipleError(FlatN0Error):
 ##
 
 
-def get_frequency_spectrum(array: NDArrayF, /, *, d: int = 1) -> NDArray[floating[Any]]:
+def get_frequency_spectrum(array: NDArrayF, /, *, d: int = 1) -> NDArrayF:
     """Get the frequency spectrum."""
     (n,) = array.shape
-    fft_vals = fft(array)
+    amplitudes = fft(array)
     freqs = fftfreq(n, d=d)
-    amplitudes = np.abs(fft_vals)
+    amplitudes = np.abs(amplitudes)
     data = np.hstack([freqs.reshape(-1, 1), amplitudes.reshape(-1, 1)])
     return data[argsort(data[:, 0])]
 
@@ -908,14 +925,14 @@ def shift_bool(
 
 
 def sigmoid(
-    array: NDArray[floating[Any]],
+    array: NDArrayF,
     /,
     *,
     loc: float = 0.0,
     slope: float = 1.0,
     rtol: float | None = None,
     atol: float | None = None,
-) -> NDArray[floating[Any]]:
+) -> NDArrayF:
     """Construct a sigmoid function."""
     if is_zero(slope, rtol=rtol, atol=atol):
         raise SigmoidError
@@ -965,6 +982,7 @@ __all__ = [
     "NDArrayO",
     "ShiftError",
     "SigmoidError",
+    "adjust_frequencies",
     "array_indexer",
     "as_int",
     "boxcar",
@@ -983,7 +1001,6 @@ __all__ = [
     "datetime64us",
     "discretize",
     "fillna",
-    "filter_frequencies",
     "flatn0",
     "get_frequency_spectrum",
     "has_dtype",

utilities/polars.py

@@ -115,10 +115,12 @@ if TYPE_CHECKING:
         JoinStrategy,  # pyright: ignore[reportPrivateImportUsage]
         JoinValidation,  # pyright: ignore[reportPrivateImportUsage]
         PolarsDataType,  # pyright: ignore[reportPrivateImportUsage]
+        RollingInterpolationMethod,  # pyright: ignore[reportPrivateImportUsage]
         SchemaDict,  # pyright: ignore[reportPrivateImportUsage]
         TimeUnit,  # pyright: ignore[reportPrivateImportUsage]
     )
 
+    from utilities.numpy import NDArrayB, NDArrayF
     from utilities.types import (
         Dataclass,
         MaybeIterable,
@@ -141,6 +143,27 @@ _FINITE_EWM_MIN_WEIGHT = 0.9999
 ##
 
 
+def adjust_frequencies(
+    series: Series,
+    /,
+    *,
+    filters: MaybeIterable[Callable[[NDArrayF], NDArrayB]] | None = None,
+    weights: MaybeIterable[Callable[[NDArrayF], NDArrayF]] | None = None,
+    d: int = 1,
+) -> Series:
+    """Adjust a Series via its FFT frequencies."""
+    import utilities.numpy
+
+    array = series.to_numpy()
+    adjusted = utilities.numpy.adjust_frequencies(
+        array, filters=filters, weights=weights, d=d
+    )
+    return Series(name=series.name, values=adjusted, dtype=Float64)
+
+
+##
+
+
 def append_dataclass(df: DataFrame, obj: Dataclass, /) -> DataFrame:
     """Append a dataclass object to a DataFrame."""
     non_null_fields = {k: v for k, v in asdict(obj).items() if v is not None}
@@ -658,6 +681,73 @@ def _cross_or_touch(
 ##
 
 
+@overload
+def cross_rolling_quantile(
+    expr: ExprLike,
+    up_or_down: Literal["up", "down"],
+    quantile: float,
+    /,
+    *,
+    interpolation: RollingInterpolationMethod = "nearest",
+    window_size: int = 2,
+    weights: list[float] | None = None,
+    min_samples: int | None = None,
+    center: bool = False,
+) -> Expr: ...
+@overload
+def cross_rolling_quantile(
+    expr: Series,
+    up_or_down: Literal["up", "down"],
+    quantile: float,
+    /,
+    *,
+    interpolation: RollingInterpolationMethod = "nearest",
+    window_size: int = 2,
+    weights: list[float] | None = None,
+    min_samples: int | None = None,
+    center: bool = False,
+) -> Series: ...
+@overload
+def cross_rolling_quantile(
+    expr: IntoExprColumn,
+    up_or_down: Literal["up", "down"],
+    quantile: float,
+    /,
+    *,
+    interpolation: RollingInterpolationMethod = "nearest",
+    window_size: int = 2,
+    weights: list[float] | None = None,
+    min_samples: int | None = None,
+    center: bool = False,
+) -> Expr | Series: ...
+def cross_rolling_quantile(
+    expr: IntoExprColumn,
+    up_or_down: Literal["up", "down"],
+    quantile: float,
+    /,
+    *,
+    interpolation: RollingInterpolationMethod = "nearest",
+    window_size: int = 2,
+    weights: list[float] | None = None,
+    min_samples: int | None = None,
+    center: bool = False,
+) -> Expr | Series:
+    """Compute when a column crosses its rolling quantile."""
+    expr = ensure_expr_or_series(expr)
+    rolling = expr.rolling_quantile(
+        quantile,
+        interpolation=interpolation,
+        window_size=window_size,
+        weights=weights,
+        min_samples=min_samples,
+        center=center,
+    )
+    return cross(expr, up_or_down, rolling)
+
+
+##
+
+
 def dataclass_to_dataframe(
     objs: MaybeIterable[Dataclass],
     /,
@@ -1027,6 +1117,20 @@ class _GetDataTypeOrSeriesTimeZoneNotZonedError(GetDataTypeOrSeriesTimeZoneError
 ##
 
 
+def get_frequency_spectrum(series: Series, /, *, d: int = 1) -> DataFrame:
+    """Get the frequency spectrum."""
+    import utilities.numpy
+
+    array = series.to_numpy()
+    spectrum = utilities.numpy.get_frequency_spectrum(array, d=d)
+    return DataFrame(
+        data=spectrum, schema={"frequency": Float64, "amplitude": Float64}, orient="row"
+    )
+
+
+##
+
+
 @overload
 def get_series_number_of_decimals(
     series: Series, /, *, nullable: Literal[True]
@@ -1736,6 +1840,7 @@ __all__ = [
     "SetFirstRowAsColumnsError",
     "StructFromDataClassError",
     "YieldStructSeriesElementsError",
+    "adjust_frequencies",
     "append_dataclass",
     "are_frames_equal",
     "ceil_datetime",
@@ -1753,6 +1858,7 @@ __all__ = [
     "finite_ewm_mean",
     "floor_datetime",
     "get_data_type_or_series_time_zone",
+    "get_frequency_spectrum",
     "get_series_number_of_decimals",
     "insert_after",
     "insert_before",

utilities/polars_ols.py

@@ -10,7 +10,9 @@ from utilities.functions import is_sequence_of
 from utilities.polars import concat_series, ensure_expr_or_series
 
 if TYPE_CHECKING:
-    from polars._typing import IntoExprColumn
+    from polars._typing import (
+        IntoExprColumn,  # pyright: ignore[reportPrivateImportUsage]
+    )
     from polars_ols import NullPolicy
 
     from utilities.polars import ExprLike