### Install tsdownsample

Source: https://github.com/predict-idlab/tsdownsample/blob/main/README.md

Install the tsdownsample package using pip. This command fetches and installs the latest version from PyPI.

```bash
pip install tsdownsample
```

--------------------------------

### Real-Time Stock Market Dashboard Setup

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/algorithm-guide.md

Initializes MinMaxLTTBDownsampler and numpy for a real-time stock market dashboard application.

```python
from tsdownsample import MinMaxLTTBDownsampler
import numpy as np

```

--------------------------------

### Install Python Test Dependencies

Source: https://github.com/predict-idlab/tsdownsample/blob/main/CONTRIBUTING.md

Installs the necessary Python dependencies for running tests.

```bash
pip install -r test/requirements.txt
```

--------------------------------

### Create NaNMinMaxLTTBDownsampler Instance

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/NaNMinMaxLTTBDownsampler.md

Instantiates the NaNMinMaxLTTBDownsampler. No parameters are required for basic setup.

```python
NaNMinMaxLTTBDownsampler()
```

--------------------------------

### Install Python Linting Dependencies

Source: https://github.com/predict-idlab/tsdownsample/blob/main/CONTRIBUTING.md

Installs the Python dependencies required for code linting.

```bash
pip install -r test/requirements-linting.txt
```

--------------------------------

### EveryNthDownsampler Example

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/algorithm-guide.md

Demonstrates the basic usage of EveryNthDownsampler for selecting every n-th data point. Useful for performance testing and as a baseline for quality comparison.

```python
from tsdownsample import EveryNthDownsampler
downsampler = EveryNthDownsampler()
indices = downsampler.downsample(y, n_out=1000)
```

```python
# Measuring algorithm overhead only
import time
y = np.random.randn(1_000_000)

ds_every = EveryNthDownsampler()
start = time.time()
indices = ds_every.downsample(y, n_out=1000)
print(f"EveryNth: {(time.time()-start)*1000:.2f}ms")

# Compare overhead of other algorithms relative to this
```

--------------------------------

### Install tsdownsample Locally

Source: https://github.com/predict-idlab/tsdownsample/blob/main/CONTRIBUTING.md

Installs the tsdownsample package locally from the project's root directory.

```bash
make install
```

--------------------------------

### EveryNthDownsampler Algorithm Calculation Example

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/EveryNthDownsampler.md

Illustrates the calculation of step size and selected indices for the EveryNthDownsampler algorithm, given input size and desired output points.

```python
# Input: 1000 points, want 100 output points
n = 1000
n_out = 100
step = max(1, 1000 / 100)  # step = 10
# Selected indices: [0, 10, 20, 30, ..., 990]
# Result: approximately 100 points
```

--------------------------------

### Install Nightly Rust

Source: https://github.com/predict-idlab/tsdownsample/blob/main/CONTRIBUTING.md

Installs the nightly version of the Rust toolchain, which is required for development.

```bash
rustup install nightly
```

--------------------------------

### Set Nightly Rust as Default

Source: https://github.com/predict-idlab/tsdownsample/blob/main/CONTRIBUTING.md

Sets the installed nightly Rust toolchain as the default for the project.

```bash
rustup default nightly
```

--------------------------------

### NaN Behavior Example

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/NaNMinMaxDownsampler.md

Demonstrates how NaN values are handled within a bin during downsampling. The index of the first NaN encountered in a bin will be included in the output indices.

```python
# When a bin contains NaN values
y = np.array([1.0, 2.0, np.nan, 3.0, 4.0])

downsampler = NaNMinMaxDownsampler()
indices = downsampler.downsample(y, n_out=4)
# Result will include the index of the NaN value (index 2)
# The actual indices depend on bin boundaries
```

--------------------------------

### Basic Downsampling with MinMaxLTTB

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/README.md

Demonstrates the fundamental usage of the MinMaxLTTBDownsampler to reduce the number of data points in a time series. Ensure numpy is installed and tsdownsample is imported.

```python
import numpy as np
from tsdownsample import MinMaxLTTBDownsampler

# Data
y = np.random.randn(1_000_000)
x = np.arange(len(y), dtype=np.float64)

# Downsample
ds = MinMaxLTTBDownsampler()
idx = ds.downsample(x, y, n_out=1000)

# Extract
down_y = y[idx]
down_x = x[idx]
```

--------------------------------

### Quick Start with MinMaxLTTBDownsampler

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/README.md

Demonstrates how to use the MinMaxLTTBDownsampler to downsample a large NumPy array. This snippet shows data creation, downsampling, and retrieval of downsampled data using the returned indices.

```python
from tsdownsample import MinMaxLTTBDownsampler
import numpy as np

# Create sample data
y = np.random.randn(10_000_000)
x = np.arange(len(y), dtype=np.float64)

# Downsample to 1000 points
downsampler = MinMaxLTTBDownsampler()
indices = downsampler.downsample(x, y, n_out=1000, minmax_ratio=4, parallel=True)

# Get downsampled data
down_x = x[indices]
down_y = y[indices]
```

--------------------------------

### Get Pixel-Perfect Visualization

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/INDEX.md

Employ M4Downsampler for pixel-perfect visualization, ensuring no data points are lost. The output size should be a multiple of 4 times the screen width.

```python
from tsdownsample import M4Downsampler
import numpy as np

screen_width = 1920
x = np.arange(100_000, dtype=np.float64)
y = np.random.randn(100_000)

downsampler = M4Downsampler()
indices = downsampler.downsample(x, y, n_out=screen_width * 4)

plot_x = x[indices]
plot_y = y[indices]
```

--------------------------------

### Accessing tsdownsample Version and Metadata

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/README.md

Shows how to retrieve the installed version and author information of the tsdownsample library using its module-level attributes.

```python
import tsdownsample

print(tsdownsample.__version__)  # "0.1.5.1"
print(tsdownsample.__author__)   # "Jeroen Van Der Donckt"
```

--------------------------------

### Robust Downsampling with Fallback Strategies

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/errors.md

Implement a robust downsampling function that attempts multiple strategies if the primary method fails. This example uses MinMaxLTTBDownsampler and falls back to EveryNthDownsampler upon encountering a ValueError.

```python
import numpy as np
from tsdownsample import MinMaxLTTBDownsampler, EveryNthDownsampler

def robust_downsample(x, y, n_out, max_retries=3):
    """Downsample with fallback strategies."""
    attempts = [
        ("MinMaxLTTB (default)", MinMaxLTTBDownsampler()),
        ("EveryNth (fallback)", EveryNthDownsampler()),
    ]
    
    for name, ds in attempts:
        try:
            indices = ds.downsample(x, y, n_out=n_out)
            print(f"Success with {name}")
            return indices
        except ValueError as e:
            print(f"Failed with {name}: {e}")
            continue
    
    raise RuntimeError("All downsampling attempts failed")
```

--------------------------------

### Downsample Time Series with MinMaxLTTB

Source: https://github.com/predict-idlab/tsdownsample/blob/main/README.md

Demonstrates downsampling a large NumPy array to a fixed number of points using the MinMaxLTTB algorithm. Assumes constant sampling rate for the initial example, then shows usage with irregular x-data.

```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]
```

--------------------------------

### Instantiate MinMaxLTTBDownsampler

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/MinMaxLTTBDownsampler.md

Create a new instance of the MinMaxLTTBDownsampler. No parameters are required for basic instantiation.

```python
from tsdownsample import MinMaxLTTBDownsampler

downsampler = MinMaxLTTBDownsampler()
```

--------------------------------

### Create MinMaxDownsampler Instance

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/MinMaxDownsampler.md

Instantiates a MinMaxDownsampler. No parameters are required for initialization.

```python
MinMaxDownsampler()
```

--------------------------------

### Initialize MinMaxLTTBDownsampler

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/algorithm-guide.md

Initializes the standard MinMaxLTTBDownsampler for an optimal balance of speed and quality, with a specified minmax_ratio.

```python
from tsdownsample import MinMaxLTTBDownsampler, NaNMinMaxLTTBDownsampler

# Standard (recommended)
ds = MinMaxLTTBDownsampler()
indices = ds.downsample(x, y, n_out=1000, minmax_ratio=4)
```

--------------------------------

### Create EveryNthDownsampler Instance

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/EveryNthDownsampler.md

Instantiates the EveryNthDownsampler. No parameters are required for initialization.

```python
from tsdownsample import EveryNthDownsampler

downsampler = EveryNthDownsampler()
```

--------------------------------

### Configure Downsampler Constructor Parameters

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/configuration.md

Customize downsampler behavior by passing parameters to the constructor. Control array contiguity checks and specify allowed data types using regex patterns.

```python
import numpy as np
from tsdownsample import MinMaxDownsampler

# Default: strict contiguity checking
ds = MinMaxDownsampler()

# Non-contiguous arrays (not recommended)
downsampler = MinMaxDownsampler()
# This will raise ValueError for non-contiguous arrays

# Custom dtype restrictions (rarely needed)
from tsdownsample.downsampling_interface import AbstractDownsampler
class CustomDownsampler(AbstractDownsampler):
    def __init__(self):
        super().__init__(
            check_contiguous=True,
            x_dtype_regex_list=["float64"],
            y_dtype_regex_list=["float64"]
        )
```

--------------------------------

### Handle ValueError for non-contiguous array

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/errors.md

Demonstrates catching a ValueError when an input array (x or y) is not C-contiguous. The example includes a fix using np.ascontiguousarray to create a contiguous copy.

```python
import numpy as np
from tsdownsample import MinMaxDownsampler

ds = MinMaxDownsampler()
y = np.random.randn(1000)
x = y[::2]  # Every other element - not contiguous!

try:
    indices = ds.downsample(x, y[::2], n_out=100)
except ValueError as e:
    print(f"Error: {e}")  # y array must be contiguous
    
    # Fix: create contiguous copy
    y_contig = np.ascontiguousarray(y[::2])
    indices = ds.downsample(x, y_contig, n_out=100)
```

--------------------------------

### Initialize Downsamplers

Source: https://github.com/predict-idlab/tsdownsample/blob/main/notebooks/benches.ipynb

Initializes instances of various time series downsampling algorithms from the tsdownsample library. Sets up parameters for benchmarking.

```python
import time
import timeit
from tsdownsample import MinMaxDownsampler, LTTBDownsampler, MinMaxLTTBDownsampler, M4Downsampler, EveryNthDownsampler

lttb_tsd = LTTBDownsampler()
minmax_tsd = MinMaxDownsampler()
minmaxlttb_tsd = MinMaxLTTBDownsampler()
m4_tsd = M4Downsampler()
everynth_tsd = EveryNthDownsampler()

minmax_ratio = 4

n_out = 2_000
```

--------------------------------

### Handle ValueError for non-1D array input

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/errors.md

Illustrates catching a ValueError when the input array 'y' is not one-dimensional. The example shows how to fix this by selecting a single dimension from a multi-dimensional array.

```python
import numpy as np
from tsdownsample import MinMaxDownsampler

ds = MinMaxDownsampler()
y_2d = np.random.randn(1000, 2)  # 2D array

try:
    indices = ds.downsample(y_2d, n_out=100)
except ValueError as e:
    print(f"Error: {e}")  # y must be 1D array
    
    # Fix: select single column
    indices = ds.downsample(y_2d[:, 0], n_out=100)
```

--------------------------------

### Importing All Downsampler Classes

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/README.md

Demonstrates the direct import statement for accessing all available downsampler classes from the tsdownsample library.

```python
from tsdownsample import (
    MinMaxDownsampler,
    M4Downsampler,
    LTTBDownsampler,
    MinMaxLTTBDownsampler,
    EveryNthDownsampler,
    NaNMinMaxDownsampler,
    NaNM4Downsampler,
    NaNMinMaxLTTBDownsampler,
)
```

--------------------------------

### Instantiate LTTBDownsampler

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/LTTBDownsampler.md

Creates a new LTTBDownsampler instance. No parameters are required for initialization.

```python
from tsdownsample import LTTBDownsampler

downsampler = LTTBDownsampler()
```

--------------------------------

### Create NaNMinMaxDownsampler Instance

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/NaNMinMaxDownsampler.md

Instantiates a NaNMinMaxDownsampler. No parameters are required for creation.

```python
NaNMinMaxDownsampler()
```

--------------------------------

### Cast Integers to Float for NaN Support

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/data-types.md

Before using NaN-aware downsamplers, cast integer arrays to a floating-point type to allow NaN values. This example shows casting an int64 array to float64.

```python
import numpy as np

# Cast integers to float for NaN support
y_int = np.array([1, 2, 3], dtype=np.int64)
y_float = y_int.astype(np.float64)
# Now can use with NaNMinMaxLTTBDownsampler

# Cast datetime to numeric for custom processing
y_datetime = np.array(['2024-01-01', '2024-01-02'], dtype='datetime64[D]')
y_numeric = y_datetime.astype(np.int64)  # Days since epoch
```

--------------------------------

### Create a Custom Downsampler

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/configuration.md

Shows how to create a custom downsampling algorithm by subclassing AbstractDownsampler. You can override default validation checks and implement custom downsampling logic.

```python
from tsdownsample.downsampling_interface import AbstractDownsampler
import numpy as np

class CustomDownsampler(AbstractDownsampler):
    def __init__(self, custom_param=None):
        super().__init__(
            check_contiguous=False,  # Allow non-contiguous
            x_dtype_regex_list=None,  # Any x type
            y_dtype_regex_list=None   # Any y type
        )
        self.custom_param = custom_param
    
    def _downsample(self, x, y, n_out, **kwargs):
        # Custom downsampling logic here
        return np.arange(n_out, dtype=np.uint64)

# Usage
custom_ds = CustomDownsampler(custom_param=42)
y = np.random.randn(10000)
indices = custom_ds.downsample(y, n_out=100)
```

--------------------------------

### Handle ValueError for odd n_out

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/errors.md

Shows how to catch and resolve a ValueError when n_out is an odd number, which is not supported by certain algorithms like MinMax and NaNMinMax. The example includes a fix to use an even number.

```python
from tsdownsample import MinMaxDownsampler

ds = MinMaxDownsampler()

# ValueError: n_out must be even
try:
    indices = ds.downsample(y, n_out=101)
except ValueError as e:
    print(f"Error: {e}")
    # Fix: use even number
    indices = ds.downsample(y, n_out=100)
```

--------------------------------

### Efficient Downsampling with Automatic Tuning

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/configuration.md

Configures the environment and imports tsdownsample, then defines a function to downsample efficiently by automatically tuning parallelization and minmax_ratio based on data size.

```python
import os
import sys
import numpy as np

# Configure environment before importing tsdownsample
os.environ["TSDOWNSAMPLE_MAX_THREADS"] = str(min(8, os.cpu_count()))

# Import after configuration
from tsdownsample import MinMaxLTTBDownsampler

def downsample_efficiently(y, target_points):
    """Downsample with automatic parameter tuning."""
    downsampler = MinMaxLTTBDownsampler()
    
    # Determine parallelization
    parallel = len(y) > 100_000
    
    # Determine minmax_ratio based on data size
    if len(y) > 10_000_000:
        minmax_ratio = 2  # Faster
    else:
        minmax_ratio = 4  # Default optimal
    
    return downsampler.downsample(
        y,
        n_out=target_points,
        minmax_ratio=minmax_ratio,
        parallel=parallel
    )
```

--------------------------------

### Clean and Prepare DataFrame for Plotting

Source: https://github.com/predict-idlab/tsdownsample/blob/main/notebooks/benches.ipynb

Cleans the 'dtype' column by extracting the last part of a string, filters rows starting with 'int', calculates a sort key, and sorts the DataFrame. It also computes 'mean_MB' and 'std_MB' columns for further analysis.

```python
sub_df["dtype"] = sub_df["dtype"].apply(
    lambda x: x.split(".")[-1].rstrip("'>")
)
sub_df = sub_df[sub_df["dtype"].str.startswith("int")]

sub_df["sort_key"] = sub_df["dtype"].str.replace("int", "").astype(int) * - 1
sub_df.sort_values(by=["sort_key", "N"], inplace=True)

sub_df["mean_MB"] = sub_df["mean"] / sub_df["MB"]
sub_df["std_MB"] = sub_df["std"] / sub_df["MB"]
```

--------------------------------

### MinMaxDownsampler and NaNMinMaxDownsampler Usage

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/algorithm-guide.md

Shows how to use MinMaxDownsampler for fast, good-quality downsampling and NaNMinMaxDownsampler for handling missing data. Both select the minimum and maximum values within each bin.

```python
from tsdownsample import MinMaxDownsampler, NaNMinMaxDownsampler

# Standard (no NaNs)
ds = MinMaxDownsampler()
indices = ds.downsample(x, y, n_out=1000)

# With NaN support
ds = NaNMinMaxDownsampler()
indices = ds.downsample(x, y, n_out=1000)
```

```python
# Real-time dashboard with 10M+ points
ds = MinMaxDownsampler()
indices = ds.downsample(large_array, n_out=2000, parallel=True)

# With missing data
ds = NaNMinMaxDownsampler()
indices = ds.downsample(sensor_data_with_gaps, n_out=1000)
```

--------------------------------

### Handle ValueError for unsupported data types

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/errors.md

Shows how to catch a ValueError when the input array's data type is not supported by the downsampler. The example demonstrates fixing this by casting the array to a supported type, such as using the absolute value for complex numbers.

```python
import numpy as np
from tsdownsample import MinMaxDownsampler

ds = MinMaxDownsampler()
y = np.array([1+2j, 3+4j, 5+6j] * 100, dtype=np.complex128)  # Complex numbers

try:
    indices = ds.downsample(y, n_out=100)
except ValueError as e:
    print(f"Error: {e}")  # complex128 doesn't match...
    
    # Fix: cast to supported type
    y_real = np.abs(y)  # Use magnitude
    indices = ds.downsample(y_real, n_out=100)
```

--------------------------------

### Generate Line Plot for Average Downsampling Time per Data Point

Source: https://github.com/predict-idlab/tsdownsample/blob/main/notebooks/benches.ipynb

This snippet creates a line plot to visualize the average downsampling time per data point for different algorithms. It calculates 'mean_N' and 'std_N' to represent this metric and uses plotly express for plotting, similar to the previous example but focusing on per-point efficiency.

```python
import plotly.express as px

algos_to_plot = [
    "MinMax",
    "M4",
    "MinMaxLTTB",
]

sub_df = df[df["algo_"].isin(algos_to_plot)].copy()
# clean the dtype column
sub_df["dtype"] = sub_df["dtype"].apply(
    lambda x: x.split(".")[-1].rstrip("'>")
)
sub_df = sub_df[sub_df["dtype"].str.startswith("int")]

sub_df["sort_key"] = sub_df["dtype"].str.replace("int", "").astype(int) * - 1
sub_df.sort_values(by=["sort_key", "N"], inplace=True)

sub_df["mean_N"] = sub_df["mean"] / sub_df["N"]
sub_df["std_N"] = sub_df["std"] / sub_df["N"]


fig = px.line(
    sub_df,
    x="N",
    y="mean_N",
    color="dtype",
    facet_col="algo_",
    # dash based on parallel
    line_dash="parallel",
    # facet_col="dtype",
    facet_col_wrap=3,
    error_y="std_N",
    # log_x=True,
    log_y=True,
    title="Downsampling time per data point (ms) vs. number of points",
    color_discrete_sequence=px.colors.qualitative.Pastel[:4][::-1],
)
fig.update_layout(
    template="plotly_white",
    height=550,
    width=1700,
    # update font size
    font=dict(
        size=20,
    ),
    # update legend font size
    legend=dict(
        font=dict(
            size=22,
        ),
    ),
)

fig.update_xaxes(title_text="Number of points")
# only show the y-axis title for the first column
fig.update_yaxes(title_text="Average time per data point (ms)", row=1, col=1)
# update the subplot titles
for i, title in enumerate(algos_to_plot):
    fig.layout.annotations[i].text = title
    fig.layout.annotations[i].font.size = 26
    fig.layout.annotations[i].font.family = "Arial"
# Update the line width to 3
for i, trace in enumerate(fig.data):
    fig.data[i].line.width = 3

# update the legend order to inverse the order of the legend
fig.update_layout(
    legend=dict(
        traceorder="normal",
    ),
)

fig.show(renderer="png")
```

--------------------------------

### Run Python Package Tests

Source: https://github.com/predict-idlab/tsdownsample/blob/main/CONTRIBUTING.md

Executes the test suite for the Python package using the Makefile.

```bash
make test
```

--------------------------------

### Adjusting MinMax Ratio for Downsampling Trade-offs

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/NaNMinMaxLTTBDownsampler.md

Demonstrates how to adjust the `minmax_ratio` parameter to control the trade-off between pre-selection speed and accuracy. Higher ratios are slower but more accurate.

```python
# Faster pre-selection (less accurate)
indices = downsampler.downsample(x, y, n_out=1000, minmax_ratio=2)

# Default (empirically optimal balance)
indices = downsampler.downsample(x, y, n_out=1000, minmax_ratio=4)

# More accurate pre-selection (slower)
indices = downsampler.downsample(x, y, n_out=1000, minmax_ratio=8)
```

--------------------------------

### Run Python Tests and Linting

Source: https://github.com/predict-idlab/tsdownsample/blob/main/CONTRIBUTING.md

Runs both the test suite and linting checks for the Python package.

```bash
make lint
```

--------------------------------

### Temporal Type Usage (datetime64, timedelta64)

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/data-types.md

Shows how to use datetime64 for timestamps and timedelta64 for durations with the MinMaxLTTBDownsampler. Ensure x-data is monotonically increasing.

```python
import numpy as np
from tsdownsample import MinMaxLTTBDownsampler

# datetime64 for timestamps
dates = np.arange('2024-01-01', '2024-02-01', dtype='datetime64[D]')
values = np.random.randn(len(dates))

ds = MinMaxLTTBDownsampler()
indices = ds.downsample(dates, values, n_out=10)

# timedelta64 for durations
durations = np.array([1, 2, 3, 4, 5], dtype='timedelta64[D]')
values = np.random.randn(len(durations))
indices = ds.downsample(durations, values, n_out=3)
```

--------------------------------

### Float Type Usage (float64, float32, float16)

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/data-types.md

Demonstrates using float64 for general purposes, float32 for space savings, and float16 for performance optimization with the MinMaxLTTBDownsampler. Ensure x-data is monotonically increasing.

```python
import numpy as np
from tsdownsample import MinMaxLTTBDownsampler

# Common case: float64 (most flexible)
y_float64 = np.array([1.234, 5.678, 9.012], dtype=np.float64)
x = np.arange(len(y_float64), dtype=np.float64)

ds = MinMaxLTTBDownsampler()
indices = ds.downsample(x, y_float64, n_out=2)

# Space savings: float32 (still good precision for most viz)
y_float32 = np.array([1.234, 5.678, 9.012], dtype=np.float32)
indices = ds.downsample(x, y_float32, n_out=2)

# Performance optimization: float16 (200-300× faster argminmax)
y_float16 = np.array([1.234, 5.678, 9.012], dtype=np.float16)
indices = ds.downsample(x, y_float16, n_out=2)
```

--------------------------------

### Create NaNM4Downsampler Instance

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/NaNM4Downsampler.md

Instantiates a NaNM4Downsampler object. No parameters are required for initialization.

```python
downsampler = NaNM4Downsampler()
```

--------------------------------

### M4Downsampler Constructor

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/M4Downsampler.md

Creates a new M4Downsampler instance. No parameters are required.

```APIDOC
## M4Downsampler()

### Description
Creates a new M4Downsampler instance.

### Parameters
None
```

--------------------------------

### Initialize NaNMinMaxLTTBDownsampler

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/algorithm-guide.md

Initializes the NaNMinMaxLTTBDownsampler to handle time series data with missing values, maintaining a balance of speed and quality.

```python
# With NaN support
ds = NaNMinMaxLTTBDownsampler()
indices = ds.downsample(x, y, n_out=1000, minmax_ratio=4)
```

--------------------------------

### Custom Algorithm Parameters for Downsampling

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/README.md

Shows how to adjust algorithm-specific parameters like minmax_ratio for higher quality downsampling or ensure n_out meets algorithm constraints (e.g., M4 requiring n_out to be a multiple of 4).

```python
# MinMaxLTTB with custom minmax_ratio
indices = downsampler.downsample(
    x, y,
    n_out=1000,
    minmax_ratio=8,      # Higher quality, slower
    parallel=True
)

# M4 requires n_out as multiple of 4
n_out = (desired // 4) * 4
indices = m4_ds.downsample(y, n_out=n_out)
```

--------------------------------

### M4Downsampler Constructor

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/M4Downsampler.md

Creates a new M4Downsampler instance. No parameters are required.

```python
M4Downsampler()
```

--------------------------------

### EveryNthDownsampler Constructor

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/EveryNthDownsampler.md

Creates a new EveryNthDownsampler instance. This downsampler does not require any parameters upon initialization.

```APIDOC
## EveryNthDownsampler()

### Description
Creates a new EveryNthDownsampler instance. No parameters required.

### Method
Constructor

### Parameters
None
```

--------------------------------

### M4Downsampler and NaNM4Downsampler Usage

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/algorithm-guide.md

Illustrates the use of M4Downsampler for pixel-perfect visualization and NaNM4Downsampler for handling NaNs. These algorithms select the first, min, max, and last values per bin.

```python
from tsdownsample import M4Downsampler, NaNM4Downsampler

# Standard
ds = M4Downsampler()
indices = ds.downsample(x, y, n_out=8000)  # Must be multiple of 4

# With NaN support
ds = NaNM4Downsampler()
indices = ds.downsample(x, y, n_out=4000)
```

```python
# Web dashboard: 1920px wide screen
screen_width = 1920
ds = M4Downsampler()
indices = ds.downsample(x, y, n_out=screen_width * 4)  # 7680 points
```

--------------------------------

### Handle x Parameter Ignored Warning

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/errors.md

Shows how to catch a UserWarning when the 'x' parameter is passed to EveryNthDownsampler, which is ignored. To avoid this warning, do not pass 'x' to the downsample method.

```python
import warnings
import numpy as np
from tsdownsample import EveryNthDownsampler

x = np.arange(1000)
y = np.random.randn(1000)

ds = EveryNthDownsampler()

# This generates a warning (but still works)
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    indices = ds.downsample(x, y, n_out=100)
    
    if len(w) > 0:
        print(f"Warning: {w[0].message}")

# To avoid: don't pass x
indices = ds.downsample(y, n_out=100)  # No warning
```

--------------------------------

### Test Rust Library

Source: https://github.com/predict-idlab/tsdownsample/blob/main/CONTRIBUTING.md

Runs tests for the Rust library component located in the downsample_rs directory.

```bash
cd downsample_rs
cargo test
```

--------------------------------

### MinMaxLTTBDownsampler Constructor

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/MinMaxLTTBDownsampler.md

Creates a new instance of the MinMaxLTTBDownsampler. This class implements a two-stage downsampling algorithm combining MinMax and LTTB for an optimal balance between speed and visual fidelity.

```APIDOC
## Constructor

```python
MinMaxLTTBDownsampler()
```

Creates a new MinMaxLTTBDownsampler instance. No parameters are required for initialization.
```

--------------------------------

### tsdownsample Project File Structure

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/INDEX.md

This snippet outlines the directory structure of the tsdownsample project, showing the location of key documentation files and the API reference.

```tree
output/
├── INDEX.md                          ← This file (navigation guide)
├── README.md                         ← Project overview and quick start
├── algorithm-guide.md                ← Algorithm selection and comparison
├── configuration.md                  ← Configuration options and tuning
├── data-types.md                     ← Supported types and conversion
├── errors.md                         ← Error handling and debugging
└── api-reference/                    ← Individual class documentation
    ├── AbstractDownsampler.md
    ├── MinMaxDownsampler.md
    ├── NaNMinMaxDownsampler.md
    ├── M4Downsampler.md
    ├── NaNM4Downsampler.md
    ├── LTTBDownsampler.md
    ├── MinMaxLTTBDownsampler.md
    ├── NaNMinMaxLTTBDownsampler.md
    └── EveryNthDownsampler.md
```

--------------------------------

### Save Benchmark Results

Source: https://github.com/predict-idlab/tsdownsample/blob/main/notebooks/benches.ipynb

Serializes the collected benchmark results (downsample_times dictionary) to a pickle file for later analysis.

```python
# pickle the downsample_times dict
import pickle

pickle.dump(downsample_times, open("downsample_times__v6.pkl", "wb"))
```

--------------------------------

### Baseline Algorithm Performance Comparison

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/algorithm-guide.md

Compares the performance of various tsdownsample algorithms by measuring their downsampling time on a large dataset. Useful for benchmarking and selecting the fastest option.

```python
from tsdownsample import *
import numpy as np
import time

y = np.random.randn(1_000_000)
target_points = 1000

algorithms = [
    ("EveryNth", EveryNthDownsampler()),
    ("MinMax", MinMaxDownsampler()),
    ("M4", M4Downsampler()),
    ("LTTB", LTTBDownsampler()),
    ("MinMaxLTTB", MinMaxLTTBDownsampler()),
]

for name, ds in algorithms:
    start = time.time()
    indices = ds.downsample(y, n_out=target_points)
    elapsed = (time.time() - start) * 1000
    print(f"{name:15} {elapsed:6.2f}ms")
```

--------------------------------

### Enable Verbose Logging for Debugging

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/errors.md

Enable debug logging and print array properties to help diagnose issues during downsampling. This snippet shows how to set up logging and inspect data characteristics like dtype, shape, contiguity, monotonicity, and NaN presence.

```python
import logging
import numpy as np

# Enable logging if available
logging.basicConfig(level=logging.DEBUG)

# Check array properties before downsampling
def debug_downsample(downsampler, x, y, n_out):
    print(f"x: dtype={x.dtype}, shape={x.shape}, C-contig={x.flags['C_CONTIGUOUS']}")
    print(f"y: dtype={y.dtype}, shape={y.shape}, C-contig={y.flags['C_CONTIGUOUS']}")
    print(f"n_out: {n_out}")
    print(f"x monotonic: {np.all(np.diff(x) >= 0)}")
    print(f"y has NaN: {np.any(np.isnan(y))}")
    
    return downsampler.downsample(x, y, n_out=n_out)
```

--------------------------------

### Ensure Even n_out for MinMax/NaNMinMax

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/errors.md

Illustrates how to handle a ValueError when n_out is odd for MinMax or NaNMinMax downsamplers. The solution involves ensuring n_out is even, either by adjusting the desired value or using a helper function.

```python
# Wrong
indices = downsampler.downsample(y, n_out=101)

# Right: ensure even
desired = 101
n_out = desired if desired % 2 == 0 else desired - 1
indices = downsampler.downsample(y, n_out=n_out)

# Or using helper function
def round_to_even(n):
    return (n // 2) * 2

indices = downsampler.downsample(y, n_out=round_to_even(101))
```

--------------------------------

### NaNM4Downsampler Constructor

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/api-reference/NaNM4Downsampler.md

Creates a new NaNM4Downsampler instance. This constructor does not require any parameters.

```APIDOC
## Constructor

```python
NaNM4Downsampler()
```

Creates a new NaNM4Downsampler instance. No parameters required.
```

--------------------------------

### Validate minmax_ratio > 0

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/errors.md

Demonstrates how to catch and fix an AssertionError when minmax_ratio is not greater than 0. Use a valid ratio to ensure correct downsampling.

```python
from tsdownsample import MinMaxLTTBDownsampler

ds = MinMaxLTTBDownsampler()

try:
    indices = ds.downsample(y, n_out=1000, minmax_ratio=0)
except AssertionError as e:
    print(f"Error: {e}")  # minmax_ratio must be greater than 0
    
    # Fix: use valid ratio
    indices = ds.downsample(y, n_out=1000, minmax_ratio=4)
```

--------------------------------

### Handle Parallel Fallback Warning

Source: https://github.com/predict-idlab/tsdownsample/blob/main/_autodocs/errors.md

Demonstrates catching a UserWarning when a parallel implementation is unavailable and the library falls back to a single-core version. This occurs for algorithms like LTTBDownsampler that lack a parallel variant.

```python
import warnings
import numpy as np
from tsdownsample import LTTBDownsampler

ds = LTTBDownsampler()
y = np.random.randn(1_000_000)

# LTTB doesn't have parallel implementation
with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    indices = ds.downsample(y, n_out=1000, parallel=True)
    
    if len(w) > 0:
        print(f"Warning: {w[0].message}")
```