time-split 0.1.0__py3-none-any.whl

time_split/settings.py

@@ -0,0 +1,172 @@
+"""Global settings for the splitting logic."""
+
+import typing as _t
+
+from . import types as _tst
+
+
+class auto_flex:  # noqa: N801
+    """Configuration for the `'auto'` :attr:`~time_split.types.Flex` logic.
+
+    This class determines how ``(lo, hi)``-tuples are expanded when flexible bounds are enabled.
+    """
+
+    SANITY_CHECK: bool = True
+    """If ``True``, use original limits if flexed limits do not pass sanity checks."""
+
+    @classmethod
+    def set_level(
+        cls,
+        level: _t.Literal["hour", "day"],
+        *,
+        start_at: _tst.TimedeltaTypes,
+        round_to: _tst.TimedeltaTypes,
+        tolerance: _tst.TimedeltaTypes,
+    ) -> None:
+        """Set a :class:`Level` used by the auto-flex logic.
+
+        Inputs are not verified until an actual split is made.
+
+        Args:
+            level: The level to set; `'hour'` or `'day'`.
+            start_at: Span size at which this level starts.
+            round_to: Frequency to round the range limits to.
+            tolerance: Maximum amount by which to alter limits.
+
+        Raises:
+            AttributeError: For unknown `level` names.
+
+        """
+        if level not in {"hour", "day"}:
+            raise AttributeError(f"Bad {level=}: Expected one of ('hour', 'day').")
+        level_tuple = (start_at, round_to, tolerance)
+        setattr(cls, level, level_tuple)
+
+    class Level(_t.NamedTuple):
+        """Level type used by :attr:`auto_flex`."""
+
+        start_at: _tst.TimedeltaTypes
+        """Span size at which this level starts."""
+
+        round_to: _tst.TimedeltaTypes
+        """Frequency to round the range limits to."""
+
+        tolerance: _tst.TimedeltaTypes
+        """Maximum amount by which to alter limits."""
+
+    hour: Level = Level("6 hours", "hour", "15 min")
+    """Conditions under which bounds are rounded to the nearest hour.
+
+    Default setting:
+        Round to hour if the total range is at least 6 hours, but do not move the bounds more than 15 minutes.
+    """
+
+    day: Level = Level("2 days", "day", "3 hours")
+    """Conditions under which bounds are rounded to the nearest day.
+
+    Default setting:
+        Round to day if the total range is at least 2 days, but do not move the bounds more than 3 hours.
+    """
+
+
+class plot:  # noqa: N801
+    """Global settings for the :func:`.time_split.plot`-function."""
+
+    THOUSANDS_SEPARATOR: str = "'"
+    """Separator to use when printing `bar_labels`."""
+    THOUSANDS_SEPARATOR_CUTOFF: int = 10_000
+    """Minimum value before `bar_labels` include a :attr:`THOUSANDS_SEPARATOR`."""
+    ROW_UNIT: str = "rows"
+    """Unit to append to the count when displaying number of rows on the bars."""
+
+    DATA_LABEL: str = "Data"
+    """Label of the blue bar; data in the the [:attr:`~.DatetimeSplitBounds.start`, :attr:`~.types.DatetimeSplitBounds.mid`)-range."""
+    FUTURE_DATA_LABEL: str = "Future data"
+    """Label of the red bar; data in the the [:attr:`~.DatetimeSplitBounds.mid`, :attr:`~.types.DatetimeSplitBounds.end`)-range."""
+
+    DEFAULT_TIME_UNIT: str = "h"
+    """Time unit to use by default when ``bar_labels=True`` and ``available=None``."""
+
+    REMOVED_FOLD_STYLE: _t.ClassVar[dict[str, _t.Any]] = {
+        "alpha": 0.35,
+        "height": 0.6,
+    }
+    """Keyword arguments used to distinguish filtered folds when plotting with ``show_removed=True``.
+
+    See :func:`matplotlib.pyplot.bar` for details.
+    """
+
+
+class log_split_progress:  # noqa: N801
+    """Global settings for the :func:`.log_split_progress`-function."""
+
+    FOLD_FORMAT: str = "'{start.auto}' <= [schedule: '{mid.auto}' ({mid:%A})] < '{end.auto}'"
+    """Pretty-printed `fold`-key for other messages.
+
+    * Only the ``start``, ``mid``, and ``end`` keys are available (see
+      :attr:`~time_split.types.DatetimeSplitBounds`). You may use ``<key>.auto`` to format as a date when
+      time is zero (this is the default).
+
+    .. code-block:: python
+       :caption: Sample output.
+
+       '2021-12-30' <= [schedule: '2022-01-04' (Tuesday)] < '2022-01-04 18:00:00'
+    """
+
+    SECONDS_FORMATTER: str | _t.Callable[[float], str] = "rics.performance.format_seconds"
+    """A callable ``(seconds) -> formatted_seconds``.
+
+    Both ``seconds`` and ``formatted_seconds`` will be available to the :attr:`END_MESSAGE` message. If a string is
+    given, the actual callable will be resolved using :func:`rics.misc.get_by_full_name`.
+    """
+
+    START_MESSAGE: str = "Begin fold {n}/{n_splits}: {fold}."
+    """Message indicating that the current fold has been yielded to the user.
+
+    Has access to all keys from the previous section, as well as:
+
+    * The ``fold`` key (see :attr:`FOLD_FORMAT`), and
+    * The ``n`` key, which is the 1-based position of the fold in `splits`, and
+    * The ``n_folds`` key, which is just ``len(splits)``.
+
+    .. code-block:: python
+       :caption: Sample output.
+
+        Begin fold 5/7: '2021-12-30' <= [schedule: '2022-01-04' (Tuesday)] < '2022-01-04 18:00:00'.
+    """
+
+    END_MESSAGE: str = "Finished fold {n}/{n_splits}: [schedule: '{mid.auto}' ({mid:%A})] after {formatted_seconds}."
+    """Message indicating that the user is done with the current fold.
+
+    Has access to all keys from the previous sections, as well as:
+
+    * The ``seconds`` key, which is the (fractional) time the user spent in the fold, and
+    * The ``formatted_seconds`` key, obtained using the :attr:`SECONDS_FORMATTER`.
+
+    The value of ``seconds`` is obtained using :py:func:`time.perf_counter`.
+
+    .. code-block:: python
+       :caption: Sample output.
+
+        Finished fold 5/7: [schedule: '2022-01-04' (Tuesday)] after 5m 21s.
+    """
+
+    AUTO_DATE_FORMAT = "%Y-%m-%d"
+    """Short-form timestamp format_spec used by ``<key>.auto``."""
+    AUTO_DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S"
+    """Long-form timestamp format_spec used by ``<key>.auto``."""
+
+
+class misc:  # noqa: N801
+    """Miscellaneous settings that don't fit in any other namespace."""
+
+    snap_to_end: bool = True
+    """Controls alignment of timedelta-based splits.
+
+    .. note::
+
+       Active only when both `schedule` and `after` are :attr:`~time_split.types.TimedeltaTypes`.
+
+    If ``True``, ensure that the `Future data` of the final fold ends at the rightmost edge of the available data range.
+    Otherwise, alignment is determined by :func:`pandas.date_range`.
+    """

time_split/support/__init__.py

@@ -0,0 +1,21 @@
+"""Supporting functions.
+
+These functions are used internally, but are exposed here as well so that user may create their own logic using the
+internal logic, or just to test things out.
+
+.. warning::
+
+   Not part of the stable API.
+
+This module may change without notice. Stick to the top-level :mod:`time_split`-module, or lock down your
+dependencies if you need to use the ``support`` module.
+"""
+
+from .._backend import expand_limits
+from .._frontend import fold_weight, to_string
+
+__all__ = [
+    "expand_limits",
+    "fold_weight",
+    "to_string",
+]

time_split/types.py

@@ -0,0 +1,61 @@
+"""Types related to splitting data."""
+
+import datetime as _dt
+import typing as _t
+
+import numpy as _np
+import pandas as _pd
+
+DatetimeTypes: _t.TypeAlias = str | _pd.Timestamp | _dt.datetime | _dt.date | _np.datetime64
+"""Types that may be cast to :class:`pandas.Timestamp`."""
+DatetimeIterable = _t.Iterable[DatetimeTypes]
+"""Iterable that may be cast to :class:`pandas.DatetimeIndex`."""
+TimedeltaTypes: _t.TypeAlias = str | _pd.Timedelta | _dt.timedelta | _np.timedelta64
+"""Types that may be cast to :class:`pandas.Timedelta`."""
+
+Schedule: _t.TypeAlias = _pd.DatetimeIndex | DatetimeIterable | TimedeltaTypes
+"""User schedule type."""
+Span = int | _t.Literal["all"] | TimedeltaTypes
+"""User span type. Used to determine limits from the timestamps given by a :attr:`Schedule`."""
+Flex = bool | _t.Literal["auto"] | str
+"""Flexibility frequency string for ``floor/ceil``. Pass ``False`` to disable."""
+
+
+class DatetimeSplitBounds(_t.NamedTuple):
+    """A 3-tuple which denotes two adjacent datetime ranges."""
+
+    start: _pd.Timestamp
+    """Left (inclusive) limit of the `data` range."""
+    mid: _pd.Timestamp
+    """Schedule timestamp.
+
+    Right (exclusive) limit of the `data` range, left (inclusive) limit of the `future_data` range.
+    """
+    end: _pd.Timestamp
+    """Right (exclusive) limit of the `future_data` range."""
+
+
+DatetimeSplits = list[DatetimeSplitBounds]
+"""A list of bounds."""
+
+
+class DatetimeSplitCounts(_t.NamedTuple):
+    """Relative importance of `data` and `future_data`."""
+
+    data: int
+    future_data: int
+
+
+class DatetimeIndexSplitterKwargs(_t.TypedDict, total=False):
+    """Keyword arguments for creating a ``DatetimeIndexSplitter``.
+
+    The ``DatetimeIndexSplitter`` is the backing type for all splitting logic. It is not exposed directly to users. See
+    :func:`.split` or one of the related functions for user-facing APIs.
+    """
+
+    schedule: _t.Required[Schedule]
+    before: Span
+    after: Span
+    step: int
+    n_splits: int | None
+    flex: Flex

time_split-0.1.0.dist-info/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,34 @@
+time_split/__init__.py,sha256=YIxnXXfGGTQaxqfCEOn4wD_jUS8PO2JWte62VZCkmao,352
+time_split/_backend/__init__.py,sha256=OBFqNCcJgiDzumVbpY0nxLuxPGnWiKbW02O8Ha-7U8E,134
+time_split/_backend/_available.py,sha256=S-IrxxMI6y9r3gke0wqTW2p22b8mgJrmfVGS8LFdZnw,2204
+time_split/_backend/_datetime_index_like.py,sha256=vFG49rURPFR72RufIjE-uzu3EuJzGsMooTcx7cNI_0U,487
+time_split/_backend/_limits.py,sha256=DY28rOcs5zsvZib-4pAKb43DsOtudiESvBya5NuxK-8,4930
+time_split/_backend/_schedule.py,sha256=cQ6wesTqBd6-Qz8HRChaec0EAQmRvPslJy-l_ZDTYf4,2643
+time_split/_backend/_span.py,sha256=Sdug-PBgbxupYQ57yfIAgu7oM2I41ySfbLuZjFsDDB8,3744
+time_split/_backend/_splitter.py,sha256=NtZAeLQEjwErjINMshx_xDWbIUSz2PNG-ALqW_NP7es,5654
+time_split/_docstrings.py,sha256=v2pZFgUTFvN0ulo6SnW8oiqMJDXBTVnzPwCB_g58dpo,1506
+time_split/_frontend/__init__.py,sha256=ncT_tl17smoSLbtwS61uDpNrHZ7KuwGz0_8hJn5Y-tY,261
+time_split/_frontend/_plot.py,sha256=5QqqGlBKBRDO5jQlU3K_G8rYOp_ccU374jlaYqN_Hb4,11885
+time_split/_frontend/_progress.py,sha256=ApCLHWfHgbEvfdhuV35TdqEzOlO4UqpWO_xKap1JlI8,5087
+time_split/_frontend/_split.py,sha256=zQbfj_kYdrmZVQoL3Ft7_H7IzUtX7A-I-J5y66P-Gx8,1099
+time_split/_frontend/_to_string.py,sha256=7j2Z8fTHaytHyBDE5nh5Mv-WB-nYGg2DHqSwgX0f2kM,3001
+time_split/_frontend/_weight.py,sha256=fMdPGyoa_CA5rm57IRyiZfOQLLMQEcdvumDtABwjdIA,2163
+time_split/_support.py,sha256=gWrcpDrP56g-fVixk7Y8hxDmtDh-VGSLFAAus3tIuQ4,420
+time_split/integration/__init__.py,sha256=adBO6ilCz0sw4mdtMroaMeLY9eXE-uN1dCloI3R8f5I,62
+time_split/integration/_log_progress.py,sha256=B82bV0RfS5QIHz1B_aUfqXu7DTKSWtBdvaQDBsgATX8,953
+time_split/integration/pandas/__init__.py,sha256=3QTqzKhfITgeKnU-Tv0RTM_oHYFr4YoRoSZCu6Z4uYI,1808
+time_split/integration/pandas/_impl.py,sha256=o2Gc1xi1GguyvWFM8hhdYM22sfbqDu9M_2qmG6wahdk,2800
+time_split/integration/polars/__init__.py,sha256=bxt_RPoGhIR6G8ODuf3vcDc0PL58OqBnvMRX74co7dY,2424
+time_split/integration/polars/_impl.py,sha256=eflPt9OD0U5hW4DWl4qZYb73kucR_XGFTS3Skz-JxcM,1890
+time_split/integration/sklearn/__init__.py,sha256=mwnC9QeV1byp4ZGQ2ser_4v-IbIyUhwzufGev6M5U64,131
+time_split/integration/sklearn/_impl.py,sha256=CKINnKf8ejoTBqRFWnRdEYAX59OtY4UI8mWuuz3bibg,5721
+time_split/integration/split_data.py,sha256=flwoJlckiBHbJBqTvCsnQDHJojUNuyeAiS61QkIjogo,2550
+time_split/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+time_split/settings.py,sha256=4JJ6BcMzxFe1Qf4igIhYzE-y_Dx4As4cS1xbjiDQkg8,6331
+time_split/support/__init__.py,sha256=a9-Zej4r3RDFGXNwwguHVFMvlxRv2ns0f-iiFic7zWs,556
+time_split/types.py,sha256=AHnF3wXx1jixKXxZ83i6p5iZKdp12W7ftSqWl4SSd4A,2002
+time_split-0.1.0.dist-info/LICENSE.md,sha256=HZP0m1lF3DaHOdzWCEVmWW9QWIIdS7Gne8j2ApIq19c,1077
+time_split-0.1.0.dist-info/METADATA,sha256=Yf9F5TC8t4VQsxETxZQauZcK0vBvu6fY1G4Hddm4xiI,4569
+time_split-0.1.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+time_split-0.1.0.dist-info/entry_points.txt,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+time_split-0.1.0.dist-info/RECORD,,

time_split-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any