time-split 0.7.0__tar.gz → 1.0.0__tar.gz

{time_split-0.7.0 → time_split-1.0.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.3
 Name: time-split
-Version: 0.7.0
+Version: 1.0.0
 Summary: Time-based k-fold validation splits for heterogeneous data.
 License: MIT
 Keywords: hyper,parameter,optimization,cross,validation,time,temporal,heterogenous,data
 Author: Richard Sundqvist
 Author-email: richard.sundqvist@live.se
 Requires-Python: >=3.11
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: POSIX :: Linux
@@ -28,7 +28,7 @@ Requires-Dist: matplotlib ; extra == "plotting"
 Requires-Dist: pandas (>=2.0.3)
 Requires-Dist: rics (>=6.0.1)
 Requires-Dist: seaborn ; extra == "plotting"
-Requires-Dist: time-split-app ; extra == "app"
+Requires-Dist: time-split-app (>=1.0.0) ; extra == "app"
 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
@@ -93,6 +93,9 @@ in the terminal. You may use
 [`create_explorer_link()`](https://time-split.readthedocs.io/en/stable/api/time_split.app.html#time_split.app.create_explorer_link)
 to build application URLs with preselected splitting parameters.
 
+Click [here](https://time-split.readthedocs.io/en/stable/api/time_split.app.reexport.html) for documentation of the most
+important types, functions and classes used by the application.
+
 ## Installation
 The package is published through the [Python Package Index (PyPI)]. Source code
 is available on GitHub: https://github.com/rsundqvist/time-split

{time_split-0.7.0 → time_split-1.0.0}/README.md

@@ -55,6 +55,9 @@ in the terminal. You may use
 [`create_explorer_link()`](https://time-split.readthedocs.io/en/stable/api/time_split.app.html#time_split.app.create_explorer_link)
 to build application URLs with preselected splitting parameters.
 
+Click [here](https://time-split.readthedocs.io/en/stable/api/time_split.app.reexport.html) for documentation of the most
+important types, functions and classes used by the application.
+
 ## Installation
 The package is published through the [Python Package Index (PyPI)]. Source code
 is available on GitHub: https://github.com/rsundqvist/time-split

{time_split-0.7.0 → time_split-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "time-split"
-version = "0.7.0"
+version = "1.0.0"
 description = "Time-based k-fold validation splits for heterogeneous data."
 authors = [
     { name = "Richard Sundqvist", email = "richard.sundqvist@live.se" },
@@ -9,7 +9,7 @@ license = { text = "MIT" }
 readme = "README.md"
 keywords = ["hyper", "parameter", "optimization", "cross", "validation", "time", "temporal", "heterogenous", "data"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: Science/Research",
     "Operating System :: POSIX :: Linux",
@@ -32,7 +32,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-app = ["click", "time-split-app"]  # Constraints managed by app.
+app = ["click", "time-split-app >= 1.0.0"]
 plotting = ["matplotlib", "seaborn"]
 
 [project.urls]

{time_split-0.7.0 → time_split-1.0.0}/src/time_split/__init__.py

@@ -11,6 +11,6 @@ __all__ = [
     "split",
 ]
 
-__version__ = "0.7.0"
+__version__ = "1.0.0"
 
 _logging.getLogger(__name__).addHandler(_logging.NullHandler())

{time_split-0.7.0 → time_split-1.0.0}/src/time_split/_backend/_splitter.py

@@ -2,7 +2,7 @@ from dataclasses import asdict, dataclass
 from typing import cast, get_args
 
 from pandas import Timedelta
-from rics.misc import format_kwargs
+from rics.misc import format_kwargs, get_by_full_name
 
 from ..settings import misc as settings
 from ..types import (
@@ -11,6 +11,7 @@ from ..types import (
     DatetimeSplitBounds,
     DatetimeSplits,
     ExpandLimits,
+    Filter,
     Schedule,
     Span,
     TimedeltaTypes,
@@ -30,6 +31,7 @@ class DatetimeIndexSplitter:
     n_splits: int = 0
     expand_limits: ExpandLimits = "auto"
     ignore_filters: bool = False
+    filter: Filter | str | None = None
 
     def get_splits(self, available: DatetimeIterable | None = None) -> DatetimeSplits:
         """Compute a split of given user data."""
@@ -115,10 +117,14 @@ class DatetimeIndexSplitter:
         if self.step < 0:  # Poorly documented - might not work as expected?
             splits.reverse()
 
-        if settings.filter is None:
+        filter = self.filter
+        if filter is None:
             return splits
 
-        return [s for s in splits if settings.filter(*s)]
+        if isinstance(filter, str):
+            filter = cast(Filter, get_by_full_name(filter))
+
+        return [s for s in splits if filter(*s)]
 
     def __post_init__(self) -> None:
         # Verify n_splits

{time_split-0.7.0 → time_split-1.0.0}/src/time_split/_docstrings.py

@@ -30,7 +30,8 @@ _DOCSTRINGS = {
     "n_splits": "Maximum number of folds, preferring folds later in the schedule.",
     "available": "Binds `schedule` to a range.",
     "expand_limits": f'A {_OFFSET} used to expand `available` data to its likely `"true"` limits. Pass ``False`` to disable.',
-    "ignore_filters": "Set to ignore filtering parameters (e.g. `step`) and global configuration.",
+    "filter": "A callable ``(start, mid, end) -> bool`` applied to each fold. Strings are converted using :func:`~rics.misc.get_by_full_name`.",
+    "ignore_filters": "Set to ignore filtering parameters (e.g. `step` and `filter`).",
     "USER_GUIDE": (
         "For more information about the `schedule`, `before/after` and `expand_limits`-arguments"
         ", see the :ref:`User guide`."

{time_split-0.7.0 → time_split-1.0.0}/src/time_split/_frontend/_plot.py

@@ -18,6 +18,7 @@ from ..types import (
     DatetimeSplitBounds,
     DatetimeSplits,
     ExpandLimits,
+    Filter,
     Schedule,
     Span,
 )
@@ -67,6 +68,7 @@ def plot(
     n_splits: int = 0,
     available: DatetimeIterable | pd.DataFrame | pd.Series | None = None,
     expand_limits: ExpandLimits = "auto",
+    filter: Filter | str | None = None,
     ignore_filters: bool = False,
     # Split plot args
     bar_labels: str | Rows | list[tuple[str, str]] | bool = True,
@@ -88,6 +90,7 @@ def plot(
         available: {available} If `bar_labels` is given but is not a ``list``,
             this data will be used to compute fold sizes.
         expand_limits: {expand_limits}
+        filter: {filter}
         ignore_filters: {ignore_filters}
         bar_labels: Labels to draw on the bars. If you pass a string, it will be interpreted as a time unit (see
             :ref:`pandas:timeseries.offset_aliases` for valid frequency strings). Bars will show the number of units
@@ -128,6 +131,7 @@ def plot(
         step=step,
         n_splits=n_splits,
         expand_limits=expand_limits,
+        filter=filter,
         ignore_filters=ignore_filters,
     )
 

{time_split-0.7.0 → time_split-1.0.0}/src/time_split/_frontend/_progress.py

@@ -1,27 +1,35 @@
 import logging
-from collections.abc import Callable, Iterable, MutableMapping, Sequence
+from collections.abc import Callable, Iterator, MutableMapping, Sequence
 from dataclasses import dataclass
 from time import perf_counter
-from typing import Any, Generic
+from typing import Any, Generic, overload
 
 import pandas as pd
 from rics.collections.dicts import flatten_dict
 from rics.strings import format_seconds as fmt_sec
 
 from ..settings import log_split_progress as settings
-from ..types import DatetimeSplitBounds, FormatMetrics, GetMetrics, LoggerArg, MetricsType, SplitProgressExtras
+from ..types import (
+    DatetimeSplitBounds,
+    FormatMetrics,
+    GetMetrics,
+    LogSplitProgress,
+    LogSplitProgressLoggerArg,
+    MetricsType,
+    SplitProgressExtras,
+)
 from ._to_string import _PrettyTimestamp
 
 
 def log_split_progress(
     splits: Sequence[DatetimeSplitBounds],
     *,
-    logger: LoggerArg = "time_split",
+    logger: LogSplitProgressLoggerArg = "time_split",
     start_level: int = logging.INFO,
     end_level: int = logging.INFO,
     extra: dict[str, Any] | None = None,
     get_metrics: GetMetrics[MetricsType] | None = None,
-) -> Iterable[DatetimeSplitBounds]:
+) -> LogSplitProgress:
     """Log iteration progress.
 
     Args:
@@ -40,7 +48,7 @@ def log_split_progress(
             :attr:`fold-end message <.settings.log_split_progress.END_MESSAGE>` as-is.
 
     Returns:
-        An iterable over `splits`.
+        A :class:`.LogSplitProgress` object.
 
     Examples:
         Configuring the `logger` name and
@@ -89,7 +97,8 @@ def log_split_progress(
         # Backport of https://github.com/python/cpython/pull/107292
         logger = _MergingLoggerAdapter(logger.logger, logger.extra)
 
-    track = _ProgressTracker(
+    return _ProgressTracker(
+        splits,
         logger=logger,
         fold_format=settings.FOLD_FORMAT,
         start_level=start_level,
@@ -101,11 +110,11 @@ def log_split_progress(
         get_metrics=get_metrics,
         format_metrics=settings.FORMAT_METRICS or default_metrics_formatter,
     )
-    return track(splits)
 
 
 @dataclass(frozen=True)
-class _ProgressTracker(Generic[MetricsType]):
+class _ProgressTracker(LogSplitProgress, Generic[MetricsType]):
+    splits: Sequence[DatetimeSplitBounds]
     logger: logging.Logger | logging.LoggerAdapter  # type: ignore[type-arg]
     fold_format: str
     start_level: int
@@ -117,13 +126,23 @@ class _ProgressTracker(Generic[MetricsType]):
     get_metrics: GetMetrics[MetricsType] | None
     format_metrics: FormatMetrics[MetricsType]
 
-    def __call__(self, splits: Sequence[DatetimeSplitBounds]) -> Iterable[DatetimeSplitBounds]:
-        n_splits = len(splits)
+    @overload
+    def __getitem__(self, index: int) -> DatetimeSplitBounds: ...
 
-        for n, split in enumerate(splits, start=1):
+    @overload
+    def __getitem__(self, index: slice) -> Sequence[DatetimeSplitBounds]: ...
+
+    def __getitem__(self, index: int | slice) -> DatetimeSplitBounds | Sequence[DatetimeSplitBounds]:
+        return self.splits[index]
+
+    def __len__(self) -> int:
+        return len(self.splits)
+
+    def __iter__(self) -> Iterator[DatetimeSplitBounds]:
+        for n, split in enumerate(self.splits, start=1):
             default_extras = SplitProgressExtras[MetricsType](
                 n=n,
-                n_splits=n_splits,
+                n_splits=len(self.splits),
                 start=split.start.isoformat(),
                 mid=split.mid.isoformat(),
                 end=split.end.isoformat(),
@@ -131,7 +150,7 @@ class _ProgressTracker(Generic[MetricsType]):
             extra = {**self.user_extra, **default_extras}
             kwargs: dict[str, Any] = dict(
                 n=n,
-                n_splits=n_splits,
+                n_splits=len(self.splits),
                 start=_PrettyTimestamp(split.start),
                 mid=_PrettyTimestamp(split.mid),
                 end=_PrettyTimestamp(split.end),

{time_split-0.7.0 → time_split-1.0.0}/src/time_split/_frontend/_split.py

@@ -1,6 +1,6 @@
 from .._backend import DatetimeIndexSplitter
 from .._docstrings import docs
-from ..types import DatetimeIterable, DatetimeSplits, ExpandLimits, Schedule, Span
+from ..types import DatetimeIterable, DatetimeSplits, ExpandLimits, Filter, Schedule, Span
 
 
 @docs
@@ -13,6 +13,7 @@ def split(
     n_splits: int = 0,
     available: DatetimeIterable | None = None,
     expand_limits: ExpandLimits = "auto",
+    filter: Filter | str | None = None,
     ignore_filters: bool = False,
 ) -> DatetimeSplits:
     """Create time-based cross-validation splits.
@@ -27,6 +28,7 @@ def split(
         n_splits: {n_splits}
         available: {available} Passing a tuple ``(min, max)`` is enough.
         expand_limits: {expand_limits}
+        filter: {filter}
         ignore_filters: {ignore_filters}
 
     {USER_GUIDE}
@@ -44,5 +46,6 @@ def split(
         step=step,
         n_splits=n_splits,
         expand_limits=expand_limits,
+        filter=filter,
         ignore_filters=ignore_filters,
     ).get_splits(available)

time_split-1.0.0/src/time_split/app/__init__.py

@@ -0,0 +1,34 @@
+"""Supporting functions for the Streamlit companion app.
+
+Run ``pip install time-split[app]`` to install the https://github.com/rsundqvist/time-split-app/, or run
+``pip install time-split-app==<version>`` to install the application directly.
+
+.. warning::
+
+   The application API may change without a major version bump.
+
+Once installed, the application will be available under the ``time_split_app`` namespace. Key parts of the API of the
+application are documented in the :mod:`.reexport` submodule.
+
+Getting started
+---------------
+To start the application directly from the command line, run
+
+.. code-block:: bash
+
+   python -m time_split app start
+
+in the terminal. To customize the application, run
+
+.. code-block:: bash
+
+   python -m time_split app new
+
+in the terminal, then modify the ``Dockerfile`` and ``my_extensions.py`` files to suit your needs.
+"""
+
+from ._create_explorer_link import create_explorer_link
+
+__all__ = [
+    "create_explorer_link",
+]

time_split-1.0.0/src/time_split/app/reexport/__init__.py

@@ -0,0 +1,41 @@
+"""Reexported members of the ``time_split_app`` namespace.
+
+.. warning::
+
+   The application API may change without a major version bump.
+
+See :mod:`time_split_app.config` for  variable-based configuration options.
+"""
+
+from time_split_app.datasets import Dataset, DatasetConfig, DuplicateIndexError, load_dataset, load_dataset_configs
+from time_split_app.widgets import DataLoaderWidget, DurationWidget, select_datetime, select_duration
+from time_split_app.widgets import types as _types
+from time_split_app.widgets.types import QueryParams
+
+SelectSplitParams = _types.SelectSplitParams
+"""Type of :attr:`~time_split_app.config.SPLIT_SELECT_FN`.
+
+See Also:
+    * :func:`time_split.split`
+    * :attr:`~time_split.types.DatetimeIndexSplitterKwargs`.
+"""
+PlotFn = _types.PlotFn
+"""Type of :attr:`~time_split_app.config.PLOT_FN`."""
+LinkFn = _types.LinkFn
+"""Type of :attr:`~time_split_app.config.LINK_FN`."""
+
+__all__ = [
+    "DataLoaderWidget",
+    "Dataset",
+    "DatasetConfig",
+    "DuplicateIndexError",
+    "DurationWidget",
+    "LinkFn",
+    "PlotFn",
+    "QueryParams",
+    "SelectSplitParams",
+    "load_dataset",
+    "load_dataset_configs",
+    "select_datetime",
+    "select_duration",
+]

{time_split-0.7.0 → time_split-1.0.0}/src/time_split/integration/polars/__init__.py

@@ -19,11 +19,11 @@ Examples:
     │ ---                 ┆ ---  │
     │ datetime[μs]        ┆ i64  │
     ╞═════════════════════╪══════╡
-    │ 2022-01-06 16:00:00 ┆ 136  │
-    │ 2022-01-08 17:00:00 ┆ 185  │
-    │ 2022-01-01 06:00:00 ┆ 6    │
-    │ 2022-01-01 05:00:00 ┆ 5    │
-    │ 2022-01-03 08:00:00 ┆ 56   │
+    │ 2022-01-02 05:00:00 ┆ 29   │
+    │ 2022-01-01 20:00:00 ┆ 20   │
+    │ 2022-01-07 12:00:00 ┆ 156  │
+    │ 2022-01-01 18:00:00 ┆ 18   │
+    │ 2022-01-04 10:00:00 ┆ 82   │
     └─────────────────────┴──────┘
 
     To split the frame, pass it to ``split_polars`` along with the column to split on. The `schedule` keyword argument

{time_split-0.7.0 → time_split-1.0.0}/src/time_split/settings.py

@@ -2,8 +2,6 @@
 
 import typing as _t
 
-import pandas as _pd
-
 from . import types as _tst
 
 
@@ -175,9 +173,6 @@ class misc:  # noqa: N801
     Otherwise, alignment is determined by :func:`pandas.date_range`.
     """
 
-    filter: _t.Callable[[_pd.Timestamp, _pd.Timestamp, _pd.Timestamp], bool] | None = None
-    """A callable ``(start, mid, end) -> bool`` applied to all generated folds."""
-
     round_limits: bool = False
     """If ``True``, use rounding instead of ``floor`` and ``ceil`` for limits expansion.
 

{time_split-0.7.0 → time_split-1.0.0}/src/time_split/types.py

@@ -3,13 +3,15 @@
 import datetime as _dt
 import logging as _logging
 import typing as _t
+from abc import ABC as _ABC
+from collections import abc as _abc
 
 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]
+DatetimeIterable = _abc.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`."""
@@ -21,6 +23,9 @@ Span = int | _t.Literal["all"] | TimedeltaTypes
 ExpandLimits = bool | _t.Literal["auto"] | str
 """Limits flexibility spec for ``floor/ceil``. Pass ``False`` to disable."""
 
+Filter = _t.Callable[[_pd.Timestamp, _pd.Timestamp, _pd.Timestamp], bool]
+"""A callable ``(start, mid, end) -> bool`` used to filter folds."""
+
 
 class DatetimeSplitBounds(_t.NamedTuple):
     """A 3-tuple which denotes two adjacent datetime ranges."""
@@ -63,11 +68,11 @@ class DatetimeIndexSplitterKwargs(_t.TypedDict, total=False):
     step: int
     n_splits: int
     expand_limits: ExpandLimits
+    filter: Filter | str | None
 
 
-LoggerArg = _logging.Logger | _logging.LoggerAdapter[_t.Any] | str
-
-
+LogSplitProgressLoggerArg = _logging.Logger | _logging.LoggerAdapter[_t.Any] | str
+"""A logger or string."""
 MetricsType = _t.TypeVar("MetricsType")
 """Metrics argument type."""
 GetMetrics = _t.Callable[[_pd.Timestamp], MetricsType]
@@ -79,7 +84,7 @@ FormatMetrics = _t.Callable[[str, MetricsType], str]
 class LogSplitProgressKwargs(_t.TypedDict, _t.Generic[MetricsType], total=False):
     """Keyword arguments for by :func:`.log_split_progress`."""
 
-    logger: LoggerArg
+    logger: LogSplitProgressLoggerArg
     start_level: int
     end_level: int
     extra: dict[str, _t.Any] | None
@@ -103,3 +108,16 @@ class SplitProgressExtras(_t.TypedDict, _t.Generic[MetricsType]):
     """User time for the fold. Available only for the :attr:`fold-end message <.settings.log_split_progress.END_MESSAGE>`."""
     metrics: _t.NotRequired[MetricsType]
     """Optional fold metrics. Typically appended to the :attr:`fold-end message <.settings.log_split_progress.END_MESSAGE>`."""
+
+
+class LogSplitProgress(_ABC, _abc.Sequence[DatetimeSplitBounds]):
+    """The sequence-like return type of :func:`.log_split_progress`.
+
+    A sequence ``[(start, mid, end), ...]`` which logs progress when iterating.
+    """
+
+    splits: _abc.Sequence[DatetimeSplitBounds]
+    """The underlying splits."""
+
+    logger: _logging.Logger | _logging.LoggerAdapter  # type: ignore[type-arg]
+    """Logger instance that emits messages."""

time_split-0.7.0/src/time_split/app/__init__.py

@@ -1,11 +0,0 @@
-"""Supporting functions for the Streamlit companion app.
-
-The app may be installed by running ``pip install time-split[app]``. The application API is *not* stable, but will be
-available under the ``time_split_app`` namespace. Repo: https://github.com/rsundqvist/time-split-app/.
-"""
-
-from ._create_explorer_link import create_explorer_link
-
-__all__ = [
-    "create_explorer_link",
-]