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

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

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

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

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=NU7I4AynUyg4F6Vu4XytgM7aO4TDKxvPbBFKo638x30,61
+utilities/__init__.py,sha256=Q2YV4YDdpMRcnIlWhuT_v301enhQDMFopz9BOGv-13g,61
 utilities/altair.py,sha256=Gpja-flOo-Db0PIPJLJsgzAlXWoKUjPU1qY-DQ829ek,9156
 utilities/astor.py,sha256=xuDUkjq0-b6fhtwjhbnebzbqQZAjMSHR1IIS5uOodVg,777
 utilities/asyncio.py,sha256=41oQUurWMvadFK5gFnaG21hMM0Vmfn2WS6OpC0R9mas,14757
@@ -28,7 +28,7 @@ utilities/hypothesis.py,sha256=sLqYcrFn0I3o0R7maqliIERRtAcREk2CKG8rSHY1t5U,46205
 utilities/ipython.py,sha256=V2oMYHvEKvlNBzxDXdLvKi48oUq2SclRg5xasjaXStw,763
 utilities/iterables.py,sha256=2Yy9gZ7BR4LXR4nlX7outFAjd4dpb3lgUo7ji_sdylY,45076
 utilities/jupyter.py,sha256=ft5JA7fBxXKzP-L9W8f2-wbF0QeYc_2uLQNFDVk4Z-M,2917
-utilities/lightweight_charts.py,sha256=0xNfcsrgFI0R9xL25LtSm-W5yhfBI93qQNT6HyaXAhg,2769
+utilities/lightweight_charts.py,sha256=vyVOzarYhBIOZj2xDhqdbP85qbSKUjdc6Au91rc1W4M,2814
 utilities/logging.py,sha256=opIwFjGKOYyMntVeCsFNXOmTY2z02hMf2UtCB76SaI4,25142
 utilities/loguru.py,sha256=MEMQVWrdECxk1e3FxGzmOf21vWT9j8CAir98SEXFKPA,3809
 utilities/luigi.py,sha256=fpH9MbxJDuo6-k9iCXRayFRtiVbUtibCJKugf7ygpv0,5988
@@ -46,7 +46,7 @@ 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=UFrD7smyBROlIBaLD6tUFKGAPtwLfyHPHp6dJI9i-kQ,54961
+utilities/polars.py,sha256=27oT-CmOtlAEdsZ2XOoN1GLINnRM2Byj_oBtsHGmp3c,57444
 utilities/polars_ols.py,sha256=efhXf0gjrHUpQrvS6a7g8yJQJWf_ATKtJnqqF2inCOU,5680
 utilities/pqdm.py,sha256=foRytQybmOQ05pjt5LF7ANyzrIa--4ScDE3T2wd31a4,3118
 utilities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -68,6 +68,7 @@ utilities/slack_sdk.py,sha256=SeDNMh24IPiEBWoGMdgvrflUaFa9TGlTS03H9-NKaQw,4132
 utilities/socket.py,sha256=K77vfREvzoVTrpYKo6MZakol0EYu2q1sWJnnZqL0So0,118
 utilities/sqlalchemy.py,sha256=GWzp54TP3F2mGhxPTn0c56KxxDeN9VKLMagcRSELhf4,35453
 utilities/sqlalchemy_polars.py,sha256=oGyMX5gSxuLI3N8mtz_-ml3UdWKcZuj6aFRW6ifI0Kc,15617
+utilities/statsmodels.py,sha256=F0bNmPUCmi3GsfpSuTVBYWxGimKury-pmcpFQ-SJ65I,2629
 utilities/streamlit.py,sha256=U9PJBaKP1IdSykKhPZhIzSPTZsmLsnwbEPZWzNhJPKk,2955
 utilities/sys.py,sha256=h0Xr7Vj86wNalvwJVP1wj5Y0kD_VWm1vzuXZ_jw94mE,2743
 utilities/tempfile.py,sha256=VqmZJAhTJ1OaVywFzk5eqROV8iJbW9XQ_QYAV0bpdRo,1384
@@ -86,7 +87,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.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,,
+dycw_utilities-0.109.21.dist-info/METADATA,sha256=oeS1xA25IzXCADvmuZu2P1ULQ3p1Kyv0_tkEcZmZzDo,13005
+dycw_utilities-0.109.21.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.109.21.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.109.21.dist-info/RECORD,,

utilities/__init__.py

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

utilities/lightweight_charts.py

@@ -13,7 +13,7 @@ if TYPE_CHECKING:
     from lightweight_charts import AbstractChart, Chart
     from lightweight_charts.abstract import SeriesCommon
     from polars import DataFrame
-    from polars._typing import SchemaDict
+    from polars._typing import SchemaDict  # pyright: ignore[reportPrivateImportUsage]
 
     from utilities.types import PathLike
 

utilities/polars.py

@@ -121,6 +121,7 @@ if TYPE_CHECKING:
     )
 
     from utilities.numpy import NDArrayB, NDArrayF
+    from utilities.statsmodels import ACFMissing
     from utilities.types import (
         Dataclass,
         MaybeIterable,
@@ -143,6 +144,85 @@ _FINITE_EWM_MIN_WEIGHT = 0.9999
 ##
 
 
+def acf(
+    series: Series,
+    /,
+    *,
+    adjusted: bool = False,
+    nlags: int | None = None,
+    qstat: bool = False,
+    fft: bool = True,
+    alpha: float | None = None,
+    bartlett_confint: bool = True,
+    missing: ACFMissing = "none",
+) -> DataFrame:
+    """Compute the autocorrelations of a series."""
+    from numpy import ndarray
+
+    import utilities.statsmodels
+
+    array = series.to_numpy()
+    result = utilities.statsmodels.acf(
+        array,
+        adjusted=adjusted,
+        nlags=nlags,
+        qstat=qstat,
+        fft=fft,
+        alpha=alpha,
+        bartlett_confint=bartlett_confint,
+        missing=missing,
+    )
+    match result:
+        case ndarray() as acfs:
+            return _acf_process_acfs(acfs)
+        case ndarray() as acfs, ndarray() as confints:
+            df_acfs = _acf_process_acfs(acfs)
+            df_confints = _acf_process_confints(confints)
+            return df_acfs.join(df_confints, on=["lag"])
+        case ndarray() as acfs, ndarray() as qstats, ndarray() as pvalues:
+            df_acfs = _acf_process_acfs(acfs)
+            df_qstats_pvalues = _acf_process_qstats_pvalues(qstats, pvalues)
+            return df_acfs.join(df_qstats_pvalues, on=["lag"], how="left")
+        case (
+            ndarray() as acfs,
+            ndarray() as confints,
+            ndarray() as qstats,
+            ndarray() as pvalues,
+        ):
+            df_acfs = _acf_process_acfs(acfs)
+            df_confints = _acf_process_confints(confints)
+            df_qstats_pvalues = _acf_process_qstats_pvalues(qstats, pvalues)
+            return join(df_acfs, df_confints, df_qstats_pvalues, on=["lag"], how="left")
+        case _ as never:
+            assert_never(never)
+
+
+def _acf_process_acfs(acfs: NDArrayF, /) -> DataFrame:
+    return (
+        Series(name="autocorrelation", values=acfs, dtype=Float64)
+        .to_frame()
+        .with_row_index(name="lag")
+    )
+
+
+def _acf_process_confints(confints: NDArrayF, /) -> DataFrame:
+    return DataFrame(
+        data=confints, schema={"lower": Float64, "upper": Float64}
+    ).with_row_index(name="lag")
+
+
+def _acf_process_qstats_pvalues(qstats: NDArrayF, pvalues: NDArrayF, /) -> DataFrame:
+    from numpy import hstack
+
+    data = hstack([qstats.reshape(-1, 1), pvalues.reshape(-1, 1)])
+    return DataFrame(
+        data=data, schema={"qstat": Float64, "pvalue": Float64}
+    ).with_row_index(name="lag", offset=1)
+
+
+##
+
+
 def adjust_frequencies(
     series: Series,
     /,
@@ -1840,6 +1920,7 @@ __all__ = [
     "SetFirstRowAsColumnsError",
     "StructFromDataClassError",
     "YieldStructSeriesElementsError",
+    "acf",
     "adjust_frequencies",
     "append_dataclass",
     "are_frames_equal",

utilities/statsmodels.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal, cast, overload
+
+import statsmodels.tsa.stattools
+
+if TYPE_CHECKING:
+    from utilities.numpy import NDArrayF
+
+
+type ACFMissing = Literal["none", "raise", "conservative", "drop"]
+
+
+@overload
+def acf(
+    array: NDArrayF,
+    /,
+    *,
+    adjusted: bool = False,
+    nlags: int | None = None,
+    qstat: Literal[False] = False,
+    fft: bool = True,
+    alpha: None = None,
+    bartlett_confint: bool = True,
+    missing: ACFMissing = "none",
+) -> NDArrayF: ...
+@overload
+def acf(
+    array: NDArrayF,
+    /,
+    *,
+    adjusted: bool = False,
+    nlags: int | None = None,
+    qstat: Literal[False] = False,
+    fft: bool = True,
+    alpha: float,
+    bartlett_confint: bool = True,
+    missing: ACFMissing = "none",
+) -> tuple[NDArrayF, NDArrayF]: ...
+@overload
+def acf(
+    array: NDArrayF,
+    /,
+    *,
+    adjusted: bool = False,
+    nlags: int | None = None,
+    qstat: Literal[True],
+    fft: bool = True,
+    alpha: float,
+    bartlett_confint: bool = True,
+    missing: ACFMissing = "none",
+) -> tuple[NDArrayF, NDArrayF, NDArrayF, NDArrayF]: ...
+@overload
+def acf(
+    array: NDArrayF,
+    /,
+    *,
+    adjusted: bool = False,
+    nlags: int | None = None,
+    qstat: Literal[True],
+    fft: bool = True,
+    alpha: None = None,
+    bartlett_confint: bool = True,
+    missing: ACFMissing = "none",
+) -> tuple[NDArrayF, NDArrayF, NDArrayF]: ...
+@overload
+def acf(
+    array: NDArrayF,
+    /,
+    *,
+    adjusted: bool = False,
+    nlags: int | None = None,
+    qstat: bool = False,
+    fft: bool = True,
+    alpha: float | None = None,
+    bartlett_confint: bool = True,
+    missing: ACFMissing = "none",
+) -> (
+    NDArrayF
+    | tuple[NDArrayF, NDArrayF]
+    | tuple[NDArrayF, NDArrayF, NDArrayF]
+    | tuple[NDArrayF, NDArrayF, NDArrayF, NDArrayF]
+): ...
+def acf(
+    array: NDArrayF,
+    /,
+    *,
+    adjusted: bool = False,
+    nlags: int | None = None,
+    qstat: bool = False,
+    fft: bool = True,
+    alpha: float | None = None,
+    bartlett_confint: bool = True,
+    missing: ACFMissing = "none",
+) -> (
+    NDArrayF
+    | tuple[NDArrayF, NDArrayF]
+    | tuple[NDArrayF, NDArrayF, NDArrayF]
+    | tuple[NDArrayF, NDArrayF, NDArrayF, NDArrayF]
+):
+    """Typed version of `acf`."""
+    return cast(
+        "Any",
+        statsmodels.tsa.stattools.acf(
+            array,
+            adjusted=adjusted,
+            nlags=nlags,
+            qstat=qstat,
+            fft=fft,
+            alpha=alpha,
+            bartlett_confint=bartlett_confint,
+            missing=missing,
+        ),
+    )
+
+
+__all__ = ["ACFMissing", "acf"]