time-split 0.1.0__tar.gz → 0.2.0__tar.gz

{time_split-0.1.0 → time_split-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: time-split
-Version: 0.1.0
-Summary: My personal little ML engineering library.
+Version: 0.2.0
+Summary: Time-based k-fold validation splits for heterogeneous data.
 Home-page: https://github.com/rsundqvist/time-split
 Author: Richard Sundqvist
 Author-email: richard.sundqvist@live.se
@@ -30,7 +30,7 @@ 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.
+Time-based 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)
@@ -46,12 +46,12 @@ Flexible k-fold validation splits for heterogeneous data.
   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
+Folds plotted 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.
+A library for creating time-based 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, 

{time_split-0.1.0 → time_split-0.2.0}/README.md

@@ -1,5 +1,5 @@
 # Time Split  <!-- omit in toc -->
-Flexible k-fold validation splits for heterogeneous data.
+Time-based 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)
@@ -15,12 +15,12 @@ Flexible k-fold validation splits for heterogeneous data.
   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
+Folds plotted 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.
+A library for creating time-based 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, 

{time_split-0.1.0 → time_split-0.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "time-split"
-version = "0.1.0"
-description = "My personal little ML engineering library."
+version = "0.2.0"
+description = "Time-based k-fold validation splits for heterogeneous data."
 authors = ["Richard Sundqvist <richard.sundqvist@live.se>"]
 
 readme = "README.md"

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/__init__.py

@@ -1,4 +1,4 @@
-"""Create temporal k-folds for cross-validation with heterogeneous data."""
+"""Time-based k-fold validation splits for heterogeneous data."""
 
 import logging as _logging
 
@@ -11,6 +11,6 @@ __all__ = [
     "__version__",  # Make MyPy happy
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 _logging.getLogger(__name__).addHandler(_logging.NullHandler())

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

@@ -0,0 +1,12 @@
+from ._datetime_index_like import DatetimeIndexLike
+from ._limits import expand_limits
+from ._process_available import ProcessAvailableResult, process_available
+from ._splitter import DatetimeIndexSplitter
+
+__all__ = [
+    "DatetimeIndexLike",
+    "DatetimeIndexSplitter",
+    "ProcessAvailableResult",
+    "process_available",
+    "expand_limits",
+]

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/_backend/_datetime_index_like.py

@@ -8,7 +8,7 @@ from ..types import DatetimeTypes
 
 @runtime_checkable
 class DatetimeIndexLike(Protocol, Iterable[DatetimeTypes]):
-    """A type that behaves (sort of) like a pandas DatetimeIndex."""
+    """A type that behaves (sort of) like a :class:`pandas.DatetimeIndex`."""
 
     def __iter__(self) -> Iterator[DatetimeTypes]: ...
 

time_split-0.1.0/src/time_split/_backend/_available.py → time_split-0.2.0/src/time_split/_backend/_process_available.py

@@ -8,15 +8,15 @@ from ._datetime_index_like import DatetimeIndexLike
 from ._limits import LimitsTuple, expand_limits
 
 
-class AvailableMetadata(NamedTuple):
-    """Output of :func:`process_available`."""
+class ProcessAvailableResult(NamedTuple):
+    """Output of :func:`.process_available`."""
 
     available_as_index: DatetimeIndexLike | None
     limits: LimitsTuple
     expanded_limits: LimitsTuple
 
 
-def process_available(available: DatetimeIterable, *, flex: Flex) -> AvailableMetadata:
+def process_available(available: DatetimeIterable, *, flex: Flex) -> ProcessAvailableResult:
     """Process a user-given `available` argument.
 
     Args:
@@ -50,7 +50,7 @@ def process_available(available: DatetimeIterable, *, flex: Flex) -> AvailableMe
         limits = Timestamp(min_dt), Timestamp(max_dt)
 
     expanded_limits = expand_limits(limits, flex=flex)
-    return AvailableMetadata(available_retval, limits=limits, expanded_limits=expanded_limits)
+    return ProcessAvailableResult(available_retval, limits=limits, expanded_limits=expanded_limits)
 
 
 def _compute_data_limits(available: DatetimeIndexLike) -> LimitsTuple:

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/_backend/_schedule.py

@@ -3,8 +3,8 @@ from typing import NamedTuple, cast, get_args
 from pandas import DatetimeIndex, NaT, Timedelta, Timestamp, date_range
 
 from ..types import DatetimeIterable, Flex, Schedule, TimedeltaTypes
-from ._available import AvailableMetadata, process_available
 from ._limits import LimitsTuple
+from ._process_available import ProcessAvailableResult, process_available
 
 NO_LIMITS = cast(LimitsTuple, (NaT, NaT))
 
@@ -13,7 +13,7 @@ class MaterializedSchedule(NamedTuple):
     """An explicit schedule."""
 
     schedule: DatetimeIndex
-    available_metadata: AvailableMetadata
+    available_metadata: ProcessAvailableResult
 
 
 def materialize_schedule(
@@ -24,7 +24,7 @@ def materialize_schedule(
         try:
             return MaterializedSchedule(
                 DatetimeIndex(schedule),
-                available_metadata=AvailableMetadata(None, NO_LIMITS, NO_LIMITS),
+                available_metadata=ProcessAvailableResult(None, NO_LIMITS, NO_LIMITS),
             )
         except TypeError as e:
             raise ValueError("Schedule must be explicit when not bounded by an available range.") from e

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/_backend/_splitter.py

@@ -26,13 +26,13 @@ LOGGER = logging.getLogger("time_split")
 
 @dataclass(frozen=True)
 class DatetimeIndexSplitter:
-    """Backend interface for splitting user data."""
+    """Backend interface for splitting user data. See the :ref:`Parameter overview` page."""
 
     schedule: Schedule
     before: Span
     after: Span
     step: int
-    n_splits: int | None
+    n_splits: int
     flex: Flex
 
     def get_splits(self, available: DatetimeIterable | None = None) -> DatetimeSplits:
@@ -115,10 +115,10 @@ class DatetimeIndexSplitter:
             splits = [s for i, s in enumerate(reversed(splits)) if i % step == 0]
             splits.reverse()
 
-        if self.n_splits:
+        if self.n_splits > 0:
             splits = splits[-self.n_splits :]
 
-        if self.step < 0:
+        if self.step < 0:  # Poorly documented - might not work as expected?
             splits.reverse()
 
         return splits
@@ -147,8 +147,8 @@ class DatetimeIndexSplitter:
 
     def __post_init__(self) -> None:
         # Verify n_splits
-        if self.n_splits is not None and self.n_splits < 1:
-            raise ValueError(f"Expected n_splits >= 1, but got n_splits={self.n_splits!r}.")
+        if self.n_splits < 0:
+            raise ValueError(f"Expected n_splits >= 0, but got n_splits={self.n_splits!r}.")
 
         # Verify before/after
         to_strict_span(self.before, name="before")

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/_docstrings.py

@@ -21,7 +21,7 @@ _SPAN = (
     f"or `'all'` (requires `available` data)."
 )
 _DOCSTRINGS = {
-    "schedule": f"A collection of timestamps, a {_OFFSET}, or a cron expression.",
+    "schedule": f"A :attr:`~time_split.types.DatetimeIterable`, {_OFFSET}, or `cron <https://pypi.org/project/croniter/>`_ expression.",
     "before": _SPAN.format(arg="before"),
     "after": _SPAN.format(arg="after"),
     "step": "Select a subset of folds, preferring folds later in the schedule.",

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/_frontend/_plot.py

@@ -1,4 +1,4 @@
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, replace
 from typing import TYPE_CHECKING, Any, Literal
 
 import pandas as pd
@@ -62,7 +62,7 @@ def plot(
     before: Span = "7d",
     after: Span = 1,
     step: int = 1,
-    n_splits: int | None = None,
+    n_splits: int = 0,
     available: DatetimeIterable | None = None,
     flex: Flex = "auto",
     # Split plot args
@@ -283,10 +283,7 @@ def _get_plot_data(
 
     if show_removed:
         kept_splits = set(splits)
-        kwargs = asdict(splitter)  # Can't use dataclasses.replace: 3.10+ only
-        kwargs["n_splits"] = None
-        kwargs["step"] = 1
-        splits = DatetimeIndexSplitter(**kwargs).get_plot_data(available)[0]
+        splits = replace(splitter, n_splits=0, step=1).get_plot_data(available)[0]
         if splitter.step < 0:
             splits.reverse()
         removed = set(splits) - set(kept_splits)

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/_frontend/_split.py

@@ -10,7 +10,7 @@ def split(
     before: Span = "7d",
     after: Span = 1,
     step: int = 1,
-    n_splits: int | None = None,
+    n_splits: int = 0,
     available: DatetimeIterable | None = None,
     flex: Flex = "auto",
 ) -> DatetimeSplits:

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/integration/sklearn/_impl.py

@@ -57,7 +57,7 @@ class ScikitLearnSplitter(BaseCrossValidator):  # type: ignore[misc]
         *,
         before: Span = "7d",
         after: Span = 1,
-        n_splits: int | None = None,
+        n_splits: int = 0,
         flex: Flex = "auto",
         step: int = 1,
         log_progress: LogProgressArg = False,

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/integration/split_data.py

@@ -6,14 +6,18 @@ Users may implement splitting of any data type by implementing suitable ``as_ava
 import typing as _t
 from datetime import datetime as _datetime
 
-from .. import _frontend, types
+from .. import _frontend
+from .. import types as _tst
 from .._docstrings import docs as _docs
 from . import _log_progress
 
+if _t.TYPE_CHECKING:
+    import pandas
+
 DataT = _t.TypeVar("DataT")
 """Type of data to split."""
 
-DataAsAvailableFn = _t.Callable[[DataT], types.DatetimeIterable]
+DataAsAvailableFn = _t.Callable[[DataT], _tst.DatetimeIterable]
 """A callable ``(data: DataT) -> DatetimeIterable``."""
 DataSelectFn = _t.Callable[[DataT, _datetime, _datetime], DataT]
 """A callable ``(data: DataT, left_inclusive: datetime, end_exclusive: datetime) -> DataT)``."""
@@ -23,12 +27,23 @@ class DatetimeSplit(_t.NamedTuple, _t.Generic[DataT]):
     """Time-based split of a generic data type."""
 
     data: DataT
-    """Data before ``bounds.mid``."""
+    """Data before the simulated :attr:`training_date`.
+
+    Bounded by `bounds.start <= time(future_data) < bounds.mid`.
+    """
     future_data: DataT
-    """Data after ``bounds.mid``."""
-    bounds: types.DatetimeSplitBounds
+    """Data after the simulated :attr:`training_date`.
+
+    Bounded by `bounds.mid <= time(future_data) < bounds.end`.
+    """
+    bounds: _tst.DatetimeSplitBounds
     """The underlying bounds that produced this split."""
 
+    @property
+    def training_date(self) -> "pandas.Timestamp":
+        """Returns the simulated training date (alias of :attr:`self.bounds.mid <.DatetimeSplitBounds.mid>`)."""
+        return self.bounds.mid
+
 
 @_docs
 def split_data(
@@ -37,7 +52,7 @@ def split_data(
     log_progress: _log_progress.LogProgressArg = False,
     as_available: DataAsAvailableFn[DataT],
     select: DataSelectFn[DataT],
-    **kwargs: _t.Unpack[types.DatetimeIndexSplitterKwargs],
+    **kwargs: _t.Unpack[_tst.DatetimeIndexSplitterKwargs],
 ) -> _t.Iterable[DatetimeSplit[DataT]]:
     """Base implementation for splitting integrated `data` types.
 

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/support/__init__.py

@@ -11,11 +11,13 @@ This module may change without notice. Stick to the top-level :mod:`time_split`-
 dependencies if you need to use the ``support`` module.
 """
 
-from .._backend import expand_limits
+from .._backend import DatetimeIndexSplitter, expand_limits, process_available
 from .._frontend import fold_weight, to_string
 
 __all__ = [
+    "DatetimeIndexSplitter",
     "expand_limits",
+    "process_available",
     "fold_weight",
     "to_string",
 ]

time_split-0.2.0/src/time_split/support/types.py

@@ -0,0 +1,11 @@
+"""Internal types."""
+
+from time_split._backend._schedule import MaterializedSchedule
+
+from .._backend import DatetimeIndexLike, ProcessAvailableResult
+
+__all__ = [
+    "DatetimeIndexLike",
+    "MaterializedSchedule",
+    "ProcessAvailableResult",
+]

{time_split-0.1.0 → time_split-0.2.0}/src/time_split/types.py

@@ -30,6 +30,9 @@ class DatetimeSplitBounds(_t.NamedTuple):
     """Schedule timestamp.
 
     Right (exclusive) limit of the `data` range, left (inclusive) limit of the `future_data` range.
+
+    When using :mod:`.integration` functions, These are available as :attr:`.DatetimeSplit.data` and
+    :attr:`.DatetimeSplit.future_data`, respectively.
     """
     end: _pd.Timestamp
     """Right (exclusive) limit of the `future_data` range."""
@@ -49,13 +52,13 @@ class DatetimeSplitCounts(_t.NamedTuple):
 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.
+    The :class:`time_split.support.DatetimeIndexSplitter` is the backend implementation for the splitting logic. In most
+    cases, it should not be used directly. 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
+    n_splits: int
     flex: Flex

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

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