tsdownsample 0.1.4.1rc0__cp39-cp39-win_amd64.whl

tsdownsample/__init__.py

@@ -0,0 +1,26 @@
+"""tsdownsample: high performance downsampling of time series data for visualization."""
+
+from .downsamplers import (
+    EveryNthDownsampler,
+    LTTBDownsampler,
+    M4Downsampler,
+    MinMaxDownsampler,
+    MinMaxLTTBDownsampler,
+    NaNM4Downsampler,
+    NaNMinMaxDownsampler,
+    NaNMinMaxLTTBDownsampler,
+)
+
+__version__ = "0.1.4.1rc0"
+__author__ = "Jeroen Van Der Donckt"
+
+__all__ = [
+    "EveryNthDownsampler",
+    "MinMaxDownsampler",
+    "M4Downsampler",
+    "LTTBDownsampler",
+    "MinMaxLTTBDownsampler",
+    "NaNMinMaxDownsampler",
+    "NaNM4Downsampler",
+    "NaNMinMaxLTTBDownsampler",
+]

tsdownsample/_python/downsamplers.py

@@ -0,0 +1,257 @@
+from typing import Union
+
+import numpy as np
+
+from ..downsampling_interface import AbstractDownsampler
+
+
+def _get_bin_idxs(x: np.ndarray, nb_bins: int) -> np.ndarray:
+    """Get the equidistant indices of the bins to use for the aggregation.
+
+    Parameters
+    ----------
+    x : np.ndarray
+        The x values of the input data.
+    nb_bins : int
+        The number of bins.
+
+    Returns
+    -------
+    np.ndarray
+        The indices of the bins to use for the aggregation.
+    """
+    # Thanks to the `linspace` the data is evenly distributed over the index-range
+    # The searchsorted function returns the index positions
+    bins = np.searchsorted(x, np.linspace(x[0], x[-1], nb_bins + 1), side="right")
+    bins[0] = 0
+    bins[-1] = len(x)
+    return np.array(bins)
+
+
+class LTTB_py(AbstractDownsampler):
+    @staticmethod
+    def _argmax_area(prev_x, prev_y, avg_next_x, avg_next_y, x_bucket, y_bucket) -> int:
+        """Vectorized triangular area argmax computation.
+
+        Parameters
+        ----------
+        prev_x : float
+            The previous selected point is x value.
+        prev_y : float
+            The previous selected point its y value.
+        avg_next_x : float
+            The x mean of the next bucket
+        avg_next_y : float
+            The y mean of the next bucket
+        x_bucket : np.ndarray
+            All x values in the bucket
+        y_bucket : np.ndarray
+            All y values in the bucket
+
+        Returns
+        -------
+        int
+            The index of the point with the largest triangular area.
+        """
+        return np.abs(
+            x_bucket * (prev_y - avg_next_y)
+            + y_bucket * (avg_next_x - prev_x)
+            + (prev_x * avg_next_y - avg_next_x * prev_y)
+        ).argmax()
+
+    def _downsample(
+        self, x: Union[np.ndarray, None], y: np.ndarray, n_out: int, **kwargs
+    ) -> np.ndarray:
+        """TODO complete docs"""
+        if x is None:
+            # Is fine for this implementation as this is only used for testing
+            x = np.arange(y.shape[0])
+
+        # Bucket size. Leave room for start and end data points
+        block_size = (y.shape[0] - 2) / (n_out - 2)
+        # Note this 'astype' cast must take place after array creation (and not with the
+        # aranage() its dtype argument) or it will cast the `block_size` step to an int
+        # before the arange array creation
+        offset = np.arange(start=1, stop=y.shape[0], step=block_size).astype(np.int64)
+
+        # Construct the output array
+        sampled_x = np.empty(n_out, dtype="int64")
+        sampled_x[0] = 0
+        sampled_x[-1] = x.shape[0] - 1
+
+        # Convert x & y to int if it is boolean
+        if x.dtype == np.bool_:
+            x = x.astype(np.int8)
+        if y.dtype == np.bool_:
+            y = y.astype(np.int8)
+
+        a = 0
+        for i in range(n_out - 3):
+            a = (
+                LTTB_py._argmax_area(
+                    prev_x=x[a],
+                    prev_y=y[a],
+                    avg_next_x=np.mean(x[offset[i + 1] : offset[i + 2]]),
+                    avg_next_y=y[offset[i + 1] : offset[i + 2]].mean(),
+                    x_bucket=x[offset[i] : offset[i + 1]],
+                    y_bucket=y[offset[i] : offset[i + 1]],
+                )
+                + offset[i]
+            )
+            sampled_x[i + 1] = a
+
+        # ------------ EDGE CASE ------------
+        # next-average of last bucket = last point
+        sampled_x[-2] = (
+            LTTB_py._argmax_area(
+                prev_x=x[a],
+                prev_y=y[a],
+                avg_next_x=x[-1],  # last point
+                avg_next_y=y[-1],
+                x_bucket=x[offset[-2] : offset[-1]],
+                y_bucket=y[offset[-2] : offset[-1]],
+            )
+            + offset[-2]
+        )
+        return sampled_x
+
+
+class MinMax_py(AbstractDownsampler):
+    """Aggregation method which performs binned min-max aggregation over fully
+    overlapping windows.
+    """
+
+    @staticmethod
+    def _check_valid_n_out(n_out: int):
+        assert n_out % 2 == 0, "n_out must be a multiple of 2"
+
+    def _downsample(
+        self, x: Union[np.ndarray, None], y: np.ndarray, n_out: int, **kwargs
+    ) -> np.ndarray:
+        if x is None:
+            # Is fine for this implementation as this is only used for testing
+            x = np.arange(y.shape[0])
+
+        xdt = x.dtype
+        if np.issubdtype(xdt, np.datetime64) or np.issubdtype(xdt, np.timedelta64):
+            x = x.view(np.int64)
+
+        bins = _get_bin_idxs(x, n_out // 2)
+
+        rel_idxs = []
+        for lower, upper in zip(bins, bins[1:]):
+            y_slice = y[lower:upper]
+            if not len(y_slice):
+                continue
+            # calculate the argmin(slice) & argmax(slice)
+            rel_idxs.append(lower + np.nanargmin(y_slice))
+            rel_idxs.append(lower + np.nanargmax(y_slice))
+        return np.unique(rel_idxs)
+
+
+class NaNMinMax_py(AbstractDownsampler):
+    @staticmethod
+    def _check_valid_n_out(n_out: int):
+        assert n_out % 2 == 0, "n_out must be a multiple of 2"
+
+    def _downsample(
+        self, x: Union[np.ndarray, None], y: np.ndarray, n_out: int, **kwargs
+    ) -> np.ndarray:
+        if x is None:
+            # Is fine for this implementation as this is only used for testing
+            x = np.arange(y.shape[0])
+
+        xdt = x.dtype
+        if np.issubdtype(xdt, np.datetime64) or np.issubdtype(xdt, np.timedelta64):
+            x = x.view(np.int64)
+
+        bins = _get_bin_idxs(x, n_out // 2)
+
+        rel_idxs = []
+        for lower, upper in zip(bins, bins[1:]):
+            y_slice = y[lower:upper]
+            if not len(y_slice):
+                continue
+            # calculate the argmin(slice) & argmax(slice)
+            rel_idxs.append(lower + np.argmin(y_slice))
+            rel_idxs.append(lower + np.argmax(y_slice))
+        return np.array(sorted(rel_idxs))
+
+
+class M4_py(AbstractDownsampler):
+    """Aggregation method which selects the 4 M-s, i.e y-argmin, y-argmax, x-argmin, and
+    x-argmax per bin.
+
+    .. note::
+        When `n_out` is 4 * the canvas its pixel widht it should create a pixel-perfect
+        visualization w.r.t. the raw data.
+
+    """
+
+    @staticmethod
+    def _check_valid_n_out(n_out: int):
+        assert n_out % 4 == 0, "n_out must be a multiple of 4"
+
+    def _downsample(
+        self, x: Union[np.ndarray, None], y: np.ndarray, n_out: int, **kwargs
+    ) -> np.ndarray:
+        """TODO complete docs"""
+        if x is None:
+            # Is fine for this implementation as this is only used for testing
+            x = np.arange(y.shape[0])
+
+        xdt = x.dtype
+        if np.issubdtype(xdt, np.datetime64) or np.issubdtype(xdt, np.timedelta64):
+            x = x.view(np.int64)
+
+        bins = _get_bin_idxs(x, n_out // 4)
+
+        rel_idxs = []
+        for lower, upper in zip(bins, bins[1:]):
+            y_slice = y[lower:upper]
+            if not len(y_slice):
+                continue
+
+            # calculate the min(idx), argmin(slice), argmax(slice), max(idx)
+            rel_idxs.append(lower)
+            rel_idxs.append(lower + np.nanargmin(y_slice))
+            rel_idxs.append(lower + np.nanargmax(y_slice))
+            rel_idxs.append(upper - 1)
+
+        # NOTE: we do not use the np.unique so that all indices are retained
+        return np.array(sorted(rel_idxs))
+
+
+class NaNM4_py(AbstractDownsampler):
+    @staticmethod
+    def _check_valid_n_out(n_out: int):
+        assert n_out % 4 == 0, "n_out must be a multiple of 4"
+
+    def _downsample(
+        self, x: Union[np.ndarray, None], y: np.ndarray, n_out: int, **kwargs
+    ) -> np.ndarray:
+        """TODO complete docs"""
+        if x is None:
+            # Is fine for this implementation as this is only used for testing
+            x = np.arange(y.shape[0])
+
+        xdt = x.dtype
+        if np.issubdtype(xdt, np.datetime64) or np.issubdtype(xdt, np.timedelta64):
+            x = x.view(np.int64)
+
+        bins = _get_bin_idxs(x, n_out // 4)
+
+        rel_idxs = []
+        for lower, upper in zip(bins, bins[1:]):
+            y_slice = y[lower:upper]
+            if not len(y_slice):
+                continue
+
+            # calculate the min(idx), argmin(slice), argmax(slice), max(idx)
+            rel_idxs.append(lower)
+            rel_idxs.append(lower + y_slice.argmin())
+            rel_idxs.append(lower + y_slice.argmax())
+            rel_idxs.append(upper - 1)
+
+        # NOTE: we do not use the np.unique so that all indices are retained
+        return np.array(sorted(rel_idxs))

tsdownsample/_rust/__init__.py

@@ -0,0 +1 @@
+# In this folder the compiled rust code should be placed.

tsdownsample/downsamplers.py

@@ -0,0 +1,158 @@
+import warnings
+from typing import Union
+
+import numpy as np
+
+# ------------------ Rust Downsamplers ------------------
+from tsdownsample._rust import _tsdownsample_rs  # type: ignore[attr-defined]
+
+from .downsampling_interface import (
+    AbstractDownsampler,
+    AbstractRustDownsampler,
+    AbstractRustNaNDownsampler,
+)
+
+
+class MinMaxDownsampler(AbstractRustDownsampler):
+    """Downsampler that uses the MinMax algorithm. If the y data contains NaNs, these
+    ignored (i.e. the NaNs are not taken into account when selecting data points).
+
+    For each bin, the indices of the minimum and maximum values are selected.
+    """
+
+    @property
+    def rust_mod(self):
+        return _tsdownsample_rs.minmax
+
+    @staticmethod
+    def _check_valid_n_out(n_out: int):
+        AbstractRustDownsampler._check_valid_n_out(n_out)
+        if n_out % 2 != 0:
+            raise ValueError("n_out must be even")
+
+
+class NaNMinMaxDownsampler(AbstractRustNaNDownsampler):
+    """Downsampler that uses the MinMax algorithm. If the y data contains NaNs, the
+    indices of these NaNs are returned.
+
+    For each bin, the indices of the minimum and maximum values are selected.
+    """
+
+    @property
+    def rust_mod(self):
+        return _tsdownsample_rs.minmax
+
+    @staticmethod
+    def _check_valid_n_out(n_out: int):
+        AbstractRustDownsampler._check_valid_n_out(n_out)
+        if n_out % 2 != 0:
+            raise ValueError("n_out must be even")
+
+
+class M4Downsampler(AbstractRustDownsampler):
+    """Downsampler that uses the M4 algorithm. If the y data contains NaNs, these are
+    ignored (i.e. the NaNs are not taken into account when selecting data points).
+
+    For each bin, the indices of the first, last, minimum and maximum values are
+    selected.
+    """
+
+    @property
+    def rust_mod(self):
+        return _tsdownsample_rs.m4
+
+    @staticmethod
+    def _check_valid_n_out(n_out: int):
+        AbstractRustDownsampler._check_valid_n_out(n_out)
+        if n_out % 4 != 0:
+            raise ValueError("n_out must be a multiple of 4")
+
+
+class NaNM4Downsampler(AbstractRustNaNDownsampler):
+    """Downsampler that uses the M4 algorithm. If the y data contains NaNs, the indices
+    of these NaNs are returned.
+
+    For each bin, the indices of the first, last, minimum and maximum values are
+    selected.
+    """
+
+    @property
+    def rust_mod(self):
+        return _tsdownsample_rs.m4
+
+    @staticmethod
+    def _check_valid_n_out(n_out: int):
+        AbstractRustDownsampler._check_valid_n_out(n_out)
+        if n_out % 4 != 0:
+            raise ValueError("n_out must be a multiple of 4")
+
+
+class LTTBDownsampler(AbstractRustDownsampler):
+    """Downsampler that uses the LTTB algorithm."""
+
+    @property
+    def rust_mod(self):
+        return _tsdownsample_rs.lttb
+
+
+class MinMaxLTTBDownsampler(AbstractRustDownsampler):
+    """Downsampler that uses the MinMaxLTTB algorithm. If the y data contains NaNs,
+    these are ignored (i.e. the NaNs are not taken into account when selecting data
+    points).
+
+    MinMaxLTTB paper: https://arxiv.org/abs/2305.00332
+    """
+
+    @property
+    def rust_mod(self):
+        return _tsdownsample_rs.minmaxlttb
+
+    def downsample(
+        self, *args, n_out: int, minmax_ratio: int = 4, parallel: bool = False, **_
+    ):
+        assert minmax_ratio > 0, "minmax_ratio must be greater than 0"
+        return super().downsample(
+            *args, n_out=n_out, parallel=parallel, ratio=minmax_ratio
+        )
+
+
+class NaNMinMaxLTTBDownsampler(AbstractRustNaNDownsampler):
+    """Downsampler that uses the MinMaxLTTB algorithm. If the y data contains NaNs, the
+    indices of these NaNs are returned.
+
+    MinMaxLTTB paper: https://arxiv.org/abs/2305.00332
+    """
+
+    @property
+    def rust_mod(self):
+        return _tsdownsample_rs.minmaxlttb
+
+    def downsample(
+        self, *args, n_out: int, minmax_ratio: int = 4, parallel: bool = False, **_
+    ):
+        assert minmax_ratio > 0, "minmax_ratio must be greater than 0"
+        return super().downsample(
+            *args, n_out=n_out, parallel=parallel, ratio=minmax_ratio
+        )
+
+
+# ------------------ EveryNth Downsampler ------------------
+
+
+class EveryNthDownsampler(AbstractDownsampler):
+    """Downsampler that selects every nth data point"""
+
+    def __init__(self, **kwargs):
+        super().__init__(check_contiguous=False, **kwargs)
+
+    def _downsample(
+        self, x: Union[np.ndarray, None], y: np.ndarray, n_out: int, **_
+    ) -> np.ndarray:
+        if x is not None:
+            name = self.__class__.__name__
+            warnings.warn(
+                f"x is passed to downsample method of {name}, but is not taken "
+                "into account by the current implementation of the EveryNth algorithm."
+            )
+        step = max(1, len(y) / n_out)
+        return np.arange(start=0, stop=len(y) - 0.1, step=step).astype(np.uint)

tsdownsample/downsampling_interface.py

@@ -0,0 +1,432 @@
+"""AbstractDownsampler interface-class, subclassed by concrete downsamplers."""
+
+__author__ = "Jeroen Van Der Donckt"
+
+import re
+import warnings
+from abc import ABC, abstractmethod
+from copy import deepcopy
+from types import ModuleType
+from typing import Callable, List, Optional, Tuple, Union
+
+import numpy as np
+
+
+class AbstractDownsampler(ABC):
+    """AbstractDownsampler interface-class, subclassed by concrete downsamplers."""
+
+    def __init__(
+        self,
+        check_contiguous: bool = True,
+        x_dtype_regex_list: Optional[List[str]] = None,
+        y_dtype_regex_list: Optional[List[str]] = None,
+    ):
+        self.check_contiguous = check_contiguous
+        self.x_dtype_regex_list = x_dtype_regex_list
+        self.y_dtype_regex_list = y_dtype_regex_list
+
+    def _check_contiguous(self, arr: np.ndarray, y: bool = True):
+        # necessary for rust downsamplers as they don't support non-contiguous arrays
+        # (we call .as_slice().unwrap() on the array) in the lib.rs file
+        # which will panic if the array is not contiguous
+        if not self.check_contiguous:
+            return
+
+        if arr.flags["C_CONTIGUOUS"]:
+            return
+
+        raise ValueError(f"{'y' if y else 'x'} array must be contiguous.")
+
+    def _supports_dtype(self, arr: np.ndarray, y: bool = True):
+        dtype_regex_list = self.y_dtype_regex_list if y else self.x_dtype_regex_list
+        # base case
+        if dtype_regex_list is None:
+            return
+
+        for dtype_regex_str in dtype_regex_list:
+            m = re.compile(dtype_regex_str).match(str(arr.dtype))
+            if m is not None:  # a match is found
+                return
+        raise ValueError(
+            f"{arr.dtype} doesn't match with any regex in {dtype_regex_list} "
+            f"for the {'y' if y else 'x'}-data"
+        )
+
+    @staticmethod
+    def _check_valid_downsample_args(
+        *args,
+    ) -> Tuple[Union[np.ndarray, None], np.ndarray]:
+        if len(args) == 2:
+            x, y = args
+        elif len(args) == 1:
+            x, y = None, args[0]
+        else:
+            raise ValueError(
+                "downsample() takes 1 or 2 positional arguments but "
+                f"{len(args)} were given"
+            )
+
+        if x is not None and not isinstance(x, np.ndarray):
+            x = np.array(x)
+        if not isinstance(y, np.ndarray):
+            y = np.array(y)
+
+        # y must be 1D array
+        if y.ndim != 1:
+            raise ValueError("y must be 1D array")
+        # x must be 1D array with same length as y or None
+        if x is not None:
+            if x.ndim != 1:
+                raise ValueError("x must be 1D array")
+            if len(x) != len(y):
+                raise ValueError("x and y must have the same length")
+
+        return x, y
+
+    @staticmethod
+    def _check_valid_n_out(n_out: int):
+        if n_out <= 0:
+            raise ValueError("n_out must be greater than 0")
+
+    @abstractmethod
+    def _downsample(
+        self, x: Union[np.ndarray, None], y: np.ndarray, n_out: int, **kwargs
+    ) -> np.ndarray:
+        """Downsample the data in x and y.
+
+        Returns
+        -------
+        np.ndarray
+            The selected indices.
+        """
+        raise NotImplementedError
+
+    def downsample(self, *args, n_out: int, **kwargs):  # x and y are optional
+        """Downsample y (and x).
+
+        Call signatures::
+            downsample([x], y, n_out, **kwargs)
+
+
+        Parameters
+        ----------
+        x, y : array-like
+            The horizontal / vertical coordinates of the data points.
+            *x* values are optional.
+            These parameters should be 1D arrays.
+            These arguments cannot be passed as keywords.
+        n_out : int
+            The number of points to keep.
+        **kwargs
+            Additional keyword arguments are passed to the downsampler.
+
+        Returns
+        -------
+        np.ndarray
+            The selected indices.
+        """
+        self._check_valid_n_out(n_out)
+        x, y = self._check_valid_downsample_args(*args)
+        self._supports_dtype(y, y=True)
+        self._check_contiguous(y, y=True)
+        if x is not None:
+            self._supports_dtype(x, y=False)
+            self._check_contiguous(x, y=False)
+        return self._downsample(x, y, n_out, **kwargs)
+
+
+# ------------------- Rust Downsample Interface -------------------
+DOWNSAMPLE_F = "downsample"
+
+
+# the following dtypes are supported by the rust downsamplers (x and y)
+_rust_dtypes = [
+    "float32",
+    "float64",
+    "uint16",
+    "uint32",
+    "uint64",
+    "int16",
+    "int32",
+    "int64",
+    "datetime64",
+    "timedelta64",
+]
+# <= 8-bit x-dtypes are not supported as the range of the values is too small to require
+# downsampling
+_y_rust_dtypes = _rust_dtypes + ["float16", "int8", "uint8", "bool"]
+
+
+class AbstractRustDownsampler(AbstractDownsampler, ABC):
+    """RustDownsampler interface-class, subclassed by concrete downsamplers."""
+
+    def __init__(self):
+        super().__init__(True, _rust_dtypes, _y_rust_dtypes)  # same for x and y
+
+    @property
+    def _downsample_func_prefix(self) -> str:
+        """The prefix of the downsample functions in the rust module."""
+        return DOWNSAMPLE_F
+
+    @property
+    def rust_mod(self) -> ModuleType:
+        """The compiled Rust module for the current downsampler."""
+        raise NotImplementedError
+
+    @property
+    def mod_single_core(self) -> ModuleType:
+        """Get the single-core Rust module.
+
+        Returns
+        -------
+        ModuleType
+            If SIMD compiled module is available, that one is returned. Otherwise, the
+            scalar compiled module is returned.
+        """
+        return self.rust_mod.sequential
+
+    @property
+    def mod_multi_core(self) -> Union[ModuleType, None]:
+        """Get the multi-core Rust module.
+
+        Returns
+        -------
+        ModuleType or None
+            If SIMD parallel compiled module is available, that one is returned.
+            Otherwise, the scalar parallel compiled module is returned.
+            If no parallel compiled module is available, None is returned.
+        """
+        if hasattr(self.rust_mod, "parallel"):
+            # use SIMD implementation if available
+            return self.rust_mod.parallel
+        return None  # no parallel compiled module available
+
+    @staticmethod
+    def _view_x(x: np.ndarray) -> np.ndarray:
+        """View the x-data as different dtype (if necessary)."""
+        if np.issubdtype(x.dtype, np.datetime64):
+            # datetime64 is viewed as int64
+            return x.view(dtype=np.int64)
+        elif np.issubdtype(x.dtype, np.timedelta64):
+            # timedelta64 is viewed as int64
+            return x.view(dtype=np.int64)
+        return x
+
+    @staticmethod
+    def _view_y(y: np.ndarray) -> np.ndarray:
+        """View the y-data as different dtype (if necessary)."""
+        if y.dtype == "bool":
+            # bool is viewed as int8
+            return y.view(dtype=np.int8)
+        elif np.issubdtype(y.dtype, np.datetime64):
+            # datetime64 is viewed as int64
+            return y.view(dtype=np.int64)
+        elif np.issubdtype(y.dtype, np.timedelta64):
+            # timedelta64 is viewed as int64
+            return y.view(dtype=np.int64)
+        return y
+
+    def _switch_mod_with_y(
+        self, y_dtype: np.dtype, mod: ModuleType, downsample_func: Optional[str] = None
+    ) -> Callable:
+        """Select the appropriate function from the rust module for the y-data.
+
+        Assumes equal binning (when no data for x is passed -> only this function is
+        executed).
+        Equidistant binning is  utilized when a `downsample_func` is passed from the
+        `_switch_mod_with_x_and_y` method (since the x-data is considered in the
+        downsampling).
+
+        Parameters
+        ----------
+        y_dtype : np.dtype
+            The dtype of the y-data
+        mod : ModuleType
+            The module to select the appropriate function from
+        downsample_func : str, optional
+            The name of the function to use, by default DOWNSAMPLE_FUNC.
+            This argument is passed from the `_switch_mod_with_x_and_y` method when
+            the x-data is considered in the downsampling.
+        """
+        if downsample_func is None:
+            downsample_func = self._downsample_func_prefix
+        # FLOATS
+        if np.issubdtype(y_dtype, np.floating):
+            if y_dtype == np.float16:
+                return getattr(mod, downsample_func + "_f16")
+            elif y_dtype == np.float32:
+                return getattr(mod, downsample_func + "_f32")
+            elif y_dtype == np.float64:
+                return getattr(mod, downsample_func + "_f64")
+        # UINTS
+        elif np.issubdtype(y_dtype, np.unsignedinteger):
+            if y_dtype == np.uint8:
+                return getattr(mod, downsample_func + "_u8")
+            elif y_dtype == np.uint16:
+                return getattr(mod, downsample_func + "_u16")
+            elif y_dtype == np.uint32:
+                return getattr(mod, downsample_func + "_u32")
+            elif y_dtype == np.uint64:
+                return getattr(mod, downsample_func + "_u64")
+        # INTS (need to be last because uint is subdtype of int)
+        elif np.issubdtype(y_dtype, np.integer):
+            if y_dtype == np.int8:
+                return getattr(mod, downsample_func + "_i8")
+            elif y_dtype == np.int16:
+                return getattr(mod, downsample_func + "_i16")
+            elif y_dtype == np.int32:
+                return getattr(mod, downsample_func + "_i32")
+            elif y_dtype == np.int64:
+                return getattr(mod, downsample_func + "_i64")
+        # DATETIME -> i64 (datetime64 is viewed as int64)
+        # TIMEDELTA -> i64 (timedelta64 is viewed as int64)
+        # BOOLS -> int8 (bool is viewed as int8)
+        raise ValueError(f"Unsupported data type (for y): {y_dtype}")
+
+    def _switch_mod_with_x_and_y(
+        self,  # necessary to access the class its _switch_mod_with_y method
+        x_dtype: np.dtype,
+        y_dtype: np.dtype,
+        mod: ModuleType,
+        downsample_func: Optional[str] = None,
+    ) -> Callable:
+        """The x-data is considered in the downsampling
+
+        Assumes equal binning.
+
+        Parameters
+        ----------
+        x_dtype : np.dtype
+            The dtype of the x-data
+        y_dtype : np.dtype
+            The dtype of the y-data
+        mod : ModuleType
+            The module to select the appropriate function from
+        downsample_func : str, optional
+            The name of the function to use, by default DOWNSAMPLE_FUNC.
+        """
+        if downsample_func is None:
+            downsample_func = self._downsample_func_prefix
+        # FLOATS
+        if np.issubdtype(x_dtype, np.floating):
+            if x_dtype == np.float16:
+                return self._switch_mod_with_y(y_dtype, mod, f"{downsample_func}_f16")
+            elif x_dtype == np.float32:
+                return self._switch_mod_with_y(y_dtype, mod, f"{downsample_func}_f32")
+            elif x_dtype == np.float64:
+                return self._switch_mod_with_y(y_dtype, mod, f"{downsample_func}_f64")
+        # UINTS
+        elif np.issubdtype(x_dtype, np.unsignedinteger):
+            if x_dtype == np.uint16:
+                return self._switch_mod_with_y(y_dtype, mod, f"{downsample_func}_u16")
+            elif x_dtype == np.uint32:
+                return self._switch_mod_with_y(y_dtype, mod, f"{downsample_func}_u32")
+            elif x_dtype == np.uint64:
+                return self._switch_mod_with_y(y_dtype, mod, f"{downsample_func}_u64")
+        # INTS (need to be last because uint is subdtype of int)
+        elif np.issubdtype(x_dtype, np.integer):
+            if x_dtype == np.int16:
+                return self._switch_mod_with_y(y_dtype, mod, f"{downsample_func}_i16")
+            elif x_dtype == np.int32:
+                return self._switch_mod_with_y(y_dtype, mod, f"{downsample_func}_i32")
+            elif x_dtype == np.int64:
+                return self._switch_mod_with_y(y_dtype, mod, f"{downsample_func}_i64")
+        # DATETIME -> i64 (datetime64 is viewed as int64)
+        # TIMEDELTA -> i64 (timedelta64 is viewed as int64)
+        raise ValueError(f"Unsupported data type (for x): {x_dtype}")
+
+    def _downsample(
+        self,
+        x: Union[np.ndarray, None],
+        y: np.ndarray,
+        n_out: int,
+        parallel: bool = False,
+        **kwargs,
+    ) -> np.ndarray:
+        """Downsample the data in x and y."""
+        mod = self.mod_single_core
+        if parallel:
+            if self.mod_multi_core is None:
+                name = self.__class__.__name__
+                warnings.warn(
+                    f"No parallel implementation available for {name}. "
+                    "Falling back to single-core implementation."
+                )
+            else:
+                mod = self.mod_multi_core
+        ## Viewing the y-data as different dtype (if necessary)
+        y = self._view_y(y)
+        ## Viewing the x-data as different dtype (if necessary)
+        if x is None:
+            downsample_f = self._switch_mod_with_y(y.dtype, mod)
+            return downsample_f(y, n_out, **kwargs)
+        x = self._view_x(x)
+        ## Getting the appropriate downsample function
+        downsample_f = self._switch_mod_with_x_and_y(x.dtype, y.dtype, mod)
+        return downsample_f(x, y, n_out, **kwargs)
+
+    def downsample(self, *args, n_out: int, parallel: bool = False, **kwargs):
+        """Downsample the data in x and y.
+
+        The x and y arguments are positional-only arguments. If only one argument is
+        passed, it is considered to be the y-data. If two arguments are passed, the
+        first argument is considered to be the x-data and the second argument is
+        considered to be the y-data.
+        """
+        return super().downsample(*args, n_out=n_out, parallel=parallel, **kwargs)
+
+    def __deepcopy__(self, memo):
+        """Deepcopy the object."""
+        cls = self.__class__
+        result = cls.__new__(cls)
+        memo[id(self)] = result
+        for k, v in self.__dict__.items():
+            if k.endswith("_mod") or k.startswith("mod_"):
+                # Don't (deep)copy the compiled modules
+                setattr(result, k, v)
+            else:
+                setattr(result, k, deepcopy(v, memo))
+        return result
+
+
+NAN_DOWNSAMPLE_F = "downsample_nan"
+
+
+class AbstractRustNaNDownsampler(AbstractRustDownsampler, ABC):
+    """RustNaNDownsampler interface-class, subclassed by concrete downsamplers."""
+
+    @property
+    def _downsample_func_prefix(self) -> str:
+        """The prefix of the downsample functions in the rust module."""
+        return NAN_DOWNSAMPLE_F
+
+    def _switch_mod_with_y(
+        self, y_dtype: np.dtype, mod: ModuleType, downsample_func: Optional[str] = None
+    ) -> Callable:
+        """Select the appropriate function from the rust module for the y-data.
+
+        Assumes equal binning (when no data for x is passed -> only this function is
+        executed).
+        Equidistant binning is  utilized when a `downsample_func` is passed from the
+        `_switch_mod_with_x_and_y` method (since the x-data is considered in the
+        downsampling).
+
+        Parameters
+        ----------
+        y_dtype : np.dtype
+            The dtype of the y-data
+        mod : ModuleType
+            The module to select the appropriate function from
+        downsample_func : str, optional
+            The name of the function to use, by default NAN_DOWNSAMPLE_F.
+            This argument is passed from the `_switch_mod_with_x_and_y` method when
+            the x-data is considered in the downsampling.
+        """
+        if downsample_func is None:
+            downsample_func = self._downsample_func_prefix
+        if not np.issubdtype(y_dtype, np.floating):
+            # When y is not a float, we need to remove the _nan suffix to use the
+            # regular downsample function as the _nan suffix is only used for floats.
+            # (Note that NaNs only exist for floats)
+            downsample_func = downsample_func.replace("_nan", "")
+        return super()._switch_mod_with_y(y_dtype, mod, downsample_func)

tsdownsample-0.1.4.1rc0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: tsdownsample
+Version: 0.1.4.1rc0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Dist: numpy
+License-File: LICENSE
+Summary: Time series downsampling in rust
+Keywords: time series,downsampling,rust,data science,visualization
+Author: Jeroen Van Der Donckt
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/predict-idlab/tsdownsample
+Project-URL: Repository, https://github.com/predict-idlab/tsdownsample
+
+# tsdownsample
+
+[![PyPI Latest Release](https://img.shields.io/pypi/v/tsdownsample.svg)](https://pypi.org/project/tsdownsample/)
+[![support-version](https://img.shields.io/pypi/pyversions/tsdownsample)](https://img.shields.io/pypi/pyversions/tsdownsample)
+[![Downloads](https://static.pepy.tech/badge/tsdownsample)](https://pepy.tech/project/tsdownsample)
+[![CodeQL](https://github.com/predict-idlab/tsdownsample/actions/workflows/codeql.yml/badge.svg)](https://github.com/predict-idlab/tsdownsample/actions/workflows/codeql.yml)
+[![Testing](https://github.com/predict-idlab/tsdownsample/actions/workflows/ci-downsample_rs.yml/badge.svg)](https://github.com/predict-idlab/tsdownsample/actions/workflows/ci-downsample_rs.yml)
+[![Testing](https://github.com/predict-idlab/tsdownsample/actions/workflows/ci-tsdownsample.yml/badge.svg)](https://github.com/predict-idlab/tsdownsample/actions/workflows/ci-tsdownsample.yml)
+[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white)](https://discord.gg/k2d59GrxPX)
+
+<!-- TODO: codecov -->
+
+Extremely fast **time series downsampling 📈** for visualization, written in Rust.
+
+## Features ✨
+
+- **Fast**: written in rust with PyO3 bindings
+  - leverages optimized [argminmax](https://github.com/jvdd/argminmax) - which is SIMD accelerated with runtime feature detection
+  - scales linearly with the number of data points
+  <!-- TODO check if it scales sublinearly -->
+  - multithreaded with Rayon (in Rust)
+    <details>
+      <summary><i>Why we do not use Python multiprocessing</i></summary>
+      Citing the <a href="https://pyo3.rs/v0.17.3/parallelism.html">PyO3 docs on parallelism</a>:<br>
+      <blockquote>
+          CPython has the infamous Global Interpreter Lock, which prevents several threads from executing Python bytecode in parallel. This makes threading in Python a bad fit for CPU-bound tasks and often forces developers to accept the overhead of multiprocessing.
+      </blockquote>
+      In Rust - which is a compiled language - there is no GIL, so CPU-bound tasks can be parallelized (with <a href="https://github.com/rayon-rs/rayon">Rayon</a>) with little to no overhead.
+    </details>
+- **Efficient**: memory efficient
+  - works on views of the data (no copies)
+  - no intermediate data structures are created
+- **Flexible**: works on any type of data
+  - supported datatypes are
+    - for `x`: `f32`, `f64`, `i16`, `i32`, `i64`, `u16`, `u32`, `u64`, `datetime64`, `timedelta64`
+    - for `y`: `f16`, `f32`, `f64`, `i8`, `i16`, `i32`, `i64`, `u8`, `u16`, `u32`, `u64`, `datetime64`, `timedelta64`, `bool`
+    <details>
+      <summary><i>!! 🚀 <code>f16</code> <a href="https://github.com/jvdd/argminmax">argminmax</a> is 200-300x faster than numpy</i></summary>
+      In contrast with all other data types above, <code>f16</code> is *not* hardware supported (i.e., no instructions for f16) by most modern CPUs!! <br>
+      🐌 Programming languages facilitate support for this datatype by either (i) upcasting to <u>f32</u> or (ii) using a software implementation. <br>
+      💡 As for argminmax, only comparisons are needed - and thus no arithmetic operations - creating a <u>symmetrical ordinal mapping from <code>f16</code> to <code>i16</code></u> is sufficient. This mapping allows to use the hardware supported scalar and SIMD <code>i16</code> instructions - while not producing any memory overhead 🎉 <br>
+      <i>More details are described in <a href="https://github.com/jvdd/argminmax/pull/1">argminmax PR #1</a>.</i>
+    </details>
+- **Easy to use**: simple & flexible API
+
+## Install
+
+```bash
+pip install tsdownsample
+```
+
+## Usage
+
+```python
+from tsdownsample import MinMaxLTTBDownsampler
+import numpy as np
+
+# Create a time series
+y = np.random.randn(10_000_000)
+x = np.arange(len(y))
+
+# Downsample to 1000 points (assuming constant sampling rate)
+s_ds = MinMaxLTTBDownsampler().downsample(y, n_out=1000)
+
+# Select downsampled data
+downsampled_y = y[s_ds]
+
+# Downsample to 1000 points using the (possible irregularly spaced) x-data
+s_ds = MinMaxLTTBDownsampler().downsample(x, y, n_out=1000)
+
+# Select downsampled data
+downsampled_x = x[s_ds]
+downsampled_y = y[s_ds]
+```
+
+## Downsampling algorithms & API
+
+### Downsampling API 📑
+
+Each downsampling algorithm is implemented as a class that implements a `downsample` method.
+The signature of the `downsample` method:
+
+```
+downsample([x], y, n_out, **kwargs) -> ndarray[uint64]
+```
+
+**Arguments**:
+
+- `x` is optional
+- `x` and `y` are both positional arguments
+- `n_out` is a mandatory keyword argument that defines the number of output values<sup>*</sup>
+- `**kwargs` are optional keyword arguments *(see [table below](#downsampling-algorithms-📈))*:
+  - `parallel`: whether to use multi-threading (default: `False`)  
+     ❗ The max number of threads can be configured with the `TSDOWNSAMPLE_MAX_THREADS` ENV var (e.g. `os.environ["TSDOWNSAMPLE_MAX_THREADS"] = "4"`)
+  - ...
+
+**Returns**: a `ndarray[uint64]` of indices that can be used to index the original data.
+
+<sup>\*</sup><i>When there are gaps in the time series, fewer than `n_out` indices may be returned.</i>
+
+### Downsampling algorithms 📈
+
+The following downsampling algorithms (classes) are implemented:
+
+| Downsampler | Description | `**kwargs` |
+| ---:| --- |--- |
+| `MinMaxDownsampler` | selects the **min and max** value in each bin | `parallel` |
+| `M4Downsampler` | selects the [**min, max, first and last**](https://dl.acm.org/doi/pdf/10.14778/2732951.2732953) value in each bin | `parallel` |
+| `LTTBDownsampler` | performs the [**Largest Triangle Three Buckets**](https://skemman.is/bitstream/1946/15343/3/SS_MSthesis.pdf) algorithm | `parallel` |
+| `MinMaxLTTBDownsampler` | (*new two-step algorithm 🎉*) first selects `n_out` * `minmax_ratio` **min and max** values, then further reduces these to `n_out` values using the **Largest Triangle Three Buckets** algorithm | `parallel`, `minmax_ratio`<sup>*</sup> |
+
+<sup>*</sup><i>Default value for `minmax_ratio` is 4, which is empirically proven to be a good default. More details here: https://arxiv.org/abs/2305.00332</i>
+
+### Handling NaNs
+
+This library supports two `NaN`-policies:
+
+1. Omit `NaN`s (`NaN`s are ignored during downsampling).
+2. Return index of first `NaN` once there is at least one present in the bin of the considered data.
+
+|             Omit `NaN`s | Return `NaN`s              |
+| ----------------------: | :------------------------- |
+|     `MinMaxDownsampler` | `NaNMinMaxDownsampler`     |
+|         `M4Downsampler` | `NaNM4Downsampler`         |
+| `MinMaxLTTBDownsampler` | `NaNMinMaxLTTBDownsampler` |
+|       `LTTBDownsampler` |                            |
+
+> Note that NaNs are not supported for `x`-data.
+
+## Limitations & assumptions 🚨
+
+Assumes;
+
+1. `x`-data is (non-strictly) monotonic increasing (i.e., sorted)
+2. no `NaN`s in `x`-data
+
+---
+
+<p align="center">
+👤 <i>Jeroen Van Der Donckt</i>
+</p>
+

tsdownsample-0.1.4.1rc0.dist-info/RECORD

@@ -0,0 +1,11 @@
+tsdownsample-0.1.4.1rc0.dist-info/METADATA,sha256=e0y2YyFZrhjUCV7jAlAtwdP7_a4YO76Xw0ceznp8HiU,8160
+tsdownsample-0.1.4.1rc0.dist-info/WHEEL,sha256=Dg5iAOm8hb2flCZz-g3oSBJ_MQUtfLw_2uuDTAM9fQs,94
+tsdownsample-0.1.4.1rc0.dist-info/licenses/LICENSE,sha256=NSbA8Qo_STXZvdmASn5697OCOsYtH2XwH5TNhODIKV8,1099
+tsdownsample/downsamplers.py,sha256=EIHJFYIx_vmag2m1swE7Irx29jivoL8o0fhB6KgtC_g,5034
+tsdownsample/downsampling_interface.py,sha256=vIZcALvdBHd0wm-EUon5d0sZYVeFqruQGmk-yZqS2zw,16701
+tsdownsample/_python/downsamplers.py,sha256=WOBaHama0BUOdiCBTuwA5j2v-LtTet3wyR9nGJRGC5A,8807
+tsdownsample/_python/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tsdownsample/_rust/__init__.py,sha256=J-7Wu5IPVJQOxeypg3Ta9Mu8Sx2vtw7vehjKEFKFugQ,59
+tsdownsample/__init__.py,sha256=Sy4yckabYwopsWppgqYeEEIxqC4XQTalH9Gq5L453HM,628
+tsdownsample/_rust/_tsdownsample_rs.cp39-win_amd64.pyd,sha256=FY0r-dagUSDlKDXVcBfqg38Unswth8p90qfx0D__hWk,5656576
+tsdownsample-0.1.4.1rc0.dist-info/RECORD,,

tsdownsample-0.1.4.1rc0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.8.1)
+Root-Is-Purelib: false
+Tag: cp39-cp39-win_amd64

tsdownsample-0.1.4.1rc0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Jeroen Van Der Donckt
+
+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.