time-split 0.4.0__tar.gz → 0.6.0__tar.gz

{time_split-0.4.0 → time_split-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: time-split
-Version: 0.4.0
+Version: 0.6.0
 Summary: Time-based k-fold validation splits for heterogeneous data.
 Home-page: https://github.com/rsundqvist/time-split
 Author: Richard Sundqvist
@@ -21,7 +21,7 @@ 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: rics (>=4.1.1)
 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
@@ -39,6 +39,7 @@ Time-based k-fold validation splits for heterogeneous data.
 [![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)
+[![Docker Image Size (tag)](https://img.shields.io/docker/image-size/rsundqvist/time-split/latest?logo=docker&label=time-split)](https://hub.docker.com/r/rsundqvist/time-split/)
 
 <div align="center">
   <img alt="Plotted folds on a two-by-two grid." 
@@ -65,6 +66,22 @@ strong non-stationary characteristics.
   [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`.
+- Convenient [web application](#experimenting-with-parameters) for exploring folds with different parameters.
+
+## Experimenting with parameters
+The **Time Fold Explorer** application
+(available [here](https://time-split.streamlit.app/?data=1554942900-1557610200&schedule=0+0+%2A+%2A+MON%2CFRI&n_splits=2&step=2&show_removed=True))
+is designed to help evaluate the effects of different
+[parameters](https://time-split.readthedocs.io/en/stable/#parameter-overview).
+To start it locally using
+[![Docker Image Size (tag)](https://img.shields.io/docker/image-size/rsundqvist/time-split/latest?logo=docker&label=time-split)](https://hub.docker.com/r/rsundqvist/time-split/)
+Docker, run
+```sh
+docker run -p 8501:8501 rsundqvist/time-split
+```
+in the terminal. You may use
+[`create_explorer_link()`](https://time-split.readthedocs.io/en/stable/generated/time_split.support.html#time_split.support.create_explorer_link)
+to build application URLs with preselected splitting parameters.
 
 ## Installation
 The package is published through the [Python Package Index (PyPI)]. Source code

{time_split-0.4.0 → time_split-0.6.0}/README.md

@@ -8,6 +8,7 @@ Time-based k-fold validation splits for heterogeneous data.
 [![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)
+[![Docker Image Size (tag)](https://img.shields.io/docker/image-size/rsundqvist/time-split/latest?logo=docker&label=time-split)](https://hub.docker.com/r/rsundqvist/time-split/)
 
 <div align="center">
   <img alt="Plotted folds on a two-by-two grid." 
@@ -34,6 +35,22 @@ strong non-stationary characteristics.
   [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`.
+- Convenient [web application](#experimenting-with-parameters) for exploring folds with different parameters.
+
+## Experimenting with parameters
+The **Time Fold Explorer** application
+(available [here](https://time-split.streamlit.app/?data=1554942900-1557610200&schedule=0+0+%2A+%2A+MON%2CFRI&n_splits=2&step=2&show_removed=True))
+is designed to help evaluate the effects of different
+[parameters](https://time-split.readthedocs.io/en/stable/#parameter-overview).
+To start it locally using
+[![Docker Image Size (tag)](https://img.shields.io/docker/image-size/rsundqvist/time-split/latest?logo=docker&label=time-split)](https://hub.docker.com/r/rsundqvist/time-split/)
+Docker, run
+```sh
+docker run -p 8501:8501 rsundqvist/time-split
+```
+in the terminal. You may use
+[`create_explorer_link()`](https://time-split.readthedocs.io/en/stable/generated/time_split.support.html#time_split.support.create_explorer_link)
+to build application URLs with preselected splitting parameters.
 
 ## Installation
 The package is published through the [Python Package Index (PyPI)]. Source code

{time_split-0.4.0 → time_split-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "time-split"
-version = "0.4.0"
+version = "0.6.0"
 description = "Time-based k-fold validation splits for heterogeneous data."
 authors = ["Richard Sundqvist <richard.sundqvist@live.se>"]
 
@@ -18,7 +18,7 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Natural Language :: English",
     "Programming Language :: Python :: 3",
-    'Programming Language :: Python :: 3 :: Only',
+    "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
 ]
@@ -34,7 +34,7 @@ classifiers = [
 python = ">=3.11"
 
 pandas = ">=2.0.3"
-rics = ">=3.1.0"
+rics = ">=4.1.1"
 
 # plotting
 matplotlib = { version = "*", optional = true }
@@ -48,7 +48,7 @@ plotting = ["matplotlib", "seaborn"]
 croniter = "^2.0.3"
 pyarrow = ">=15.0.2,<17.0.0"
 polars = { version = "^0.20.19", extras = ["pandas"] }
-numpy = "<2"  # TODO: numpy 2.0
+streamlit = "*"
 
 [tool.poetry.group.docs]
 [tool.poetry.group.docs.dependencies]
@@ -85,11 +85,11 @@ dask = { version = "==2024.5.0", extras = ["dataframe"] }
 
 [tool.poetry.group.devops.dependencies]
 invoke = "^2.2.0"
-mypy = "^1.9.0"
-ruff = ">=0.3.7,<0.5.0"
+mypy = "^1.10.1"
+ruff = "^0.5.0"
 
-safety = "^3.1.0"
-codespell = "^2.2.6"
+safety = "^3.2.3"
+codespell = "^2.3.0"
 bump2version = "^1.0.1"
 
 [tool.ruff]
@@ -148,6 +148,7 @@ ignore = [
     "SIM108", # Use ternary operator - coverage issue, see https://github.com/nedbat/coveragepy/issues/509
     "TD003", # Missing issue link
 ]
+allowed-confusables = ["ℹ"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = [

{time_split-0.4.0 → time_split-0.6.0}/src/time_split/__init__.py

@@ -11,6 +11,6 @@ __all__ = [
     "__version__",  # Make MyPy happy
 ]
 
-__version__ = "0.4.0"
+__version__ = "0.6.0"
 
 _logging.getLogger(__name__).addHandler(_logging.NullHandler())

{time_split-0.4.0 → time_split-0.6.0}/src/time_split/_backend/_splitter.py

@@ -1,13 +1,12 @@
 import logging
 from dataclasses import asdict, dataclass
+from functools import lru_cache
 from typing import cast, get_args
 
-from pandas import Timedelta, Timestamp
+from pandas import Timedelta
 from rics.misc import format_kwargs
 
-from time_split._compat import fmt_sec
-
-from ..settings import misc
+from ..settings import misc as settings
 from ..types import (
     DatetimeIndexSplitterKwargs,
     DatetimeIterable,
@@ -30,11 +29,12 @@ class DatetimeIndexSplitter:
     """Backend interface for splitting user data. See the :ref:`Parameter overview` page."""
 
     schedule: Schedule
-    before: Span
-    after: Span
-    step: int
-    n_splits: int
-    expand_limits: ExpandLimits
+    before: Span = "7d"
+    after: Span = 1
+    step: int = 1
+    n_splits: int = 0
+    expand_limits: ExpandLimits = "auto"
+    ignore_filters: bool = False
 
     def get_splits(self, available: DatetimeIterable | None = None) -> DatetimeSplits:
         """Compute a split of given user data."""
@@ -55,7 +55,7 @@ class DatetimeIndexSplitter:
 
         types = get_args(TimedeltaTypes)
         if (
-            misc.snap_to_end
+            settings.snap_to_end
             and self.after != "all"
             and isinstance(self.schedule, types)
             and isinstance(self.after, types)
@@ -99,7 +99,7 @@ class DatetimeIndexSplitter:
             msg = f"No valid splits with {limits_info}split params: ({format_kwargs(self.as_dict())})"
             raise ValueError(msg)
 
-        return self._filter(retval)
+        return retval if self.ignore_filters else self._filter(retval)
 
     def _filter(self, splits: DatetimeSplits) -> DatetimeSplits:
         """Apply splitting arguments.
@@ -122,29 +122,25 @@ class DatetimeIndexSplitter:
         if self.step < 0:  # Poorly documented - might not work as expected?
             splits.reverse()
 
-        return splits
+        if settings.filter is None:
+            return splits
+
+        return [s for s in splits if settings.filter(*s)]
 
     def _log_expansion(self, original: LimitsTuple, *, expanded: LimitsTuple) -> None:
-        if original == expanded:
-            return
+        from .._frontend import format_expanded_limits
 
-        if not LOGGER.isEnabledFor(logging.INFO):
+        if original == expanded or not LOGGER.isEnabledFor(logging.INFO):
             return
 
-        def stringify(old: Timestamp, *, new: Timestamp) -> str:
-            from .._frontend._to_string import _PrettyTimestamp
+        message = format_expanded_limits(original, expanded=expanded, expand_limits=self.expand_limits)
+        self._emit_once(message)
 
-            retval = f"{old} -> "
-            if old == new:
-                return retval + "<no change>"
-            diff = (new - old).total_seconds()
-            return retval + f"{_PrettyTimestamp(new).auto} ({'+' if diff > 0 else '-'}{fmt_sec(abs(diff))})"
-
-        LOGGER.info(
-            f"Available data limits have been expanded (since expand_limits={self.expand_limits!r}):\n"
-            f"  start: {stringify(original[0], new=expanded[0])}\n"
-            f"    end: {stringify(original[1], new=expanded[1])}"
-        )
+    @staticmethod
+    @lru_cache(8)
+    def _emit_once(message: str) -> None:
+        """Emit if **not** in the eight most recent emission messages."""
+        LOGGER.info(message)
 
     def __post_init__(self) -> None:
         # Verify n_splits

{time_split-0.4.0 → time_split-0.6.0}/src/time_split/_docstrings.py

@@ -17,7 +17,7 @@ def docs(__func: Callable[P, T], /) -> Callable[P, T]:
     __func.__doc__ = __func.__doc__.format(**_DOCSTRINGS)
 
     if isinstance(__func, type):
-        __func.__init__ = deprecated_params(__func.__init__)
+        __func.__init__ = deprecated_params(__func.__init__)  # type: ignore[misc]
     else:
         __func = deprecated_params(__func)
 
@@ -37,10 +37,12 @@ _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.",
     "USER_GUIDE": (
         "For more information about the `schedule`, `before/after` and `expand_limits`-arguments"
         ", see the :ref:`User guide`."
     ),
     "OFFSET": _OFFSET,
     "DatetimeIndexSplitterKwargs": "See :func:`~time_split.split`. The `available` keyword is managed by the integration.",
+    "show_removed": "If ``True``, splits removed by `n_splits` or `step` are included in the figure.",
 }

{time_split-0.4.0 → time_split-0.6.0}/src/time_split/_frontend/__init__.py

@@ -1,7 +1,7 @@
 from ._plot import plot
 from ._progress import default_metrics_formatter, log_split_progress
 from ._split import split
-from ._to_string import to_string
+from ._to_string import format_expanded_limits, to_string
 from ._weight import fold_weight
 
 __all__ = [
@@ -11,4 +11,5 @@ __all__ = [
     "plot",
     "split",
     "to_string",
+    "format_expanded_limits",
 ]

{time_split-0.4.0 → time_split-0.6.0}/src/time_split/_frontend/_plot.py

@@ -1,5 +1,5 @@
 from dataclasses import asdict, dataclass, replace
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Any, Literal, Sized
 
 import pandas as pd
 from pandas import Timestamp
@@ -22,6 +22,7 @@ from ..types import (
     Span,
 )
 from ._split import split
+from ._to_string import _PrettyTimestamp
 from ._weight import fold_weight
 
 if TYPE_CHECKING:
@@ -66,6 +67,7 @@ def plot(
     n_splits: int = 0,
     available: DatetimeIterable | None = None,
     expand_limits: ExpandLimits = "auto",
+    ignore_filters: bool = False,
     # Split plot args
     bar_labels: str | Rows | list[tuple[str, str]] | bool = True,
     show_removed: bool = False,
@@ -86,12 +88,13 @@ 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}
+        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
             contained. Pass `'rows'` to simply count the numbers of elements in `data` (if given). To write custom
             bar labels, pass a list ``[(data_label, future_data_label), ...]``, one tuple for each fold. This may be
             used to write metric values per data set after cross validation.
-        show_removed: If ``True``, splits removed by `n_splits` or `step` are included in the figure.
+        show_removed: {show_removed}
         row_count_bin: A {OFFSET}. If given, show normalized row count per `row_count_bin` in the background. Pass
             ``pandas.Series`` to use pre-computed row counts.
         ax: Axis to use for plotting. If ``None``, create new axes.
@@ -116,20 +119,24 @@ def plot(
         step=step,
         n_splits=n_splits,
         expand_limits=expand_limits,
+        ignore_filters=ignore_filters,
     )
     plot_data = _get_plot_data(available, splitter, row_count_bin=row_count_bin, show_removed=show_removed)
 
     if bar_labels is True:
-        bar_labels = settings.DEFAULT_TIME_UNIT if plot_data.available is None else COUNT_ROWS
+        bar_labels = (
+            settings.DEFAULT_TIME_UNIT if (plot_data.available is None or _is_limits(available)) else COUNT_ROWS
+        )
 
     if ax is None:
-        _, ax = plt.subplots(
+        fig, ax = plt.subplots(
             tight_layout=True,
             figsize=(
                 plt.rcParams["figure.figsize"][0],
                 3 + len(plot_data.splits) * 0.5,
             ),
         )
+        fig.autofmt_xdate(ha="center", rotation=15)
 
     _plot_splits(ax, plot_data.splits, removed=plot_data.removed)
 
@@ -166,7 +173,7 @@ def _plot_limits(ax: "Axes", limits: LimitsTuple) -> None:
     from matplotlib.dates import date2num
 
     left, right = limits
-    ax.axvline(left, color="k", ls="--", label="Outer range")
+    ax.axvline(left, color="k", ls="--", label="Available")
     ax.axvline(right, color="k", ls="--")
     left_tick, right_tick = date2num(left), date2num(right)  # type: ignore[no-untyped-call]
     ax.set_xticks([left_tick, *ax.get_xticks(), right_tick])
@@ -284,7 +291,8 @@ def _get_plot_data(
 
     if show_removed:
         kept_splits = set(splits)
-        splits = replace(splitter, n_splits=0, step=1).get_plot_data(available)[0]
+        splits = replace(splitter, ignore_filters=True).get_plot_data(available)[0]
+
         if splitter.step < 0:
             splits.reverse()
         removed = set(splits) - set(kept_splits)
@@ -347,7 +355,19 @@ def _make_title(available: Any | None, split_kwargs: dict[str, Any]) -> str:
     kwargs = {key: value for key, value in split_kwargs.items() if not is_default(key)}
     if available is None:
         formatted_available = ""
+    elif _is_limits(available):
+        available = sorted(_PrettyTimestamp(a).auto for a in available)
+        available = tuple(available)
+        formatted_available = f", {available=}"  # Probably pre-computed
     else:
         pretty = get_public_module(type(available), resolve_reexport=True, include_name=True)
         formatted_available = f", available={pretty}"
-    return f"time_split.split({format_kwargs(kwargs, max_value_length=40)}{formatted_available})"
+
+    title = f"time_split.split({format_kwargs(kwargs, max_value_length=40)}{formatted_available})"
+    title = title.replace("datetime.", "")
+    title = title.replace("pandas.", "pd.")
+    return title
+
+
+def _is_limits(available: Any) -> bool:
+    return isinstance(available, Sized) and len(available) == 2  # noqa: PLR2004

{time_split-0.4.0 → time_split-0.6.0}/src/time_split/_frontend/_split.py

@@ -13,6 +13,7 @@ def split(
     n_splits: int = 0,
     available: DatetimeIterable | None = None,
     expand_limits: ExpandLimits = "auto",
+    ignore_filters: bool = False,
 ) -> DatetimeSplits:
     """Create time-based cross-validation splits.
 
@@ -26,6 +27,7 @@ def split(
         n_splits: {n_splits}
         available: {available} Passing a tuple ``(min, max)`` is enough.
         expand_limits: {expand_limits}
+        ignore_filters: {ignore_filters}
 
     {USER_GUIDE}
 
@@ -42,4 +44,5 @@ def split(
         step=step,
         n_splits=n_splits,
         expand_limits=expand_limits,
+        ignore_filters=ignore_filters,
     ).get_splits(available)

{time_split-0.4.0 → time_split-0.6.0}/src/time_split/_frontend/_to_string.py

@@ -2,8 +2,10 @@ from typing import Any, Literal, overload
 
 from pandas import Timestamp
 
+from .._backend._limits import LimitsTuple
+from .._compat import fmt_sec
 from ..settings import log_split_progress
-from ..types import DatetimeSplitBounds, DatetimeTypes
+from ..types import DatetimeSplitBounds, DatetimeTypes, ExpandLimits
 
 
 @overload
@@ -73,6 +75,25 @@ def to_string(
     )
 
 
+def stringify(old: Timestamp, *, new: Timestamp | None = None, diff_only: bool = False) -> str:
+    if new is None:
+        return _PrettyTimestamp(old).auto
+
+    original = f"{old} -> "
+    if old == new:
+        no_change = "<no change>"
+        if diff_only:
+            return no_change
+        return original + no_change
+    diff = (new - old).total_seconds()
+    pretty_diff = f"{'+' if diff > 0 else '-'}{fmt_sec(abs(diff))}"
+
+    if diff_only:
+        return pretty_diff
+
+    return original + f"{_PrettyTimestamp(new).auto} ({pretty_diff})"
+
+
 class _PrettyTimestamp:
     def __init__(self, raw: DatetimeTypes) -> None:
         self.timestamp = Timestamp(raw)
@@ -101,3 +122,31 @@ class _PrettyTimestamp:
             )
             self._auto = format(timestamp, format_spec)
         return self._auto
+
+
+def format_expanded_limits(
+    original: LimitsTuple,
+    *,
+    expanded: LimitsTuple | None = None,
+    expand_limits: ExpandLimits,
+) -> str:
+    """Format expanded limits.
+
+    Args:
+        original: The original data limits.
+        expanded: Expanded data limits. Derived based on `original` and `expanded_limits` if ``None``.
+        expand_limits: Limits expansion spec.
+
+    Returns:
+        A string.
+    """
+    if expanded is None:
+        from .._backend._limits import expand_limits as expand
+
+        expanded = expand(original, spec=expand_limits)
+
+    return (
+        f"Available data limits have been expanded (since {expand_limits=}):\n"
+        f"  start: {stringify(original[0], new=expanded[0])}\n"
+        f"    end: {stringify(original[1], new=expanded[1])}"
+    )

{time_split-0.4.0 → time_split-0.6.0}/src/time_split/integration/sklearn/_impl.py

@@ -1,5 +1,5 @@
 from collections.abc import Iterable, Sequence
-from typing import Any, cast, get_args
+from typing import Any, Unpack, cast, get_args
 
 from numpy import array, datetime64, logical_and, ndarray, nonzero
 from numpy.typing import NDArray
@@ -7,13 +7,11 @@ from numpy.typing import NDArray
 from ..._backend import DatetimeIndexSplitter
 from ..._docstrings import docs
 from ...types import (
+    DatetimeIndexSplitterKwargs,
     DatetimeIterable,
     DatetimeSplits,
     DatetimeTypes,
-    ExpandLimits,
     MetricsType,
-    Schedule,
-    Span,
 )
 from .._log_progress import LogProgressArg, handle_log_progress_arg
 
@@ -39,14 +37,9 @@ class ScikitLearnSplitter(BaseCrossValidator):  # type: ignore[misc]
     If a ``pandas`` type is passed to the :meth:`ScikitLearnSplitter.split`-method, the index will be used.
 
     Args:
-        schedule: {schedule}
-        before: {before}
-        after: {after}
-        step: {step}
-        n_splits: {n_splits}
-        expand_limits: {expand_limits}
         log_progress: {log_progress}
         verify_xy: If ``True``, split X and y independently and verify that they are equal.
+        **kwargs: {DatetimeIndexSplitterKwargs}
 
     {USER_GUIDE}
 
@@ -54,25 +47,13 @@ class ScikitLearnSplitter(BaseCrossValidator):  # type: ignore[misc]
 
     def __init__(
         self,
-        schedule: Schedule,
         *,
-        before: Span = "7d",
-        after: Span = 1,
-        n_splits: int = 0,
-        expand_limits: ExpandLimits = "auto",
-        step: int = 1,
         log_progress: LogProgressArg[MetricsType] = False,
         verify_xy: bool = True,
+        **kwargs: Unpack[DatetimeIndexSplitterKwargs],
     ) -> None:
         super().__init__()
-        self._splitter = DatetimeIndexSplitter(
-            schedule,
-            before=before,
-            after=after,
-            step=step,
-            n_splits=n_splits,
-            expand_limits=expand_limits,
-        )
+        self._splitter = DatetimeIndexSplitter(**kwargs)
         self.log_progress = log_progress
         self.verify_xy = verify_xy
 

{time_split-0.4.0 → time_split-0.6.0}/src/time_split/settings.py

@@ -2,17 +2,19 @@
 
 import typing as _t
 
+import pandas as _pd
+
 from . import types as _tst
 
 
 class auto_expand_limits:  # noqa: N801
     """Configuration for the `'auto'` :attr:`~time_split.types.ExpandLimits` logic.
 
-    This class determines how ``(min, max)``-tuples are expanded when expand_limitsible bounds are enabled.
+    This class determines how ``(min, max)``-tuples are expanded when expanded limits are enabled.
     """
 
     SANITY_CHECK: bool = True
-    """If ``True``, use original limits if expand_limitsed limits do not pass sanity checks."""
+    """If ``True``, use original limits if expanded limits do not pass sanity checks."""
 
     @classmethod
     def set_level(
@@ -84,8 +86,8 @@ class plot:  # noqa: N801
     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``."""
+    DEFAULT_TIME_UNIT: str = "hours"
+    """Time unit to use by default when ``bar_labels=True`` and ``available=None`` or a limits tuple."""
 
     REMOVED_FOLD_STYLE: _t.ClassVar[dict[str, _t.Any]] = {
         "alpha": 0.35,
@@ -172,3 +174,6 @@ class misc:  # noqa: N801
     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`.
     """
+
+    filter: _t.Callable[[_pd.Timestamp, _pd.Timestamp, _pd.Timestamp], bool] | None = None
+    """A callable ``(start, mid, end) -> bool`` applied to all generated folds."""

{time_split-0.4.0 → time_split-0.6.0}/src/time_split/support/__init__.py

@@ -12,7 +12,8 @@ dependencies if you need to use the ``support`` module.
 """
 
 from .._backend import DatetimeIndexSplitter, expand_limits, process_available
-from .._frontend import default_metrics_formatter, fold_weight, to_string
+from .._frontend import default_metrics_formatter, fold_weight, format_expanded_limits, to_string
+from ._create_explorer_link import create_explorer_link
 
 __all__ = [
     "DatetimeIndexSplitter",
@@ -21,4 +22,6 @@ __all__ = [
     "default_metrics_formatter",
     "fold_weight",
     "to_string",
+    "format_expanded_limits",
+    "create_explorer_link",
 ]

time_split-0.6.0/src/time_split/support/_create_explorer_link.py

@@ -0,0 +1,118 @@
+from datetime import datetime
+from typing import Any, Unpack
+from urllib.parse import ParseResult, urlencode, urlparse, urlunparse
+
+from .._backend import DatetimeIndexSplitter
+from .._docstrings import docs
+from ..types import DatetimeIndexSplitterKwargs, DatetimeIterable
+
+
+@docs
+def create_explorer_link(
+    host: str,
+    data: DatetimeIterable | str | None = None,
+    available: DatetimeIterable | str | None = None,
+    *,
+    show_removed: bool = True,
+    skip_default: bool = False,
+    **kwargs: Unpack[DatetimeIndexSplitterKwargs],
+) -> str:
+    """Create a `Time Fold Explorer` application URL.
+
+    Args:
+        host: Base address where the application is hosted.
+        data: {available} Regular `available` arguments (as passed to e.g. :func:`time_split.split`) are encoded as
+            a date range to generate dummy data for. Pass a ``str`` to use dataset bundled by the server instead. Note
+            that this function cannot verify the `kwargs` if `available` is a ``str`` dataset.
+        available: Alias of `data`.
+        skip_default: If ``True``, do not include default split params in the link.
+        show_removed: {show_removed}
+        kwargs: Keyword arguments for the :func:`time_split.split`-function.
+
+    Returns:
+        An encoded URL.
+
+    Examples:
+        Getting the URL for a local host.
+
+        >>> create_explorer_link(
+        ...     host="http://localhost:8501",
+        ...     available=("2019-04-11 00:35:00", "2019-05-11 21:30:00"),
+        ...     schedule="0 0 * * MON,FRI",
+        ... )
+        'http://localhost:8501?data=1554942900-1557610200&schedule=0+0+%2A+%2A+MON%2CFRI&show_removed=True'
+
+        To start the application using locally using |image| Docker, run
+
+        .. code-block:: bash
+
+           docker run -p 8501:8501 rsundqvist/time-split
+
+        in the terminal.
+
+        .. |image| image:: https://img.shields.io/docker/image-size/rsundqvist/time-split/latest?logo=docker&label=time-split
+                   :target: https://hub.docker.com/r/rsundqvist/time-split/
+                   :alt: Docker Image Size (tag)
+    """
+    if sum([data is None, available is None]) != 1:
+        raise ValueError("Exactly one of `data` and `available` must be given.")
+    if data is None:
+        data = available
+
+    assert data is not None  # noqa: S101
+    pr = _create_explorer_link(host, data, show_removed=show_removed, skip_default=skip_default, **kwargs)
+    return urlunparse(pr)
+
+
+def _create_explorer_link(
+    host: str,
+    data: DatetimeIterable | str,
+    *,
+    show_removed: bool = True,
+    skip_default: bool = False,
+    **kwargs: Unpack[DatetimeIndexSplitterKwargs],
+) -> ParseResult:
+    query = _create_query(data, skip_default=skip_default, show_removed=show_removed, kwargs=kwargs)
+
+    pr: ParseResult = urlparse(host)  # scheme netloc path params query fragment
+    if pr.query:
+        raise ValueError(f"Bad {host=}; query={pr.query!r} is not allowed.")
+    return pr._replace(query=urlencode(query))
+
+
+def _create_query(
+    data: DatetimeIterable | str,
+    *,
+    skip_default: bool,
+    show_removed: bool,
+    kwargs: DatetimeIndexSplitterKwargs,
+) -> dict[str, Any]:
+    query: dict[str, Any] = {}
+
+    if isinstance(data, str):
+        query = {"data": data, **kwargs}
+    else:
+        splitter = DatetimeIndexSplitter(**kwargs)
+        _, ms = splitter.get_plot_data(data)
+        query["data"] = _get_data_param(*ms.available_metadata.limits)
+
+        if skip_default:
+            schedule = kwargs["schedule"]
+            query["schedule"] = schedule
+
+            default = DatetimeIndexSplitter(schedule).as_dict()
+            no_defaults = {
+                key: value
+                for key, value in kwargs.items()
+                if value != default[key]  # type: ignore[literal-required]
+            }
+            query.update(no_defaults)
+        else:
+            query.update(kwargs)
+
+    query["show_removed"] = show_removed
+    return query
+
+
+def _get_data_param(start: datetime, end: datetime) -> str:
+    return f"{int(start.timestamp())}-{int(end.timestamp())}"