dycw-utilities 0.148.5__py3-none-any.whl → 0.174.12__py3-none-any.whl

utilities/polars.py

@@ -1,25 +1,24 @@
 from __future__ import annotations
 
-import datetime as dt
 import enum
 from collections.abc import Callable, Iterator, Sequence
 from collections.abc import Set as AbstractSet
-from contextlib import suppress
 from dataclasses import asdict, dataclass
 from functools import partial, reduce
-from itertools import chain, product
-from math import ceil, log
+from itertools import chain, pairwise, product
+from math import ceil, log, pi, sqrt
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, assert_never, cast, overload, override
 from uuid import UUID
 from zoneinfo import ZoneInfo
 
 import polars as pl
+import whenever
 from polars import (
     Boolean,
     DataFrame,
-    Date,
     Datetime,
+    Duration,
     Expr,
     Float64,
     Int64,
@@ -33,8 +32,11 @@ from polars import (
     any_horizontal,
     col,
     concat,
+    concat_list,
+    datetime_range,
     int_range,
     lit,
+    max_horizontal,
     struct,
     sum_horizontal,
     when,
@@ -49,59 +51,60 @@ from polars.exceptions import (
 )
 from polars.schema import Schema
 from polars.testing import assert_frame_equal, assert_series_equal
+from whenever import DateDelta, DateTimeDelta, PlainDateTime, TimeDelta, ZonedDateTime
 
-from utilities.dataclasses import _YieldFieldsInstance, yield_fields
+import utilities.math
+from utilities.dataclasses import yield_fields
 from utilities.errors import ImpossibleCaseError
-from utilities.functions import (
-    EnsureIntError,
-    ensure_int,
-    is_dataclass_class,
-    is_dataclass_instance,
-    is_iterable_of,
-    make_isinstance,
-)
+from utilities.functions import get_class_name
 from utilities.gzip import read_binary
 from utilities.iterables import (
     CheckIterablesEqualError,
     CheckMappingsEqualError,
-    CheckSubSetError,
     CheckSuperMappingError,
     OneEmptyError,
     OneNonUniqueError,
     always_iterable,
     check_iterables_equal,
     check_mappings_equal,
-    check_subset,
     check_supermapping,
     is_iterable_not_str,
     one,
+    resolve_include_and_exclude,
 )
 from utilities.json import write_formatted_json
 from utilities.math import (
+    MAX_DECIMALS,
     CheckIntegerError,
     check_integer,
     ewm_parameters,
     is_less_than,
     is_non_negative,
-    number_of_decimals,
 )
 from utilities.reprlib import get_repr
 from utilities.types import MaybeStr, Number, PathLike, WeekDay
 from utilities.typing import (
     get_args,
-    get_type_hints,
+    is_dataclass_class,
+    is_dataclass_instance,
     is_frozenset_type,
-    is_instance_gen,
     is_list_type,
     is_literal_type,
     is_optional_type,
     is_set_type,
-    is_union_type,
+    make_isinstance,
 )
 from utilities.warnings import suppress_warnings
-from utilities.zoneinfo import UTC, ensure_time_zone, get_time_zone_name
+from utilities.whenever import (
+    DatePeriod,
+    TimePeriod,
+    ZonedDateTimePeriod,
+    to_py_time_delta,
+)
+from utilities.zoneinfo import UTC, to_time_zone_name
 
 if TYPE_CHECKING:
+    import datetime as dt
     from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
     from collections.abc import Set as AbstractSet
 
@@ -112,6 +115,7 @@ if TYPE_CHECKING:
         JoinValidation,
         PolarsDataType,
         QuantileMethod,
+        RoundMode,
         SchemaDict,
         TimeUnit,
     )
@@ -122,13 +126,19 @@ if TYPE_CHECKING:
 
 
 type ExprLike = MaybeStr[Expr]
+type ExprOrSeries = Expr | Series
 DatetimeHongKong = Datetime(time_zone="Asia/Hong_Kong")
 DatetimeTokyo = Datetime(time_zone="Asia/Tokyo")
 DatetimeUSCentral = Datetime(time_zone="US/Central")
 DatetimeUSEastern = Datetime(time_zone="US/Eastern")
 DatetimeUTC = Datetime(time_zone="UTC")
+DatePeriodDType = Struct({"start": pl.Date, "end": pl.Date})
+TimePeriodDType = Struct({"start": pl.Time, "end": pl.Time})
+
+
 _FINITE_EWM_MIN_WEIGHT = 0.9999
 
+
 ##
 
 
@@ -208,7 +218,7 @@ def acf(
             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:
+        case never:
             assert_never(never)
 
 
@@ -238,11 +248,6 @@ def _acf_process_qstats_pvalues(qstats: NDArrayF, pvalues: NDArrayF, /) -> DataF
 ##
 
 
-# def acf_halflife(series: Series,/)
-
-##
-
-
 def adjust_frequencies(
     series: Series,
     /,
@@ -264,29 +269,108 @@ def adjust_frequencies(
 ##
 
 
-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}
-    try:
-        check_subset(non_null_fields, df.columns)
-    except CheckSubSetError as error:
-        raise AppendDataClassError(
-            left=error.left, right=error.right, extra=error.extra
-        ) from None
-    row_cols = set(df.columns) & set(non_null_fields)
-    row = dataclass_to_dataframe(obj).select(*row_cols)
-    return concat([df, row], how="diagonal")
+def all_dataframe_columns(
+    df: DataFrame, expr: IntoExprColumn, /, *exprs: IntoExprColumn
+) -> Series:
+    """Return a DataFrame column with `AND` applied to additional exprs/series."""
+    name = get_expr_name(df, expr)
+    return df.select(all_horizontal(expr, *exprs).alias(name))[name]
+
+
+def any_dataframe_columns(
+    df: DataFrame, expr: IntoExprColumn, /, *exprs: IntoExprColumn
+) -> Series:
+    """Return a DataFrame column with `OR` applied to additional exprs/series."""
+    name = get_expr_name(df, expr)
+    return df.select(any_horizontal(expr, *exprs).alias(name))[name]
+
+
+def all_series(series: Series, /, *columns: ExprOrSeries) -> Series:
+    """Return a Series with `AND` applied to additional exprs/series."""
+    return all_dataframe_columns(series.to_frame(), series.name, *columns)
+
+
+def any_series(series: Series, /, *columns: ExprOrSeries) -> Series:
+    """Return a Series with `OR` applied to additional exprs/series."""
+    df = series.to_frame()
+    name = series.name
+    return df.select(any_horizontal(name, *columns).alias(name))[name]
+
+
+##
+
+
+def append_row(
+    df: DataFrame,
+    row: StrMapping,
+    /,
+    *,
+    predicate: Callable[[StrMapping], bool] | None = None,
+    disallow_extra: bool = False,
+    disallow_missing: bool | MaybeIterable[str] = False,
+    disallow_null: bool | MaybeIterable[str] = False,
+    in_place: bool = False,
+) -> DataFrame:
+    """Append a row to a DataFrame."""
+    if (predicate is not None) and not predicate(row):
+        raise _AppendRowPredicateError(df=df, row=row)
+    if disallow_extra and (len(extra := set(row) - set(df.columns)) >= 1):
+        raise _AppendRowExtraKeysError(df=df, row=row, extra=extra)
+    if disallow_missing is not False:
+        missing = set(df.columns) - set(row)
+        if disallow_missing is not True:
+            missing &= set(always_iterable(disallow_missing))
+        if len(missing) >= 1:
+            raise _AppendRowMissingKeysError(df=df, row=row, missing=missing)
+    other = DataFrame(data=[row], schema=df.schema)
+    if disallow_null:
+        other_null = other.select(col(c).is_null().any() for c in other.columns)
+        null = {k for k, v in other_null.row(0, named=True).items() if v}
+        if disallow_null is not True:
+            null &= set(always_iterable(disallow_null))
+        if len(null) >= 1:
+            raise _AppendRowNullColumnsError(df=df, row=row, columns=null)
+    return df.extend(other) if in_place else df.vstack(other)
 
 
 @dataclass(kw_only=True, slots=True)
-class AppendDataClassError[T](Exception):
-    left: AbstractSet[T]
-    right: AbstractSet[T]
-    extra: AbstractSet[T]
+class AppendRowError(Exception):
+    df: DataFrame
+    row: StrMapping
+
 
+@dataclass(kw_only=True, slots=True)
+class _AppendRowPredicateError(AppendRowError):
     @override
     def __str__(self) -> str:
-        return f"Dataclass fields {get_repr(self.left)} must be a subset of DataFrame columns {get_repr(self.right)}; dataclass had extra items {get_repr(self.extra)}"
+        return f"Predicate failed; got {get_repr(self.row)}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _AppendRowExtraKeysError(AppendRowError):
+    extra: AbstractSet[str]
+
+    @override
+    def __str__(self) -> str:
+        return f"Extra key(s) found; got {get_repr(self.extra)}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _AppendRowMissingKeysError(AppendRowError):
+    missing: AbstractSet[str]
+
+    @override
+    def __str__(self) -> str:
+        return f"Missing key(s) found; got {get_repr(self.missing)}"
+
+
+@dataclass(kw_only=True, slots=True)
+class _AppendRowNullColumnsError(AppendRowError):
+    columns: AbstractSet[str]
+
+    @override
+    def __str__(self) -> str:
+        return f"Null column(s) found; got {get_repr(self.columns)}"
 
 
 ##
@@ -301,8 +385,8 @@ def are_frames_equal(
     check_column_order: bool = True,
     check_dtypes: bool = True,
     check_exact: bool = False,
-    rtol: float = 1e-5,
-    atol: float = 1e-8,
+    rel_tol: float = 1e-5,
+    abs_tol: float = 1e-8,
     categorical_as_str: bool = False,
 ) -> bool:
     """Check if two DataFrames are equal."""
@@ -314,8 +398,8 @@ def are_frames_equal(
             check_column_order=check_column_order,
             check_dtypes=check_dtypes,
             check_exact=check_exact,
-            rtol=rtol,
-            atol=atol,
+            rel_tol=rel_tol,
+            abs_tol=abs_tol,
             categorical_as_str=categorical_as_str,
         )
     except AssertionError:
@@ -345,7 +429,7 @@ def bernoulli(
             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:
+        case never:
             assert_never(never)
 
 
@@ -379,7 +463,7 @@ def boolean_value_counts(
                 (false / total).alias("false (%)"),
                 (null / total).alias("null (%)"),
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -422,29 +506,6 @@ class BooleanValueCountsError(Exception):
 ##
 
 
-@overload
-def ceil_datetime(column: ExprLike, every: ExprLike, /) -> Expr: ...
-@overload
-def ceil_datetime(column: Series, every: ExprLike, /) -> Series: ...
-@overload
-def ceil_datetime(column: IntoExprColumn, every: ExprLike, /) -> Expr | Series: ...
-def ceil_datetime(column: IntoExprColumn, every: ExprLike, /) -> Expr | Series:
-    """Compute the `ceil` of a datetime column."""
-    column = ensure_expr_or_series(column)
-    rounded = column.dt.round(every)
-    ceil = (
-        when(column <= rounded)
-        .then(rounded)
-        .otherwise(column.dt.offset_by(every).dt.round(every))
-    )
-    if isinstance(column, Expr):
-        return ceil
-    return DataFrame().with_columns(ceil.alias(column.name))[column.name]
-
-
-##
-
-
 def check_polars_dataframe(
     df: DataFrame,
     /,
@@ -504,7 +565,7 @@ def _check_polars_dataframe_columns(df: DataFrame, columns: Iterable[str], /) ->
 
 @dataclass(kw_only=True, slots=True)
 class _CheckPolarsDataFrameColumnsError(CheckPolarsDataFrameError):
-    columns: Sequence[str]
+    columns: list[str]
 
     @override
     def __str__(self) -> str:
@@ -763,29 +824,22 @@ def choice(
                 name=name,
                 dtype=dtype,
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
 ##
 
 
-def collect_series(expr: Expr, /) -> Series:
-    """Collect a column expression into a Series."""
-    data = DataFrame().with_columns(expr)
-    return data[one(data.columns)]
-
-
-##
-
-
-def columns_to_dict(df: DataFrame, key: str, value: str, /) -> dict[Any, Any]:
+def columns_to_dict(
+    df: DataFrame, key: IntoExprColumn, value: IntoExprColumn, /
+) -> dict[Any, Any]:
     """Map a pair of columns into a dictionary. Must be unique on `key`."""
-    col_key = df[key]
-    if col_key.is_duplicated().any():
-        raise ColumnsToDictError(df=df, key=key)
-    col_value = df[value]
-    return dict(zip(col_key, col_value, strict=True))
+    df = df.select(key, value)
+    key_col, value_col = [df[get_expr_name(df, expr)] for expr in [key, value]]
+    if key_col.is_duplicated().any():
+        raise ColumnsToDictError(df=df, key=key_col.name)
+    return dict(zip(key_col, value_col, strict=True))
 
 
 @dataclass(kw_only=True, slots=True)
@@ -828,7 +882,7 @@ def convert_time_zone(
 
 def _convert_time_zone_one(sr: Series, /, *, time_zone: TimeZoneLike = UTC) -> Series:
     if isinstance(sr.dtype, Datetime):
-        return sr.dt.convert_time_zone(get_time_zone_name(time_zone))
+        return sr.dt.convert_time_zone(to_time_zone_name(time_zone))
     return sr
 
 
@@ -849,13 +903,13 @@ def cross(
     up_or_down: Literal["up", "down"],
     other: Number | IntoExprColumn,
     /,
-) -> Expr | Series: ...
+) -> ExprOrSeries: ...
 def cross(
     expr: IntoExprColumn,
     up_or_down: Literal["up", "down"],
     other: Number | IntoExprColumn,
     /,
-) -> Expr | Series:
+) -> ExprOrSeries:
     """Compute when a cross occurs."""
     return _cross_or_touch(expr, "cross", up_or_down, other)
 
@@ -874,13 +928,13 @@ def touch(
     up_or_down: Literal["up", "down"],
     other: Number | IntoExprColumn,
     /,
-) -> Expr | Series: ...
+) -> ExprOrSeries: ...
 def touch(
     expr: IntoExprColumn,
     up_or_down: Literal["up", "down"],
     other: Number | IntoExprColumn,
     /,
-) -> Expr | Series:
+) -> ExprOrSeries:
     """Compute when a touch occurs."""
     return _cross_or_touch(expr, "touch", up_or_down, other)
 
@@ -891,7 +945,7 @@ def _cross_or_touch(
     up_or_down: Literal["up", "down"],
     other: Number | IntoExprColumn,
     /,
-) -> Expr | Series:
+) -> ExprOrSeries:
     """Compute when a column crosses/touches a threshold."""
     expr = ensure_expr_or_series(expr)
     match other:
@@ -899,7 +953,7 @@ def _cross_or_touch(
             ...
         case str() | Expr() | Series():
             other = ensure_expr_or_series(other)
-        case _ as never:
+        case never:
             assert_never(never)
     enough = int_range(end=pl.len()) >= 1
     match cross_or_touch, up_or_down:
@@ -911,7 +965,7 @@ def _cross_or_touch(
             current = expr >= other
         case "touch", "down":
             current = expr <= other
-        case _ as never:
+        case never:
             assert_never(never)
     prev = current.shift()
     result = when(enough & expr.is_finite()).then(current & ~prev)
@@ -963,7 +1017,7 @@ def cross_rolling_quantile(
     weights: list[float] | None = None,
     min_samples: int | None = None,
     center: bool = False,
-) -> Expr | Series: ...
+) -> ExprOrSeries: ...
 def cross_rolling_quantile(
     expr: IntoExprColumn,
     up_or_down: Literal["up", "down"],
@@ -975,7 +1029,7 @@ def cross_rolling_quantile(
     weights: list[float] | None = None,
     min_samples: int | None = None,
     center: bool = False,
-) -> Expr | Series:
+) -> ExprOrSeries:
     """Compute when a column crosses its rolling quantile."""
     expr = ensure_expr_or_series(expr)
     rolling = expr.rolling_quantile(
@@ -1020,16 +1074,43 @@ def dataclass_to_dataframe(
 
 
 def _dataclass_to_dataframe_cast(series: Series, /) -> Series:
-    if series.dtype == Object:
-        is_path = series.map_elements(make_isinstance(Path), return_dtype=Boolean).all()
-        is_uuid = series.map_elements(make_isinstance(UUID), return_dtype=Boolean).all()
-        if is_path or is_uuid:
-            with suppress_warnings(category=PolarsInefficientMapWarning):
-                return series.map_elements(str, return_dtype=String)
-        else:  # pragma: no cover
-            msg = f"{is_path=}, f{is_uuid=}"
-            raise NotImplementedError(msg)
-    return series
+    if series.dtype != Object:
+        return series
+    if series.map_elements(make_isinstance(whenever.Date), return_dtype=Boolean).all():
+        return series.map_elements(lambda x: x.py_date(), return_dtype=pl.Date)
+    if series.map_elements(make_isinstance(DateDelta), return_dtype=Boolean).all():
+        return series.map_elements(to_py_time_delta, return_dtype=Duration)
+    if series.map_elements(make_isinstance(DateTimeDelta), return_dtype=Boolean).all():
+        return series.map_elements(to_py_time_delta, return_dtype=Duration)
+    is_path = series.map_elements(make_isinstance(Path), return_dtype=Boolean).all()
+    is_uuid = series.map_elements(make_isinstance(UUID), return_dtype=Boolean).all()
+    if is_path or is_uuid:
+        with suppress_warnings(
+            category=cast("type[Warning]", PolarsInefficientMapWarning)
+        ):
+            return series.map_elements(str, return_dtype=String)
+    if series.map_elements(make_isinstance(whenever.Time), return_dtype=Boolean).all():
+        return series.map_elements(lambda x: x.py_time(), return_dtype=pl.Time)
+    if series.map_elements(make_isinstance(TimeDelta), return_dtype=Boolean).all():
+        return series.map_elements(to_py_time_delta, return_dtype=Duration)
+    if series.map_elements(make_isinstance(ZonedDateTime), return_dtype=Boolean).all():
+        return_dtype = zoned_date_time_dtype(time_zone=one({dt.tz for dt in series}))
+        return series.map_elements(lambda x: x.py_datetime(), return_dtype=return_dtype)
+    if series.map_elements(
+        lambda x: isinstance(x, dict) and (set(x) == {"start", "end"}),
+        return_dtype=Boolean,
+    ).all():
+        start = _dataclass_to_dataframe_cast(
+            series.map_elements(lambda x: x["start"], return_dtype=Object)
+        ).alias("start")
+        end = _dataclass_to_dataframe_cast(
+            series.map_elements(lambda x: x["end"], return_dtype=Object)
+        ).alias("end")
+        name = series.name
+        return concat_series(start, end).select(
+            struct(start=start, end=end).alias(name)
+        )[name]
+    raise NotImplementedError(series)  # pragma: no cover
 
 
 @dataclass(kw_only=True, slots=True)
@@ -1070,20 +1151,14 @@ def dataclass_to_schema(
     for field in yield_fields(
         obj, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
     ):
-        if is_dataclass_instance(field.value):
+        if is_dataclass_instance(field.value) and not (
+            isinstance(field.type_, type)
+            and issubclass(field.type_, (DatePeriod, TimePeriod, ZonedDateTimePeriod))
+        ):
             dtypes = dataclass_to_schema(
                 field.value, globalns=globalns, localns=localns
             )
             dtype = struct_dtype(**dtypes)
-        elif field.type_ is dt.datetime:
-            dtype = _dataclass_to_schema_datetime(field)
-        elif is_union_type(field.type_) and set(
-            get_args(field.type_, optional_drop_none=True)
-        ) == {dt.date, dt.datetime}:
-            if is_instance_gen(field.value, dt.date):
-                dtype = Date
-            else:
-                dtype = _dataclass_to_schema_datetime(field)
         else:
             dtype = _dataclass_to_schema_one(
                 field.type_, globalns=globalns, localns=localns
@@ -1092,14 +1167,6 @@ def dataclass_to_schema(
     return out
 
 
-def _dataclass_to_schema_datetime(
-    field: _YieldFieldsInstance[dt.datetime], /
-) -> PolarsDataType:
-    if field.value.tzinfo is None:
-        return Datetime
-    return zoned_datetime(time_zone=ensure_time_zone(field.value.tzinfo))
-
-
 def _dataclass_to_schema_one(
     obj: Any,
     /,
@@ -1107,20 +1174,35 @@ def _dataclass_to_schema_one(
     globalns: StrMapping | None = None,
     localns: StrMapping | None = None,
 ) -> PolarsDataType:
-    if obj is bool:
-        return Boolean
-    if obj is int:
-        return Int64
-    if obj is float:
-        return Float64
-    if obj is str:
-        return String
-    if obj is dt.date:
-        return Date
-    if obj in {Path, UUID}:
-        return Object
-    if isinstance(obj, type) and issubclass(obj, enum.Enum):
-        return pl.Enum([e.name for e in obj])
+    if isinstance(obj, type):
+        if issubclass(obj, bool):
+            return Boolean
+        if issubclass(obj, int):
+            return Int64
+        if issubclass(obj, float):
+            return Float64
+        if issubclass(obj, str):
+            return String
+        if issubclass(
+            obj,
+            (
+                DateDelta,
+                DatePeriod,
+                DateTimeDelta,
+                Path,
+                PlainDateTime,
+                TimeDelta,
+                TimePeriod,
+                UUID,
+                ZonedDateTime,
+                ZonedDateTimePeriod,
+                whenever.Date,
+                whenever.Time,
+            ),
+        ):
+            return Object
+        if issubclass(obj, enum.Enum):
+            return pl.Enum([e.name for e in obj])
     if is_dataclass_class(obj):
         out: dict[str, Any] = {}
         for field in yield_fields(obj, globalns=globalns, localns=localns):
@@ -1146,27 +1228,6 @@ def _dataclass_to_schema_one(
 ##
 
 
-def drop_null_struct_series(series: Series, /) -> Series:
-    """Drop nulls in a struct-dtype Series as per the <= 1.1 definition."""
-    try:
-        is_not_null = is_not_null_struct_series(series)
-    except IsNotNullStructSeriesError as error:
-        raise DropNullStructSeriesError(series=error.series) from None
-    return series.filter(is_not_null)
-
-
-@dataclass(kw_only=True, slots=True)
-class DropNullStructSeriesError(Exception):
-    series: Series
-
-    @override
-    def __str__(self) -> str:
-        return f"Series must have Struct-dtype; got {self.series.dtype}"
-
-
-##
-
-
 def ensure_data_type(dtype: PolarsDataType, /) -> DataType:
     """Ensure a data type is returned."""
     return dtype if isinstance(dtype, DataType) else dtype()
@@ -1180,8 +1241,8 @@ def ensure_expr_or_series(column: ExprLike, /) -> Expr: ...
 @overload
 def ensure_expr_or_series(column: Series, /) -> Series: ...
 @overload
-def ensure_expr_or_series(column: IntoExprColumn, /) -> Expr | Series: ...
-def ensure_expr_or_series(column: IntoExprColumn, /) -> Expr | Series:
+def ensure_expr_or_series(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def ensure_expr_or_series(column: IntoExprColumn, /) -> ExprOrSeries:
     """Ensure a column expression or Series is returned."""
     return col(column) if isinstance(column, str) else column
 
@@ -1191,7 +1252,7 @@ def ensure_expr_or_series(column: IntoExprColumn, /) -> Expr | Series:
 
 def ensure_expr_or_series_many(
     *columns: IntoExprColumn, **named_columns: IntoExprColumn
-) -> Sequence[Expr | Series]:
+) -> Sequence[ExprOrSeries]:
     """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())
@@ -1201,6 +1262,119 @@ def ensure_expr_or_series_many(
 ##
 
 
+def expr_to_series(expr: Expr, /) -> Series:
+    """Collect a column expression into a Series."""
+    return one_column(DataFrame().with_columns(expr))
+
+
+##
+
+
+@overload
+def filter_date(
+    column: ExprLike = "datetime",
+    /,
+    *,
+    time_zone: ZoneInfo | None = None,
+    include: MaybeIterable[whenever.Date] | None = None,
+    exclude: MaybeIterable[whenever.Date] | None = None,
+) -> Expr: ...
+@overload
+def filter_date(
+    column: Series,
+    /,
+    *,
+    time_zone: ZoneInfo | None = None,
+    include: MaybeIterable[whenever.Date] | None = None,
+    exclude: MaybeIterable[whenever.Date] | None = None,
+) -> Series: ...
+@overload
+def filter_date(
+    column: IntoExprColumn = "datetime",
+    /,
+    *,
+    time_zone: ZoneInfo | None = None,
+    include: MaybeIterable[whenever.Date] | None = None,
+    exclude: MaybeIterable[whenever.Date] | None = None,
+) -> ExprOrSeries: ...
+def filter_date(
+    column: IntoExprColumn = "datetime",
+    /,
+    *,
+    time_zone: ZoneInfo | None = None,
+    include: MaybeIterable[whenever.Date] | None = None,
+    exclude: MaybeIterable[whenever.Date] | None = None,
+) -> ExprOrSeries:
+    """Compute the filter based on a set of dates."""
+    column = ensure_expr_or_series(column)
+    if time_zone is not None:
+        column = column.dt.convert_time_zone(time_zone.key)
+    keep = true_like(column)
+    date = column.dt.date()
+    include, exclude = resolve_include_and_exclude(include=include, exclude=exclude)
+    if include is not None:
+        keep &= date.is_in([d.py_date() for d in include])
+    if exclude is not None:
+        keep &= ~date.is_in([d.py_date() for d in exclude])
+    return try_reify_expr(keep, column)
+
+
+@overload
+def filter_time(
+    column: ExprLike = "datetime",
+    /,
+    *,
+    time_zone: ZoneInfo | None = None,
+    include: MaybeIterable[tuple[whenever.Time, whenever.Time]] | None = None,
+    exclude: MaybeIterable[tuple[whenever.Time, whenever.Time]] | None = None,
+) -> Expr: ...
+@overload
+def filter_time(
+    column: Series,
+    /,
+    *,
+    time_zone: ZoneInfo | None = None,
+    include: MaybeIterable[tuple[whenever.Time, whenever.Time]] | None = None,
+    exclude: MaybeIterable[tuple[whenever.Time, whenever.Time]] | None = None,
+) -> Series: ...
+@overload
+def filter_time(
+    column: IntoExprColumn = "datetime",
+    /,
+    *,
+    time_zone: ZoneInfo | None = None,
+    include: MaybeIterable[tuple[whenever.Time, whenever.Time]] | None = None,
+    exclude: MaybeIterable[tuple[whenever.Time, whenever.Time]] | None = None,
+) -> ExprOrSeries: ...
+def filter_time(
+    column: IntoExprColumn = "datetime",
+    /,
+    *,
+    time_zone: ZoneInfo | None = None,
+    include: MaybeIterable[tuple[whenever.Time, whenever.Time]] | None = None,
+    exclude: MaybeIterable[tuple[whenever.Time, whenever.Time]] | None = None,
+) -> ExprOrSeries:
+    """Compute the filter based on a set of times."""
+    column = ensure_expr_or_series(column)
+    if time_zone is not None:
+        column = column.dt.convert_time_zone(time_zone.key)
+    keep = true_like(column)
+    time = column.dt.time()
+    include, exclude = resolve_include_and_exclude(include=include, exclude=exclude)
+    if include is not None:
+        keep &= any_horizontal(
+            time.is_between(s.py_time(), e.py_time()) for s, e in include
+        )
+    if exclude is not None:
+        keep &= ~any_horizontal(
+            time.is_between(s.py_time(), e.py_time()) for s, e in exclude
+        )
+    return try_reify_expr(keep, column)
+
+
+##
+
+
 @overload
 def finite_ewm_mean(
     column: ExprLike,
@@ -1233,7 +1407,7 @@ def finite_ewm_mean(
     half_life: float | None = None,
     alpha: float | None = None,
     min_weight: float = _FINITE_EWM_MIN_WEIGHT,
-) -> Expr | Series: ...
+) -> ExprOrSeries: ...
 def finite_ewm_mean(
     column: IntoExprColumn,
     /,
@@ -1243,7 +1417,7 @@ def finite_ewm_mean(
     half_life: float | None = None,
     alpha: float | None = None,
     min_weight: float = _FINITE_EWM_MIN_WEIGHT,
-) -> Expr | Series:
+) -> ExprOrSeries:
     """Compute a finite EWMA."""
     try:
         weights = _finite_ewm_weights(
@@ -1305,23 +1479,14 @@ class _FiniteEWMWeightsError(Exception):
 
 
 @overload
-def floor_datetime(column: ExprLike, every: ExprLike, /) -> Expr: ...
-@overload
-def floor_datetime(column: Series, every: ExprLike, /) -> Series: ...
+def first_true_horizontal(*columns: Series) -> Series: ...
 @overload
-def floor_datetime(column: IntoExprColumn, every: ExprLike, /) -> Expr | Series: ...
-def floor_datetime(column: IntoExprColumn, every: ExprLike, /) -> Expr | Series:
-    """Compute the `floor` of a datetime column."""
-    column = ensure_expr_or_series(column)
-    rounded = column.dt.round(every)
-    floor = (
-        when(column >= rounded)
-        .then(rounded)
-        .otherwise(column.dt.offset_by("-" + every).dt.round(every))
-    )
-    if isinstance(column, Expr):
-        return floor
-    return DataFrame().with_columns(floor.alias(column.name))[column.name]
+def first_true_horizontal(*columns: IntoExprColumn) -> ExprOrSeries: ...
+def first_true_horizontal(*columns: IntoExprColumn) -> ExprOrSeries:
+    """Get the index of the first true in each row."""
+    columns2 = ensure_expr_or_series_many(*columns)
+    expr = when(any_horizontal(*columns2)).then(concat_list(*columns2).list.arg_max())
+    return try_reify_expr(expr, *columns2)
 
 
 ##
@@ -1338,13 +1503,24 @@ def get_data_type_or_series_time_zone(
             dtype = dtype_cls()
         case Series() as series:
             dtype = series.dtype
-        case _ as never:
+        case never:
             assert_never(never)
-    if not isinstance(dtype, Datetime):
-        raise _GetDataTypeOrSeriesTimeZoneNotDateTimeError(dtype=dtype)
-    if dtype.time_zone is None:
-        raise _GetDataTypeOrSeriesTimeZoneNotZonedError(dtype=dtype)
-    return ZoneInfo(dtype.time_zone)
+    match dtype:
+        case Datetime() as datetime:
+            if datetime.time_zone is None:
+                raise _GetDataTypeOrSeriesTimeZoneNotZonedError(dtype=datetime)
+            return ZoneInfo(datetime.time_zone)
+        case Struct() as struct:
+            try:
+                return one({
+                    get_data_type_or_series_time_zone(f.dtype) for f in struct.fields
+                })
+            except OneNonUniqueError as error:
+                raise _GetDataTypeOrSeriesTimeZoneStructNonUniqueError(
+                    dtype=struct, first=error.first, second=error.second
+                ) from None
+        case _:
+            raise _GetDataTypeOrSeriesTimeZoneNotDateTimeError(dtype=dtype)
 
 
 @dataclass(kw_only=True, slots=True)
@@ -1366,6 +1542,18 @@ class _GetDataTypeOrSeriesTimeZoneNotZonedError(GetDataTypeOrSeriesTimeZoneError
         return f"Data type must be zoned; got {self.dtype}"
 
 
+@dataclass(kw_only=True, slots=True)
+class _GetDataTypeOrSeriesTimeZoneStructNonUniqueError(
+    GetDataTypeOrSeriesTimeZoneError
+):
+    first: ZoneInfo
+    second: ZoneInfo
+
+    @override
+    def __str__(self) -> str:
+        return f"Struct data type must contain exactly one time zone; got {self.first}, {self.second} and perhaps more"
+
+
 ##
 
 
@@ -1375,9 +1563,8 @@ def get_expr_name(obj: Series | DataFrame, expr: IntoExprColumn, /) -> str:
         case Series() as series:
             return get_expr_name(series.to_frame(), expr)
         case DataFrame() as df:
-            selected = df.select(expr)
-            return one(selected.columns)
-        case _ as never:
+            return one_column(df.select(expr)).name
+        case never:
             assert_never(never)
 
 
@@ -1399,50 +1586,31 @@ def get_frequency_spectrum(series: Series, /, *, d: int = 1) -> DataFrame:
 
 
 @overload
-def get_series_number_of_decimals(
-    series: Series, /, *, nullable: Literal[True]
-) -> int | None: ...
+def increasing_horizontal(*columns: ExprLike) -> Expr: ...
 @overload
-def get_series_number_of_decimals(
-    series: Series, /, *, nullable: Literal[False] = False
-) -> int: ...
+def increasing_horizontal(*columns: Series) -> Series: ...
 @overload
-def get_series_number_of_decimals(
-    series: Series, /, *, nullable: bool = False
-) -> int | None: ...
-def get_series_number_of_decimals(
-    series: Series, /, *, nullable: bool = False
-) -> int | None:
-    """Get the number of decimals of a series."""
-    if not isinstance(dtype := series.dtype, Float64):
-        raise _GetSeriesNumberOfDecimalsNotFloatError(dtype=dtype)
-    decimals = series.map_elements(number_of_decimals, return_dtype=Int64).max()
-    try:
-        return ensure_int(decimals, nullable=nullable)
-    except EnsureIntError:
-        raise _GetSeriesNumberOfDecimalsAllNullError(series=series) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class GetSeriesNumberOfDecimalsError(Exception): ...
+def increasing_horizontal(*columns: IntoExprColumn) -> ExprOrSeries: ...
+def increasing_horizontal(*columns: IntoExprColumn) -> ExprOrSeries:
+    """Check if a set of columns are increasing."""
+    columns2 = ensure_expr_or_series_many(*columns)
+    if len(columns2) == 0:
+        return lit(value=True, dtype=Boolean)
+    return all_horizontal(prev < curr for prev, curr in pairwise(columns2))
 
 
-@dataclass(kw_only=True, slots=True)
-class _GetSeriesNumberOfDecimalsNotFloatError(GetSeriesNumberOfDecimalsError):
-    dtype: DataType
-
-    @override
-    def __str__(self) -> str:
-        return f"Data type must be Float64; got {self.dtype}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _GetSeriesNumberOfDecimalsAllNullError(GetSeriesNumberOfDecimalsError):
-    series: Series
-
-    @override
-    def __str__(self) -> str:
-        return f"Series must not be all-null; got {self.series}"
+@overload
+def decreasing_horizontal(*columns: ExprLike) -> Expr: ...
+@overload
+def decreasing_horizontal(*columns: Series) -> Series: ...
+@overload
+def decreasing_horizontal(*columns: IntoExprColumn) -> ExprOrSeries: ...
+def decreasing_horizontal(*columns: IntoExprColumn) -> ExprOrSeries:
+    """Check if a set of columns are decreasing."""
+    columns2 = ensure_expr_or_series_many(*columns)
+    if len(columns2) == 0:
+        return lit(value=True, dtype=Boolean)
+    return all_horizontal(prev > curr for prev, curr in pairwise(columns2))
 
 
 ##
@@ -1575,13 +1743,49 @@ def integers(
                 name=name,
                 dtype=dtype,
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
 ##
 
 
+@overload
+def is_close(
+    x: ExprLike, y: ExprLike, /, *, rel_tol: float = 1e-9, abs_tol: float = 0
+) -> Expr: ...
+@overload
+def is_close(
+    x: Series, y: Series, /, *, rel_tol: float = 1e-9, abs_tol: float = 0
+) -> Series: ...
+@overload
+def is_close(
+    x: IntoExprColumn,
+    y: IntoExprColumn,
+    /,
+    *,
+    rel_tol: float = 1e-9,
+    abs_tol: float = 0,
+) -> ExprOrSeries: ...
+def is_close(
+    x: IntoExprColumn,
+    y: IntoExprColumn,
+    /,
+    *,
+    rel_tol: float = 1e-9,
+    abs_tol: float = 0,
+) -> ExprOrSeries:
+    """Check if two columns are close."""
+    x, y = map(ensure_expr_or_series, [x, y])
+    result = (x - y).abs() <= max_horizontal(
+        rel_tol * max_horizontal(x.abs(), y.abs()), abs_tol
+    )
+    return try_reify_expr(result, x, y)
+
+
+##
+
+
 @overload
 def is_near_event(
     *exprs: ExprLike, before: int = 0, after: int = 0, **named_exprs: ExprLike
@@ -1596,13 +1800,13 @@ def is_near_event(
     before: int = 0,
     after: int = 0,
     **named_exprs: IntoExprColumn,
-) -> Expr | Series: ...
+) -> ExprOrSeries: ...
 def is_near_event(
     *exprs: IntoExprColumn,
     before: int = 0,
     after: int = 0,
     **named_exprs: IntoExprColumn,
-) -> Expr | Series:
+) -> ExprOrSeries:
     """Compute the rows near any event."""
     if before <= -1:
         raise _IsNearEventBeforeError(before=before)
@@ -1645,68 +1849,28 @@ class _IsNearEventAfterError(IsNearEventError):
 ##
 
 
-def is_not_null_struct_series(series: Series, /) -> Series:
-    """Check if a struct-dtype Series is not null as per the <= 1.1 definition."""
-    try:
-        return ~is_null_struct_series(series)
-    except IsNullStructSeriesError as error:
-        raise IsNotNullStructSeriesError(series=error.series) from None
-
-
-@dataclass(kw_only=True, slots=True)
-class IsNotNullStructSeriesError(Exception):
-    series: Series
-
-    @override
-    def __str__(self) -> str:
-        return f"Series must have Struct-dtype; got {self.series.dtype}"
-
-
-##
-
-
-def is_null_struct_series(series: Series, /) -> Series:
-    """Check if a struct-dtype Series is null as per the <= 1.1 definition."""
-    if not isinstance(series.dtype, Struct):
-        raise IsNullStructSeriesError(series=series)
-    paths = _is_null_struct_series_one(series.dtype)
-    paths = list(paths)
-    exprs = map(_is_null_struct_to_expr, paths)
-    expr = all_horizontal(*exprs)
-    return (
-        series.struct.unnest().with_columns(_result=expr)["_result"].rename(series.name)
-    )
-
-
-def _is_null_struct_series_one(
-    dtype: Struct, /, *, root: Iterable[str] = ()
-) -> Iterator[Sequence[str]]:
-    for field in dtype.fields:
-        name = field.name
-        inner = field.dtype
-        path = list(chain(root, [name]))
-        if isinstance(inner, Struct):
-            yield from _is_null_struct_series_one(inner, root=path)
-        else:
-            yield path
-
-
-def _is_null_struct_to_expr(path: Iterable[str], /) -> Expr:
-    head, *tail = path
-    return reduce(_is_null_struct_to_expr_reducer, tail, col(head)).is_null()
-
-
-def _is_null_struct_to_expr_reducer(expr: Expr, path: str, /) -> Expr:
-    return expr.struct[path]
-
+@overload
+def is_true(column: ExprLike, /) -> Expr: ...
+@overload
+def is_true(column: Series, /) -> Series: ...
+@overload
+def is_true(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def is_true(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series is True."""
+    column = ensure_expr_or_series(column)
+    return (column.is_not_null()) & column
 
-@dataclass(kw_only=True, slots=True)
-class IsNullStructSeriesError(Exception):
-    series: Series
 
-    @override
-    def __str__(self) -> str:
-        return f"Series must have Struct-dtype; got {self.series.dtype}"
+@overload
+def is_false(column: ExprLike, /) -> Expr: ...
+@overload
+def is_false(column: Series, /) -> Series: ...
+@overload
+def is_false(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def is_false(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series is False."""
+    column = ensure_expr_or_series(column)
+    return (column.is_not_null()) & (~column)
 
 
 ##
@@ -1880,7 +2044,7 @@ def map_over_columns(
             return _map_over_series_one(func, series)
         case DataFrame() as df:
             return df.select(*(_map_over_series_one(func, df[c]) for c in df.columns))
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -1895,46 +2059,74 @@ def _map_over_series_one(func: Callable[[Series], Series], series: Series, /) ->
 ##
 
 
-def nan_sum_agg(column: str | Expr, /, *, dtype: PolarsDataType | None = None) -> Expr:
+def nan_sum_agg(column: str | Expr, /) -> Expr:
     """Nan sum aggregation."""
     col_use = col(column) if isinstance(column, str) else column
-    return (
-        when(col_use.is_not_null().any())
-        .then(col_use.sum())
-        .otherwise(lit(None, dtype=dtype))
-    )
+    return when(col_use.is_not_null().any()).then(col_use.sum())
 
 
 ##
 
 
-def nan_sum_cols(
-    column: str | Expr, *columns: str | Expr, dtype: PolarsDataType | None = None
-) -> Expr:
+@overload
+def nan_sum_horizontal(*columns: Series) -> Series: ...
+@overload
+def nan_sum_horizontal(*columns: IntoExprColumn) -> ExprOrSeries: ...
+def nan_sum_horizontal(*columns: IntoExprColumn) -> ExprOrSeries:
     """Nan sum across columns."""
-    all_columns = chain([column], columns)
-    all_exprs = (
-        col(column) if isinstance(column, str) else column for column in all_columns
+    columns2 = ensure_expr_or_series_many(*columns)
+    expr = when(any_horizontal(*(c.is_not_null() for c in columns2))).then(
+        sum_horizontal(*columns2)
     )
+    return try_reify_expr(expr, *columns2)
 
-    def func(x: Expr, y: Expr, /) -> Expr:
-        return (
-            when(x.is_not_null() & y.is_not_null())
-            .then(x + y)
-            .when(x.is_not_null() & y.is_null())
-            .then(x)
-            .when(x.is_null() & y.is_not_null())
-            .then(y)
-            .otherwise(lit(None, dtype=dtype))
-        )
 
-    return reduce(func, all_exprs)
+##
+
+
+@overload
+def normal_pdf(
+    x: ExprLike,
+    /,
+    *,
+    loc: float | IntoExprColumn = 0.0,
+    scale: float | IntoExprColumn = 1.0,
+) -> Expr: ...
+@overload
+def normal_pdf(
+    x: Series,
+    /,
+    *,
+    loc: float | IntoExprColumn = 0.0,
+    scale: float | IntoExprColumn = 1.0,
+) -> Series: ...
+@overload
+def normal_pdf(
+    x: IntoExprColumn,
+    /,
+    *,
+    loc: float | IntoExprColumn = 0.0,
+    scale: float | IntoExprColumn = 1.0,
+) -> ExprOrSeries: ...
+def normal_pdf(
+    x: IntoExprColumn,
+    /,
+    *,
+    loc: float | IntoExprColumn = 0.0,
+    scale: float | IntoExprColumn = 1.0,
+) -> ExprOrSeries:
+    """Compute the PDF of a normal distribution."""
+    x = ensure_expr_or_series(x)
+    loc = loc if isinstance(loc, int | float) else ensure_expr_or_series(loc)
+    scale = scale if isinstance(scale, int | float) else ensure_expr_or_series(scale)
+    expr = (1 / (scale * sqrt(2 * pi))) * (-(1 / 2) * ((x - loc) / scale) ** 2).exp()
+    return try_reify_expr(expr, x)
 
 
 ##
 
 
-def normal(
+def normal_rv(
     obj: int | Series | DataFrame,
     /,
     *,
@@ -1953,20 +2145,102 @@ def normal(
             values = rng.normal(loc=loc, scale=scale, size=height)
             return Series(name=name, values=values, dtype=dtype)
         case Series() as series:
-            return normal(
+            return normal_rv(
                 series.len(), loc=loc, scale=scale, seed=seed, name=name, dtype=dtype
             )
         case DataFrame() as df:
-            return normal(
+            return normal_rv(
                 df.height, loc=loc, scale=scale, seed=seed, name=name, dtype=dtype
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
 ##
 
 
+@overload
+def number_of_decimals(
+    column: ExprLike, /, *, max_decimals: int = MAX_DECIMALS
+) -> Expr: ...
+@overload
+def number_of_decimals(
+    column: Series, /, *, max_decimals: int = MAX_DECIMALS
+) -> Series: ...
+@overload
+def number_of_decimals(
+    column: IntoExprColumn, /, *, max_decimals: int = MAX_DECIMALS
+) -> ExprOrSeries: ...
+def number_of_decimals(
+    column: IntoExprColumn, /, *, max_decimals: int = MAX_DECIMALS
+) -> ExprOrSeries:
+    """Get the number of decimals."""
+    column = ensure_expr_or_series(column)
+    frac = column - column.floor()
+    results = (
+        _number_of_decimals_check_scale(frac, s) for s in range(max_decimals + 1)
+    )
+    return first_true_horizontal(*results)
+
+
+def _number_of_decimals_check_scale(frac: ExprOrSeries, scale: int, /) -> ExprOrSeries:
+    scaled = 10**scale * frac
+    return is_close(scaled, scaled.round()).alias(str(scale))
+
+
+##
+
+
+def offset_datetime(
+    datetime: ZonedDateTime, offset: str, /, *, n: int = 1
+) -> ZonedDateTime:
+    """Offset a datetime as `polars` would."""
+    sr = Series(values=[datetime.py_datetime()])
+    for _ in range(n):
+        sr = sr.dt.offset_by(offset)
+    return ZonedDateTime.from_py_datetime(sr.item())
+
+
+##
+
+
+def one_column(df: DataFrame, /) -> Series:
+    """Return the unique column in a DataFrame."""
+    try:
+        return df[one(df.columns)]
+    except OneEmptyError:
+        raise OneColumnEmptyError(df=df) from None
+    except OneNonUniqueError as error:
+        raise OneColumnNonUniqueError(
+            df=df, first=error.first, second=error.second
+        ) from None
+
+
+@dataclass(kw_only=True, slots=True)
+class OneColumnError(Exception):
+    df: DataFrame
+
+
+@dataclass(kw_only=True, slots=True)
+class OneColumnEmptyError(OneColumnError):
+    @override
+    def __str__(self) -> str:
+        return "DataFrame must not be empty"
+
+
+@dataclass(kw_only=True, slots=True)
+class OneColumnNonUniqueError(OneColumnError):
+    first: str
+    second: str
+
+    @override
+    def __str__(self) -> str:
+        return f"DataFrame must contain exactly one column; got {self.first!r}, {self.second!r} and perhaps more"
+
+
+##
+
+
 @overload
 def order_of_magnitude(column: ExprLike, /, *, round_: bool = False) -> Expr: ...
 @overload
@@ -1974,10 +2248,10 @@ def order_of_magnitude(column: Series, /, *, round_: bool = False) -> Series: ..
 @overload
 def order_of_magnitude(
     column: IntoExprColumn, /, *, round_: bool = False
-) -> Expr | Series: ...
+) -> ExprOrSeries: ...
 def order_of_magnitude(
     column: IntoExprColumn, /, *, round_: bool = False
-) -> Expr | Series:
+) -> ExprOrSeries:
     """Compute the order of magnitude of a column."""
     column = ensure_expr_or_series(column)
     result = column.abs().log10()
@@ -1987,6 +2261,75 @@ def order_of_magnitude(
 ##
 
 
+@overload
+def period_range(
+    start: ZonedDateTime,
+    end_or_length: ZonedDateTime | int,
+    /,
+    *,
+    interval: str = "1d",
+    time_unit: TimeUnit | None = None,
+    time_zone: TimeZoneLike | None = None,
+    eager: Literal[True],
+) -> Series: ...
+@overload
+def period_range(
+    start: ZonedDateTime,
+    end_or_length: ZonedDateTime | int,
+    /,
+    *,
+    interval: str = "1d",
+    time_unit: TimeUnit | None = None,
+    time_zone: TimeZoneLike | None = None,
+    eager: Literal[False] = False,
+) -> Expr: ...
+@overload
+def period_range(
+    start: ZonedDateTime,
+    end_or_length: ZonedDateTime | int,
+    /,
+    *,
+    interval: str = "1d",
+    time_unit: TimeUnit | None = None,
+    time_zone: TimeZoneLike | None = None,
+    eager: bool = False,
+) -> Series | Expr: ...
+def period_range(
+    start: ZonedDateTime,
+    end_or_length: ZonedDateTime | int,
+    /,
+    *,
+    interval: str = "1d",
+    time_unit: TimeUnit | None = None,
+    time_zone: TimeZoneLike | None = None,
+    eager: bool = False,
+) -> Series | Expr:
+    """Construct a period range."""
+    time_zone_use = None if time_zone is None else to_time_zone_name(time_zone)
+    match end_or_length:
+        case ZonedDateTime() as end:
+            ...
+        case int() as length:
+            end = offset_datetime(start, interval, n=length)
+        case never:
+            assert_never(never)
+    starts = datetime_range(
+        start.py_datetime(),
+        end.py_datetime(),
+        interval,
+        closed="left",
+        time_unit=time_unit,
+        time_zone=time_zone_use,
+        eager=eager,
+    ).alias("start")
+    ends = starts.dt.offset_by(interval).alias("end")
+    period = struct(starts, ends)
+    return try_reify_expr(period, starts, ends)
+
+
+##
+
+
 def reify_exprs(
     *exprs: IntoExprColumn, **named_exprs: IntoExprColumn
 ) -> Expr | Series | DataFrame:
@@ -2019,13 +2362,10 @@ def reify_exprs(
         .with_columns(*all_exprs)
         .drop("_index")
     )
-    match len(df.columns):
-        case 0:
-            raise ImpossibleCaseError(case=[f"{df.columns=}"])  # pragma: no cover
-        case 1:
-            return df[one(df.columns)]
-        case _:
-            return df
+    try:
+        return one_column(df)
+    except OneColumnNonUniqueError:
+        return df
 
 
 @dataclass(kw_only=True, slots=True)
@@ -2075,7 +2415,7 @@ def _replace_time_zone_one(
     sr: Series, /, *, time_zone: TimeZoneLike | None = UTC
 ) -> Series:
     if isinstance(sr.dtype, Datetime):
-        time_zone_use = None if time_zone is None else get_time_zone_name(time_zone)
+        time_zone_use = None if time_zone is None else to_time_zone_name(time_zone)
         return sr.dt.replace_time_zone(time_zone_use)
     return sr
 
@@ -2192,8 +2532,138 @@ def _reconstruct_dtype(obj: _DeconDType, /) -> PolarsDataType:
             return List(_reconstruct_dtype(inner))
         case "Struct", inner:
             return Struct(_reconstruct_schema(inner))
-        case _ as never:
+        case never:
+            assert_never(never)
+
+
+##
+
+
+@overload
+def round_to_float(
+    x: ExprLike, y: float, /, *, mode: RoundMode = "half_to_even"
+) -> Expr: ...
+@overload
+def round_to_float(
+    x: Series, y: float | ExprOrSeries, /, *, mode: RoundMode = "half_to_even"
+) -> Series: ...
+@overload
+def round_to_float(
+    x: ExprLike, y: Series, /, *, mode: RoundMode = "half_to_even"
+) -> Series: ...
+@overload
+def round_to_float(
+    x: ExprLike, y: Expr, /, *, mode: RoundMode = "half_to_even"
+) -> Expr: ...
+@overload
+def round_to_float(
+    x: IntoExprColumn, y: float | Series, /, *, mode: RoundMode = "half_to_even"
+) -> ExprOrSeries: ...
+def round_to_float(
+    x: IntoExprColumn, y: float | IntoExprColumn, /, *, mode: RoundMode = "half_to_even"
+) -> ExprOrSeries:
+    """Round a column to the nearest multiple of another float."""
+    x = ensure_expr_or_series(x)
+    y = y if isinstance(y, int | float) else ensure_expr_or_series(y)
+    match x, y:
+        case Expr() | Series(), int() | float():
+            z = (x / y).round(mode=mode) * y
+            return z.round(decimals=utilities.math.number_of_decimals(y) + 1)
+        case Series(), Expr() | Series():
+            df = (
+                x
+                .to_frame()
+                .with_columns(y)
+                .with_columns(number_of_decimals(y).alias("_decimals"))
+                .with_row_index(name="_index")
+                .group_by("_decimals")
+                .map_groups(_round_to_float_one)
+                .sort("_index")
+            )
+            return df[df.columns[1]]
+        case Expr(), Series():
+            df = y.to_frame().with_columns(x)
+            return round_to_float(df[df.columns[1]], df[df.columns[0]], mode=mode)
+        case Expr(), Expr() | str():
+            raise RoundToFloatError(x=x, y=y)
+        case never:
+            assert_never(never)
+
+
+def _round_to_float_one(df: DataFrame, /) -> DataFrame:
+    decimals: int | None = df["_decimals"].unique().item()
+    name = df.columns[1]
+    match decimals:
+        case int():
+            expr = col(name).round(decimals=decimals)
+        case None:
+            expr = lit(None, dtype=Float64).alias(name)
+        case never:
             assert_never(never)
+    return df.with_columns(expr)
+
+
+@dataclass(kw_only=True, slots=True)
+class RoundToFloatError(Exception):
+    x: IntoExprColumn
+    y: IntoExprColumn
+
+    @override
+    def __str__(self) -> str:
+        return f"At least 1 of the dividend and/or divisor must be a Series; got {get_class_name(self.x)!r} and {get_class_name(self.y)!r}"
+
+
+##
+
+
+def search_period(
+    series: Series,
+    date_time: ZonedDateTime,
+    /,
+    *,
+    start_or_end: Literal["start", "end"] = "end",
+) -> int | None:
+    """Search a series of periods for the one containing a given date-time."""
+    end = series.struct["end"]
+    py_date_time = date_time.py_datetime()
+    match start_or_end:
+        case "start":
+            index = end.search_sorted(py_date_time, side="right")
+            if index >= len(series):
+                return None
+            item: dt.datetime = series[index]["start"]
+            return index if py_date_time >= item else None
+        case "end":
+            index = end.search_sorted(py_date_time, side="left")
+            if index >= len(series):
+                return None
+            item: dt.datetime = series[index]["start"]
+            return index if py_date_time > item else None
+
+
+##
+
+
+def select_exact(
+    df: DataFrame, /, *columns: IntoExprColumn, drop: MaybeIterable[str] | None = None
+) -> DataFrame:
+    """Select an exact set of columns from a DataFrame."""
+    names = [get_expr_name(df, c) for c in columns]
+    drop = set() if drop is None else set(always_iterable(drop))
+    union = set(names) | drop
+    extra = [c for c in df.columns if c not in union]
+    if len(extra) >= 1:
+        raise SelectExactError(columns=extra)
+    return df.select(*columns)
+
+
+@dataclass(kw_only=True, slots=True)
+class SelectExactError(Exception):
+    columns: list[str]
+
+    @override
+    def __str__(self) -> str:
+        return f"All columns must be selected; got {get_repr(self.columns)} remaining"
 
 
 ##
@@ -2229,79 +2699,79 @@ def struct_dtype(**kwargs: PolarsDataType) -> Struct:
 ##
 
 
-def struct_from_dataclass(
-    cls: type[Dataclass],
-    /,
-    *,
-    globalns: StrMapping | None = None,
-    localns: StrMapping | None = None,
-    warn_name_errors: bool = False,
-    time_zone: TimeZoneLike | None = None,
-) -> Struct:
-    """Construct the Struct data type for a dataclass."""
-    if not is_dataclass_class(cls):
-        raise _StructFromDataClassNotADataclassError(cls=cls)
-    anns = get_type_hints(
-        cls, globalns=globalns, localns=localns, warn_name_errors=warn_name_errors
-    )
-    data_types = {
-        k: _struct_from_dataclass_one(v, time_zone=time_zone) for k, v in anns.items()
-    }
-    return Struct(data_types)
+@overload
+def to_true(column: ExprLike, /) -> Expr: ...
+@overload
+def to_true(column: Series, /) -> Series: ...
+@overload
+def to_true(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def to_true(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series turns True."""
+    t = is_true(column)
+    return ((~t).shift() & t).fill_null(value=False)
 
 
-def _struct_from_dataclass_one(
-    ann: Any, /, *, time_zone: TimeZoneLike | None = None
-) -> PolarsDataType:
-    mapping = {bool: Boolean, dt.date: Date, float: Float64, int: Int64, str: String}
-    with suppress(KeyError):
-        return mapping[ann]
-    if ann is dt.datetime:
-        if time_zone is None:
-            raise _StructFromDataClassTimeZoneMissingError
-        return zoned_datetime(time_zone=time_zone)
-    if is_dataclass_class(ann):
-        return struct_from_dataclass(ann, time_zone=time_zone)
-    if (isinstance(ann, type) and issubclass(ann, enum.Enum)) or (
-        is_literal_type(ann) and is_iterable_of(get_args(ann), str)
-    ):
-        return String
-    if is_optional_type(ann):
-        return _struct_from_dataclass_one(
-            one(get_args(ann, optional_drop_none=True)), time_zone=time_zone
-        )
-    if is_frozenset_type(ann) or is_list_type(ann) or is_set_type(ann):
-        return List(_struct_from_dataclass_one(one(get_args(ann)), time_zone=time_zone))
-    raise _StructFromDataClassTypeError(ann=ann)
+@overload
+def to_not_true(column: ExprLike, /) -> Expr: ...
+@overload
+def to_not_true(column: Series, /) -> Series: ...
+@overload
+def to_not_true(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def to_not_true(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series turns non-True."""
+    t = is_true(column)
+    return (t.shift() & (~t)).fill_null(value=False)
 
 
-@dataclass(kw_only=True, slots=True)
-class StructFromDataClassError(Exception): ...
+@overload
+def to_false(column: ExprLike, /) -> Expr: ...
+@overload
+def to_false(column: Series, /) -> Series: ...
+@overload
+def to_false(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def to_false(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series turns False."""
+    f = is_false(column)
+    return ((~f).shift() & f).fill_null(value=False)
 
 
-@dataclass(kw_only=True, slots=True)
-class _StructFromDataClassNotADataclassError(StructFromDataClassError):
-    cls: type[Dataclass]
+@overload
+def to_not_false(column: ExprLike, /) -> Expr: ...
+@overload
+def to_not_false(column: Series, /) -> Series: ...
+@overload
+def to_not_false(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def to_not_false(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute when a boolean series turns non-False."""
+    f = is_false(column)
+    return (f.shift() & (~f)).fill_null(value=False)
 
-    @override
-    def __str__(self) -> str:
-        return f"Object must be a dataclass; got {self.cls}"
 
+##
 
-@dataclass(kw_only=True, slots=True)
-class _StructFromDataClassTimeZoneMissingError(StructFromDataClassError):
-    @override
-    def __str__(self) -> str:
-        return "Time-zone must be given"
 
+@overload
+def true_like(column: ExprLike, /) -> Expr: ...
+@overload
+def true_like(column: Series, /) -> Series: ...
+@overload
+def true_like(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def true_like(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute a column of `True` values."""
+    column = ensure_expr_or_series(column)
+    return column.is_null() | column.is_not_null()
 
-@dataclass(kw_only=True, slots=True)
-class _StructFromDataClassTypeError(StructFromDataClassError):
-    ann: Any
 
-    @override
-    def __str__(self) -> str:
-        return f"Unsupported type: {self.ann}"
+@overload
+def false_like(column: ExprLike, /) -> Expr: ...
+@overload
+def false_like(column: Series, /) -> Series: ...
+@overload
+def false_like(column: IntoExprColumn, /) -> ExprOrSeries: ...
+def false_like(column: IntoExprColumn, /) -> ExprOrSeries:
+    """Compute a column of `False` values."""
+    column = ensure_expr_or_series(column)
+    return column.is_null() & column.is_not_null()
 
 
 ##
@@ -2309,7 +2779,7 @@ class _StructFromDataClassTypeError(StructFromDataClassError):
 
 def try_reify_expr(
     expr: IntoExprColumn, /, *exprs: IntoExprColumn, **named_exprs: IntoExprColumn
-) -> Expr | Series:
+) -> ExprOrSeries:
     """Try reify an expression."""
     expr = ensure_expr_or_series(expr)
     all_exprs = ensure_expr_or_series_many(*exprs, **named_exprs)
@@ -2322,7 +2792,7 @@ def try_reify_expr(
             return series
         case DataFrame() as df:
             return df[get_expr_name(df, expr)]
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -2355,7 +2825,7 @@ def uniform(
             return uniform(
                 df.height, low=low, high=high, seed=seed, name=name, dtype=dtype
             )
-        case _ as never:
+        case never:
             assert_never(never)
 
 
@@ -2376,8 +2846,8 @@ def week_num(column: ExprLike, /, *, start: WeekDay = "mon") -> Expr: ...
 @overload
 def week_num(column: Series, /, *, start: WeekDay = "mon") -> Series: ...
 @overload
-def week_num(column: IntoExprColumn, /, *, start: WeekDay = "mon") -> Expr | Series: ...
-def week_num(column: IntoExprColumn, /, *, start: WeekDay = "mon") -> Expr | Series:
+def week_num(column: IntoExprColumn, /, *, start: WeekDay = "mon") -> ExprOrSeries: ...
+def week_num(column: IntoExprColumn, /, *, start: WeekDay = "mon") -> ExprOrSeries:
     """Compute the week number of a date column."""
     column = ensure_expr_or_series(column)
     epoch = column.dt.epoch(time_unit="d").alias("epoch")
@@ -2388,87 +2858,129 @@ def week_num(column: IntoExprColumn, /, *, start: WeekDay = "mon") -> Expr | Ser
 ##
 
 
-def zoned_datetime(
+def zoned_date_time_dtype(
     *, time_unit: TimeUnit = "us", time_zone: TimeZoneLike = UTC
 ) -> Datetime:
-    """Create a zoned datetime data type."""
-    return Datetime(time_unit=time_unit, time_zone=get_time_zone_name(time_zone))
+    """Create a zoned date-time data type."""
+    return Datetime(time_unit=time_unit, time_zone=to_time_zone_name(time_zone))
+
+
+def zoned_date_time_period_dtype(
+    *,
+    time_unit: TimeUnit = "us",
+    time_zone: TimeZoneLike | tuple[TimeZoneLike, TimeZoneLike] = UTC,
+) -> Struct:
+    """Create a zoned date-time period data type."""
+    match time_zone:
+        case start, end:
+            return struct_dtype(
+                start=zoned_date_time_dtype(time_unit=time_unit, time_zone=start),
+                end=zoned_date_time_dtype(time_unit=time_unit, time_zone=end),
+            )
+        case _:
+            dtype = zoned_date_time_dtype(time_unit=time_unit, time_zone=time_zone)
+            return struct_dtype(start=dtype, end=dtype)
 
 
 __all__ = [
+    "AppendRowError",
     "BooleanValueCountsError",
     "CheckPolarsDataFrameError",
     "ColumnsToDictError",
     "DataClassToDataFrameError",
+    "DatePeriodDType",
     "DatetimeHongKong",
     "DatetimeTokyo",
     "DatetimeUSCentral",
     "DatetimeUSEastern",
     "DatetimeUTC",
-    "DropNullStructSeriesError",
+    "ExprOrSeries",
     "FiniteEWMMeanError",
     "GetDataTypeOrSeriesTimeZoneError",
-    "GetSeriesNumberOfDecimalsError",
     "InsertAfterError",
     "InsertBeforeError",
     "InsertBetweenError",
     "IsNearEventError",
-    "IsNullStructSeriesError",
+    "OneColumnEmptyError",
+    "OneColumnError",
+    "OneColumnNonUniqueError",
+    "RoundToFloatError",
+    "SelectExactError",
     "SetFirstRowAsColumnsError",
-    "StructFromDataClassError",
+    "TimePeriodDType",
     "acf",
     "adjust_frequencies",
-    "append_dataclass",
+    "all_dataframe_columns",
+    "all_series",
+    "any_dataframe_columns",
+    "any_series",
+    "append_row",
     "are_frames_equal",
     "bernoulli",
     "boolean_value_counts",
-    "ceil_datetime",
     "check_polars_dataframe",
     "choice",
-    "collect_series",
     "columns_to_dict",
     "concat_series",
     "convert_time_zone",
     "cross",
     "dataclass_to_dataframe",
     "dataclass_to_schema",
+    "decreasing_horizontal",
     "deserialize_dataframe",
-    "drop_null_struct_series",
     "ensure_data_type",
     "ensure_expr_or_series",
     "ensure_expr_or_series_many",
+    "expr_to_series",
+    "false_like",
+    "filter_date",
+    "filter_time",
     "finite_ewm_mean",
-    "floor_datetime",
+    "first_true_horizontal",
     "get_data_type_or_series_time_zone",
     "get_expr_name",
     "get_frequency_spectrum",
-    "get_series_number_of_decimals",
+    "increasing_horizontal",
     "insert_after",
     "insert_before",
     "insert_between",
     "integers",
+    "is_close",
+    "is_false",
     "is_near_event",
-    "is_not_null_struct_series",
-    "is_null_struct_series",
+    "is_true",
     "join",
     "join_into_periods",
     "map_over_columns",
     "nan_sum_agg",
-    "nan_sum_cols",
-    "normal",
+    "nan_sum_horizontal",
+    "normal_pdf",
+    "normal_rv",
+    "number_of_decimals",
+    "offset_datetime",
+    "one_column",
     "order_of_magnitude",
+    "period_range",
     "read_dataframe",
     "read_series",
     "replace_time_zone",
+    "round_to_float",
+    "search_period",
+    "select_exact",
     "serialize_dataframe",
     "set_first_row_as_columns",
     "struct_dtype",
-    "struct_from_dataclass",
+    "to_false",
+    "to_not_false",
+    "to_not_true",
+    "to_true",
     "touch",
+    "true_like",
     "try_reify_expr",
     "uniform",
     "unique_element",
     "write_dataframe",
     "write_series",
-    "zoned_datetime",
+    "zoned_date_time_dtype",
+    "zoned_date_time_period_dtype",
 ]