Metadata-Version: 2.4
Name: matplotlib-window
Version: 1.2.0
Summary: Draggable data windowing for matplotlib plots
Author: sco1
Author-email: sco1 <sco1.git@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Typing :: Typed
Requires-Dist: matplotlib~=3.9
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/sco1/matplotlib-window
Project-URL: Documentation, https://github.com/sco1/matplotlib-window/blob/main/README.md
Project-URL: Repository, https://github.com/sco1/matplotlib-window.git
Project-URL: Issues, https://github.com/sco1/matplotlib-window/issues
Project-URL: Changelog, https://github.com/sco1/matplotlib-window/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# matplotlib-window
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/matplotlib-window/1.2.0?logo=python&logoColor=FFD43B)](https://pypi.org/project/matplotlib-window/)
[![PyPI](https://img.shields.io/pypi/v/matplotlib-window?logo=Python&logoColor=FFD43B)](https://pypi.org/project/matplotlib-window/)
[![PyPI - License](https://img.shields.io/pypi/l/matplotlib-window?color=magenta)](https://github.com/sco1/matplotlib-window/blob/main/LICENSE)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/sco1/matplotlib-window/main.svg)](https://results.pre-commit.ci/latest/github/sco1/matplotlib-window/main)

Draggable data windowing for matplotlib plots. Inspired by the adventures of past me and [`dragpy`](https://github.com/sco1-archive/dragpy).

![fixed window sample](/example/fixed_width_window.gif?raw=true)

## Interface
For most use cases, interaction with this library is done via the helper wrappers in `matplotlib_window.window`. These functions will accept the user data and build the plots directly for windowing.

#### Units
In addition to numeric data, plotted data and window `position`/`window_width` values may be of any type supported by matplotlib's unit conversion (e.g. `datetime`/`timedelta`, or NumPy's `datetime64`/`timedelta64`).

Returned window bounds are always provided in the axes' native float units; for datetime data these can be converted back to datetimes using [`matplotlib.dates.num2date`](https://matplotlib.org/stable/api/dates_api.html#matplotlib.dates.num2date).

### `fixed_window`
Plot the provided data & build a draggable fixed-width window to select bounds of interest; the x-locations of the edges of the window are returned once the figure window is closed.

#### Parameters
| Parameter      | Description                                                          | Type             | Default          |
|----------------|----------------------------------------------------------------------|------------------|------------------|
| `x_data`       | x data values to plot                                                | See: Note 1      | Required         |
| `y_data`       | y data values to plot                                                | See: Note 1      | Required         |
| `position`     | x-coordinate of the left edge of the window                          | See: Note 1      | Required         |
| `window_width` | Width, along the x-axis, of the draggable window                     | See: Note 1      | Required         |
| `snap_to_data` | Prevent dragging of the window beyond the bounds of the plotted data | `bool`           | `True`           |
| `axes_kwargs`  | Optional kwargs to pass to the `Axes` setter<sup>2</sup>             | `dict[str, Any]` | `{"title": ...}` |
| `plot_kwargs`  | Optional kwargs to pass to the plotting call<sup>3</sup>             | `dict[str, Any]` | `{}`             |

1. `int|float`, or any type supported by matplotlib's unit conversion, see: [Units](#units)
2. kwargs are passed directly to the `Axes` using `Axes.set()`, see the [`matplotlib.axes.Axes` documentation](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes) for supported arguments.
3. kwargs are passed directly to the plotting call, see the [`matplotlib.pyplot.plot` documentation](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.plot.html) for supported arguments.

### `flexible_window`
Plot the provided data & build a flexible-width window to select bounds of interest; the x-locations of the edges of the window are returned once the figure window is closed.

#### Parameters
| Parameter         | Description                                                          | Type             | Default          |
|-------------------|----------------------------------------------------------------------|----------------- |------------------|
| `x_data`          | x data values to plot                                                | See: Note 1      | Required         |
| `y_data`          | y data values to plot                                                | See: Note 1      | Required         |
| `position`        | x-coordinate of the left edge of the window                          | See: Note 1      | Required         |
| `window_width`    | Starting width, along the x-axis, of the flexible window             | See: Note 1      | Required         |
| `snap_to_data`    | Prevent dragging of the window beyond the bounds of the plotted data | `bool`           | `True`           |
| `allow_face_drag` | Allow dragging of the window using its face                          | `bool`           | `False`          |
| `axes_kwargs`     | Optional kwargs to pass to the `Axes` setter<sup>3</sup>             | `dict[str, Any]` | `{"title": ...}` |
| `plot_kwargs`     | Optional kwargs to pass to the plotting call<sup>4</sup>             | `dict[str, Any]` | `{}`             |

1. `int|float`, or any type supported by matplotlib's unit conversion, see: [Units](#units)
2. kwargs are passed directly to the `Axes` using `Axes.set()`, see the [`matplotlib.axes.Axes` documentation](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes) for supported arguments.
3. kwargs are passed directly to the plotting call, see the [`matplotlib.pyplot.plot` documentation](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.plot.html) for supported arguments.
