time-split 0.1.0__tar.gz

time_split-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024, Richard Sundqvist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

time_split-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.1
+Name: time-split
+Version: 0.1.0
+Summary: My personal little ML engineering library.
+Home-page: https://github.com/rsundqvist/time-split
+Author: Richard Sundqvist
+Author-email: richard.sundqvist@live.se
+Requires-Python: >=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Provides-Extra: plotting
+Requires-Dist: matplotlib ; extra == "plotting"
+Requires-Dist: pandas (>=2.0.3)
+Requires-Dist: rics (>=3.1.0)
+Requires-Dist: seaborn ; extra == "plotting"
+Project-URL: Bug Tracker, https://github.com/rsundqvist/time-split/issues
+Project-URL: Changelog, https://github.com/rsundqvist/time-split/blob/master/CHANGELOG.md
+Project-URL: Documentation, https://time-split.readthedocs.io
+Project-URL: Repository, https://github.com/rsundqvist/time-split
+Description-Content-Type: text/markdown
+
+# Time Split  <!-- omit in toc -->
+Flexible k-fold validation splits for heterogeneous data.
+
+-----------------
+[![PyPI - Version](https://img.shields.io/pypi/v/time-split.svg)](https://pypi.python.org/pypi/time-split)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/time-split.svg)](https://pypi.python.org/pypi/time-split)
+[![Tests](https://github.com/rsundqvist/time-split/workflows/tests/badge.svg)](https://github.com/rsundqvist/time-split/actions?workflow=tests)
+[![Codecov](https://codecov.io/gh/rsundqvist/time-split/branch/master/graph/badge.svg)](https://codecov.io/gh/rsundqvist/time-split)
+[![Read the Docs](https://readthedocs.org/projects/time-split/badge/)](https://time-split.readthedocs.io/)
+[![PyPI - License](https://img.shields.io/pypi/l/time-split.svg)](https://pypi.python.org/pypi/time-split)
+
+<div align="center">
+  <img alt="Plotted folds on a two-by-two grid." 
+       title="Examples" height="300" width="1200" 
+  src="https://raw.githubusercontent.com/rsundqvist/time-split/master/docs/2x2-examples.jpg"><br>
+</div>
+
+Plotted folds on a two-by-two grid. See the
+[examples](https://time-split.readthedocs.io/en/stable/auto_examples/index.html) page for more.
+
+## What is it?
+A library for creating cross-validation splits of _heterogeneous_ data, such as raw transaction data with strong
+non-stationary characteristics.
+
+## Highlighted Features
+- [Splitting schedules](https://time-split.readthedocs.io/en/stable/guide/schedules.html) based on a fixed interval, 
+  a CRON-expression, or a pre-defined list.
+- [Data selection](https://time-split.readthedocs.io/en/stable/guide/spans.html) based on a timedelta, or the splitting 
+  schedule itself.
+- Automatically extract and [normalize](https://time-split.readthedocs.io/en/stable/guide/flex.html) data limits for 
+  supported data types.
+- [Plotting function](https://time-split.readthedocs.io/en/stable/generated/time_split.html#time_split.plot) for
+  visualization of folds. Display fold sizes (hour/row count), or 
+  [use custom text](https://time-split.readthedocs.io/en/stable/auto_examples/plotting_with_metrics.html).
+- [Integrations](https://time-split.readthedocs.io/en/stable/generated/time_split.integration.html) for popular 
+  libraries such as `pandas`, `polars` and `scikit-learn`.
+
+## Installation
+The package is published through the [Python Package Index (PyPI)]. Source code
+is available on GitHub: https://github.com/rsundqvist/time-split
+
+```sh
+pip install -U time-split
+```
+
+This is the preferred method to install ``time-split``, as it will always install the
+most recent stable release.
+
+If you don't have [pip] installed, this [Python installation guide] can guide
+you through the process.
+
+## License
+[MIT](LICENSE.md)
+
+## Documentation
+Hosted on Read the Docs: https://time-split.readthedocs.io
+
+## Contributing
+
+All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. To get 
+started, see the [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).
+
+[Python Package Index (PyPI)]: https://pypi.org/project/time-split
+[pip]: https://pip.pypa.io
+[Python installation guide]: http://docs.python-guide.org/en/stable/starting/installation/
+

time_split-0.1.0/README.md

@@ -0,0 +1,65 @@
+# Time Split  <!-- omit in toc -->
+Flexible k-fold validation splits for heterogeneous data.
+
+-----------------
+[![PyPI - Version](https://img.shields.io/pypi/v/time-split.svg)](https://pypi.python.org/pypi/time-split)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/time-split.svg)](https://pypi.python.org/pypi/time-split)
+[![Tests](https://github.com/rsundqvist/time-split/workflows/tests/badge.svg)](https://github.com/rsundqvist/time-split/actions?workflow=tests)
+[![Codecov](https://codecov.io/gh/rsundqvist/time-split/branch/master/graph/badge.svg)](https://codecov.io/gh/rsundqvist/time-split)
+[![Read the Docs](https://readthedocs.org/projects/time-split/badge/)](https://time-split.readthedocs.io/)
+[![PyPI - License](https://img.shields.io/pypi/l/time-split.svg)](https://pypi.python.org/pypi/time-split)
+
+<div align="center">
+  <img alt="Plotted folds on a two-by-two grid." 
+       title="Examples" height="300" width="1200" 
+  src="https://raw.githubusercontent.com/rsundqvist/time-split/master/docs/2x2-examples.jpg"><br>
+</div>
+
+Plotted folds on a two-by-two grid. See the
+[examples](https://time-split.readthedocs.io/en/stable/auto_examples/index.html) page for more.
+
+## What is it?
+A library for creating cross-validation splits of _heterogeneous_ data, such as raw transaction data with strong
+non-stationary characteristics.
+
+## Highlighted Features
+- [Splitting schedules](https://time-split.readthedocs.io/en/stable/guide/schedules.html) based on a fixed interval, 
+  a CRON-expression, or a pre-defined list.
+- [Data selection](https://time-split.readthedocs.io/en/stable/guide/spans.html) based on a timedelta, or the splitting 
+  schedule itself.
+- Automatically extract and [normalize](https://time-split.readthedocs.io/en/stable/guide/flex.html) data limits for 
+  supported data types.
+- [Plotting function](https://time-split.readthedocs.io/en/stable/generated/time_split.html#time_split.plot) for
+  visualization of folds. Display fold sizes (hour/row count), or 
+  [use custom text](https://time-split.readthedocs.io/en/stable/auto_examples/plotting_with_metrics.html).
+- [Integrations](https://time-split.readthedocs.io/en/stable/generated/time_split.integration.html) for popular 
+  libraries such as `pandas`, `polars` and `scikit-learn`.
+
+## Installation
+The package is published through the [Python Package Index (PyPI)]. Source code
+is available on GitHub: https://github.com/rsundqvist/time-split
+
+```sh
+pip install -U time-split
+```
+
+This is the preferred method to install ``time-split``, as it will always install the
+most recent stable release.
+
+If you don't have [pip] installed, this [Python installation guide] can guide
+you through the process.
+
+## License
+[MIT](LICENSE.md)
+
+## Documentation
+Hosted on Read the Docs: https://time-split.readthedocs.io
+
+## Contributing
+
+All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. To get 
+started, see the [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).
+
+[Python Package Index (PyPI)]: https://pypi.org/project/time-split
+[pip]: https://pip.pypa.io
+[Python installation guide]: http://docs.python-guide.org/en/stable/starting/installation/

time_split-0.1.0/pyproject.toml

@@ -0,0 +1,190 @@
+[tool.poetry]
+name = "time-split"
+version = "0.1.0"
+description = "My personal little ML engineering library."
+authors = ["Richard Sundqvist <richard.sundqvist@live.se>"]
+
+readme = "README.md"
+homepage = "https://github.com/rsundqvist/time-split"
+repository = "https://github.com/rsundqvist/time-split"
+documentation = "https://time-split.readthedocs.io"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    'Programming Language :: Python :: 3 :: Only',
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/rsundqvist/time-split/issues"
+"Changelog" = "https://github.com/rsundqvist/time-split/blob/master/CHANGELOG.md"
+
+[tool.poetry.scripts]
+
+[tool.poetry.dependencies]
+python = ">=3.11"
+
+pandas = ">=2.0.3"
+rics = ">=3.1.0"
+
+# plotting
+matplotlib = { version = "*", optional = true }
+seaborn = { version = "*", optional = true }
+
+[tool.poetry.extras]
+plotting = ["matplotlib", "seaborn"]
+
+[tool.poetry.group.manual-extras.dependencies]
+# Extras that must be available for docs + tests go here. Doc/test-only deps go in their respective groups.
+croniter = "^2.0.3"
+pyarrow = "^15.0.2"
+polars = { version = "^0.20.19", extras = ["pandas"] }
+
+[tool.poetry.group.docs]
+[tool.poetry.group.docs.dependencies]
+# duplicate object warnings for sphinx>=4
+# description: https://github.com/astropy/astropy/issues/11723
+# https://github.com/astropy/astropy/pull/12270
+sphinx = "^7.2.6"
+sphinx-gallery = "^0.15.0"
+pydata-sphinx-theme = "^0.15.2"
+myst-parser = "^2.0.0"
+nbsphinx = "^0.9.3"
+ipython = "^8.23.0"
+
+[tool.poetry.group.notebooks]
+optional = true
+[tool.poetry.group.notebooks.dependencies]
+jupyterlab = "^4"
+ipywidgets = "*"
+jupyterlab-execute-time = "*"
+tqdm = "*"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.1.1"
+xdoctest = "^1.1.3"
+coverage = "^7.4.4"
+pytest-cov = "^5.0.0"
+
+scikit-learn = "^1.4.2"
+# TODO Unpin.
+# dask.datasets.timeseries() warns:
+#     UserWarning: dask_expr does not support the DataFrameIOFunction protocol for column projection
+# on dask == 2024.3.1
+dask = { version = "==2024.4.1", extras = ["dataframe"] }
+
+[tool.poetry.group.devops.dependencies]
+invoke = "^2.2.0"
+mypy = "^1.9.0"
+ruff = "^0.3.7"
+
+safety = "^3.1.0"
+codespell = "^2.2.6"
+bump2version = "^1.0.1"
+
+[tool.ruff]
+line-length = 120
+fix = true
+unsafe-fixes = false
+output-format = "grouped"
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = 80
+line-ending = "lf"
+
+[tool.ruff.lint]
+exclude = ["notebooks/*"]
+select = [
+    "ANN",
+    "S",
+    "I",
+    "B",
+    "D",
+    "F",
+    "W",
+    "E",
+    "SLOT",
+    "SIM",
+    "TID",
+    "TD",
+    "TCH",
+    "ARG",
+    "PTH",
+    "NPY",
+    "PD",
+    "N",
+    "PERF",
+    "PLC",
+    "PLE",
+    "PLR",
+    "PLW",
+    "UP",
+    "FURB",
+    "RUF",
+    "TRY",
+]
+ignore = [
+    "ANN101", # Missing type annotation for `self` in method
+    "ANN102", # Missing type annotation for `cls` in method
+    "D105", # Missing docstring in magic method
+    "D107", # Missing docstring in `__init__`
+    "ANN401",
+    "TID252", # Prefer absolute imports over relative imports from parent modules
+    "TRY003",
+    "PD901", # Avoid using the generic variable name `df` for DataFrames
+    "PLC0415", # `import` should be at the top-level of a file
+    "PLR0913", #
+    "SIM108", # Use ternary operator - coverage issue, see https://github.com/nedbat/coveragepy/issues/509
+    "TD003", # Missing issue link
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "D",
+    "S101", # Allow 'assert' keyword
+    "ANN",
+    "PLR2004", # Allow magic values
+]
+"examples/*" = [
+    "D205", # Clashes with sphinx_gallery (generated examples)
+    "B007",
+]
+"**/time_split/*" = [
+    "PLR0913", # Too many arguments in function definition
+]
+"**/time_split/integration/sklearn/*" = [
+    "N803", # Argument name `X` should be lowercase
+    "ARG002", # Unused method argument: `groups`
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+[tool.ruff.lint.pycodestyle]
+max-line-length = 150
+
+[tool.pytest]
+[tool.pytest.ini_options]
+filterwarnings = [
+    "error",
+    "ignore:Matplotlib is currently using agg:UserWarning",
+    "ignore:.*utcfromtimestamp.*:DeprecationWarning", # Detta är farligt - ta bort
+]
+log_file_level = 10
+log_file = "pytest.log"
+norecursedirs = [
+    "**/cli_modules/*",
+]
+
+[build-system]
+requires = ["poetry-core>=1.0.8"]
+build-backend = "poetry.core.masonry.api"

time_split-0.1.0/src/time_split/__init__.py

@@ -0,0 +1,16 @@
+"""Create temporal k-folds for cross-validation with heterogeneous data."""
+
+import logging as _logging
+
+from ._frontend import log_split_progress, plot, split
+
+__all__ = [
+    "log_split_progress",
+    "plot",
+    "split",
+    "__version__",  # Make MyPy happy
+]
+
+__version__ = "0.1.0"
+
+_logging.getLogger(__name__).addHandler(_logging.NullHandler())

time_split-0.1.0/src/time_split/_backend/__init__.py

@@ -0,0 +1,4 @@
+from ._limits import expand_limits
+from ._splitter import DatetimeIndexSplitter
+
+__all__ = ["DatetimeIndexSplitter", "expand_limits"]

time_split-0.1.0/src/time_split/_backend/_available.py

@@ -0,0 +1,57 @@
+from typing import NamedTuple
+
+from pandas import DatetimeIndex, Timestamp, isna
+
+from .._support import handle_dask
+from ..types import DatetimeIterable, Flex
+from ._datetime_index_like import DatetimeIndexLike
+from ._limits import LimitsTuple, expand_limits
+
+
+class AvailableMetadata(NamedTuple):
+    """Output of :func:`process_available`."""
+
+    available_as_index: DatetimeIndexLike | None
+    limits: LimitsTuple
+    expanded_limits: LimitsTuple
+
+
+def process_available(available: DatetimeIterable, *, flex: Flex) -> AvailableMetadata:
+    """Process a user-given `available` argument.
+
+    Args:
+        available: Available data from user. May be ``None``
+        flex: Flex-argument. Determines how much (if at all) to expand limits.
+
+    Returns:
+        A tuple ``(available, limits)``. Note that `available` will be ``None``, it has not been iterated over. This
+        assures that iterables are not consumed unless needed.
+
+    Raises:
+        ValueError: For invalid `available` arguments.
+
+    """
+    if isinstance(available, DatetimeIndexLike):
+        # Avoids conversion, which may be expensive (or impossible on the current machine),
+        # and leverages additional non-Pandas types that do vectorized min/max.
+        limits = _compute_data_limits(available)
+        available_retval = available
+    else:
+        available_retval = DatetimeIndex(available)
+        limits = _compute_data_limits(available_retval)
+
+    min_dt, max_dt = limits
+    if min_dt == max_dt or isna(min_dt) or isna(max_dt):
+        raise ValueError("Not enough data in 'available'; at least two unique elements are required.")
+
+    if not (isinstance(min_dt, Timestamp) and isinstance(max_dt, Timestamp)):
+        # Enforce pandas types; we might have a numpy.datetime64
+        # (croniter 1.4.1 + numpy 1.25.2): croniter cannot handle numpy.datetime64
+        limits = Timestamp(min_dt), Timestamp(max_dt)
+
+    expanded_limits = expand_limits(limits, flex=flex)
+    return AvailableMetadata(available_retval, limits=limits, expanded_limits=expanded_limits)
+
+
+def _compute_data_limits(available: DatetimeIndexLike) -> LimitsTuple:
+    return handle_dask(available.min()), handle_dask(available.max())

time_split-0.1.0/src/time_split/_backend/_datetime_index_like.py

@@ -0,0 +1,19 @@
+from collections.abc import Iterable, Iterator
+from typing import Protocol, runtime_checkable
+
+from pandas import Series
+
+from ..types import DatetimeTypes
+
+
+@runtime_checkable
+class DatetimeIndexLike(Protocol, Iterable[DatetimeTypes]):
+    """A type that behaves (sort of) like a pandas DatetimeIndex."""
+
+    def __iter__(self) -> Iterator[DatetimeTypes]: ...
+
+    def value_counts(self) -> Series: ...
+
+    def min(self) -> DatetimeTypes: ...
+
+    def max(self) -> DatetimeTypes: ...

time_split-0.1.0/src/time_split/_backend/_limits.py

@@ -0,0 +1,151 @@
+from collections.abc import Iterable
+from itertools import starmap
+from typing import NamedTuple
+
+from pandas import Timedelta, Timestamp
+
+from ..settings import auto_flex
+from ..types import Flex, TimedeltaTypes
+
+LimitsTuple = tuple[Timestamp, Timestamp]
+LevelTuple = tuple[TimedeltaTypes, TimedeltaTypes, TimedeltaTypes]
+
+
+class _TimedeltaTuple(NamedTuple):
+    start_at: Timedelta
+    round_to: Timedelta
+    tolerance: Timedelta
+
+
+def expand_limits(limits: LimitsTuple, *, flex: Flex | LevelTuple | Iterable[LevelTuple] = "auto") -> LimitsTuple:
+    """Derive the `"real"` bounds of `limits`.
+
+    Args:
+        limits: A tuple ``(lo, hi)`` of timestamps.
+        flex: Flex arguments as described in the :ref:`User guide`. Also supports level-tuples
+            ``[(start_at, round_to, tolerance)...]``. Passing ``flex=[settings.auto_flex.day, settings.auto_flex.hour]``
+            is equivalent to ``flex='auto'``.
+
+    Returns:
+        Limits rounded according to the `flex`-argument.
+
+    Raises:
+        ValueError: For invalid limits.
+
+    Examples:
+        >>> from pandas import Timestamp
+        >>> limits = Timestamp("2019-05-11"), Timestamp("2019-05-11 22:05:30")
+
+        Basic usage.
+
+        >>> expand_limits(limits, flex="d")
+        (Timestamp('2019-05-11 00:00:00'), Timestamp('2019-05-12 00:00:00'))
+
+        You may specify a maximum "distance" that limits may be expanded.
+
+        >>> expand_limits(limits, flex="d<1h")
+        (Timestamp('2019-05-11 00:00:00'), Timestamp('2019-05-11 22:05:30'))
+
+        Limits will never be rounded in the "wrong" direction...
+
+        >>> limits = Timestamp("2019-05-11"), Timestamp("2019-05-11 11:05:30")
+        >>> expand_limits(limits, flex="d")
+        (Timestamp('2019-05-11 00:00:00'), Timestamp('2019-05-11 11:05:30'))
+
+        ...even if you make the tolerance large enough.
+
+        >>> expand_limits(limits, flex="d<14h")
+        (Timestamp('2019-05-11 00:00:00'), Timestamp('2019-05-11 11:05:30'))
+
+    """
+    if limits[0] >= limits[1]:
+        msg = f"Bad limits. Expected limits[1] > limits[0], but got {limits=}."
+        raise ValueError(msg)
+
+    if flex is False:
+        return limits
+
+    if flex is True or flex == "auto":
+        return _from_levels(limits)
+
+    if isinstance(flex, str):
+        round_to, _, tolerance = flex.partition("<")
+        level = _make_level(None, round_to=round_to.strip(), tolerance=tolerance.strip())
+        return _apply(limits, level=level)
+    if isinstance(flex, tuple):
+        return _from_levels(limits, levels=[_make_level(*flex)])
+
+    return _from_levels(limits, levels=starmap(_make_level, flex))
+
+
+def _from_levels(limits: LimitsTuple, *, levels: Iterable[_TimedeltaTuple] | None = None) -> LimitsTuple:
+    if levels is None:
+        levels = _levels_from_settings()
+    else:
+        levels = sorted(levels, reverse=True, key=lambda level: level[0])
+
+    lo, hi = limits
+    diff = hi - lo
+
+    for level in levels:
+        start_at, _round_to, _tolerance = level
+        if diff >= start_at:
+            return _apply(limits, level=level)
+
+    return limits
+
+
+def _apply(limits: LimitsTuple, *, level: _TimedeltaTuple) -> LimitsTuple:
+    lo, hi = limits
+
+    lo_floor = lo.floor(level.round_to)
+    if abs(lo_floor - lo) > level.tolerance:
+        return limits
+
+    hi_ceil = hi.ceil(level.round_to)
+    if abs(hi_ceil - hi) > level.tolerance:
+        return limits
+
+    if auto_flex.SANITY_CHECK:
+        if lo.round(level.round_to) != lo_floor:
+            return limits
+        if hi.round(level.round_to) != hi_ceil:
+            return limits
+
+    return lo_floor, hi_ceil
+
+
+def _levels_from_settings() -> list[_TimedeltaTuple]:
+    day, hour = _make_level(*auto_flex.day), _make_level(*auto_flex.hour)
+    if day.round_to != Timedelta(days=1):
+        msg = f"Invalid settings: {auto_flex.day=} must have round_to=1 day."
+        raise ValueError(msg)
+    if hour.round_to != Timedelta(hours=1):
+        msg = f"Invalid settings: {auto_flex.hour=} must have round_to=1 hour."
+        raise ValueError(msg)
+    return [day, hour]
+
+
+def _make_level(
+    start_at: TimedeltaTypes | None,
+    round_to: TimedeltaTypes,
+    tolerance: TimedeltaTypes,
+) -> _TimedeltaTuple:
+    start_at = Timedelta(start_at)  # Will be NaT if None, making all ifs False.
+    if start_at <= Timedelta(0):
+        raise ValueError(f"Bad {start_at=}; must be non-negative.")
+
+    try:
+        round_to = Timedelta(1, unit=round_to)
+    except ValueError as e:
+        raise ValueError(f"Got {round_to=}, which is not a valid frequency.") from e
+
+    tolerance = Timedelta(tolerance)
+    if tolerance <= Timedelta(0):
+        raise ValueError(f"Bad {tolerance=}; must be non-negative.")
+
+    if start_at < round_to:
+        raise ValueError(f"{start_at=} < {round_to=}")
+    if round_to < tolerance:
+        raise ValueError(f"{round_to=} < {tolerance=}")
+    return _TimedeltaTuple(start_at, round_to, tolerance)