lightspeed-series 0.0.1__tar.gz

lightspeed_series-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Hull
+
+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.

lightspeed_series-0.0.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: lightspeed-series
+Version: 0.0.1
+Summary: Fast, zoomable plots of very large series, from min/max level-of-detail pyramids cached in HDF5.
+Author-email: Mike Hull <mikehulluk@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mikehulluk/lightspeed
+Project-URL: Source, https://github.com/mikehulluk/lightspeed
+Project-URL: Issues, https://github.com/mikehulluk/lightspeed/issues
+Keywords: time series,large data,plotting,level of detail,hdf5,matplotlib,downsampling
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: filelock>=3.12
+Requires-Dist: h5py>=3.10
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=1.26
+Dynamic: license-file
+
+# lightspeed
+
+Fast, zoomable plots of very large series.
+
+A series of tens of millions of samples is too long to draw point by point.
+lightspeed reads it once, in chunks, and reduces it into a pyramid of min/max
+levels of detail, which it caches in an HDF5 file. A plot then asks for the
+x range in view at the resolution the axes can show, and gets back a
+min/max envelope of a few thousand buckets whatever the zoom - and the raw
+samples once you zoom in far enough. Spikes are never averaged away.
+
+The cache is keyed by a hash of the source's contents, so a second open of the
+same data is immediate, and several processes can share one cache directory.
+
+## Install
+
+```sh
+pip install lightspeed-series
+```
+
+The PyPI name is `lightspeed-series`; the import name is `lightspeed`.
+
+## Use
+
+```python
+import matplotlib.pyplot as plt
+from lightspeed import SourceSpec, ZoomSync, build_or_get_cache, close_cache
+
+# A 1-D dataset in an HDF5 file, sampled at x = 0, 1, 2, ...
+spec = SourceSpec.uniform("signal.h5", "/y", x0=0.0, dx=1.0)
+handle = build_or_get_cache(spec)
+
+fig, ax = plt.subplots()
+sync = ZoomSync(ax=ax, handle=handle, spec=spec)  # re-queries on pan and zoom
+plt.show()
+
+sync.disconnect()
+close_cache(handle)
+```
+
+`examples/demo.py` builds a 20-million-sample source and zooms into it.
+
+## Cache directory
+
+`build_or_get_cache(spec, cache_dir=...)` uses `cache_dir` if given; otherwise
+`$LIGHTSPEED_CACHE_DIR`, then `%LOCALAPPDATA%\Lightspeed\Cache` on Windows,
+`$XDG_CACHE_HOME/lightspeed`, or `~/.cache/lightspeed`.
+
+## Licence
+
+MIT.

lightspeed_series-0.0.1/README.md

@@ -0,0 +1,51 @@
+# lightspeed
+
+Fast, zoomable plots of very large series.
+
+A series of tens of millions of samples is too long to draw point by point.
+lightspeed reads it once, in chunks, and reduces it into a pyramid of min/max
+levels of detail, which it caches in an HDF5 file. A plot then asks for the
+x range in view at the resolution the axes can show, and gets back a
+min/max envelope of a few thousand buckets whatever the zoom - and the raw
+samples once you zoom in far enough. Spikes are never averaged away.
+
+The cache is keyed by a hash of the source's contents, so a second open of the
+same data is immediate, and several processes can share one cache directory.
+
+## Install
+
+```sh
+pip install lightspeed-series
+```
+
+The PyPI name is `lightspeed-series`; the import name is `lightspeed`.
+
+## Use
+
+```python
+import matplotlib.pyplot as plt
+from lightspeed import SourceSpec, ZoomSync, build_or_get_cache, close_cache
+
+# A 1-D dataset in an HDF5 file, sampled at x = 0, 1, 2, ...
+spec = SourceSpec.uniform("signal.h5", "/y", x0=0.0, dx=1.0)
+handle = build_or_get_cache(spec)
+
+fig, ax = plt.subplots()
+sync = ZoomSync(ax=ax, handle=handle, spec=spec)  # re-queries on pan and zoom
+plt.show()
+
+sync.disconnect()
+close_cache(handle)
+```
+
+`examples/demo.py` builds a 20-million-sample source and zooms into it.
+
+## Cache directory
+
+`build_or_get_cache(spec, cache_dir=...)` uses `cache_dir` if given; otherwise
+`$LIGHTSPEED_CACHE_DIR`, then `%LOCALAPPDATA%\Lightspeed\Cache` on Windows,
+`$XDG_CACHE_HOME/lightspeed`, or `~/.cache/lightspeed`.
+
+## Licence
+
+MIT.

lightspeed_series-0.0.1/examples/demo.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import h5py
+import matplotlib.pyplot as plt
+import numpy as np
+
+from lightspeed import SourceSpec, ZoomSync, build_or_get_cache, close_cache
+
+ROOT = Path(__file__).resolve().parent
+
+POINT_COUNT = 20_000_000
+CACHE_DIR = ROOT / "_build" / "demo-cache"
+SOURCE_PATH = ROOT / "_build" / "demo-source.h5"
+
+
+def build_synthetic_source() -> None:
+    SOURCE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    if SOURCE_PATH.exists():
+        return
+
+    print(f"Generating {POINT_COUNT:,} synthetic samples at {SOURCE_PATH}")
+    with h5py.File(SOURCE_PATH, "w") as handle:
+        dataset = handle.create_dataset("/y", shape=(POINT_COUNT,), dtype=np.float64)
+        block = 1_000_000
+        rng = np.random.default_rng(0)
+        for start in range(0, POINT_COUNT, block):
+            end = min(start + block, POINT_COUNT)
+            x = np.arange(start, end, dtype=np.float64)
+            values = (
+                np.sin(x * 0.0003)
+                + 0.3 * np.sin(x * 0.011)
+                + 0.02 * rng.standard_normal(end - start)
+            )
+            if start <= 3_500_000 < end:
+                spike_index = 3_500_000 - start
+                values[spike_index] += 6.0
+            dataset[start:end] = values
+
+
+def main() -> None:
+    build_synthetic_source()
+
+    spec = SourceSpec.uniform(SOURCE_PATH, "/y", x0=0.0, dx=1.0)
+
+    print("Building or reusing cache...")
+    handle = build_or_get_cache(spec, cache_dir=CACHE_DIR)
+    print(f"content_hash={handle.content_hash} n_levels={handle.n_levels}")
+
+    fig, ax = plt.subplots(figsize=(10, 4))
+    sync = ZoomSync(ax=ax, handle=handle, spec=spec)
+    ax.set_title("lightspeed demo: min/max envelope with live re-leveling")
+
+    print("Simulating pan/zoom...")
+    for x_start, x_end in [
+        (0, POINT_COUNT - 1),
+        (3_000_000, 4_000_000),
+        (3_450_000, 3_550_000),
+    ]:
+        ax.set_xlim(x_start, x_end)
+        fig.canvas.draw()
+        print(f"  xlim=({x_start}, {x_end}) -> level={sync._line_min.get_xdata().shape[0]} buckets")
+
+    output_path = ROOT / "_build" / "demo.png"
+    fig.savefig(output_path, dpi=150)
+    print(f"Saved {output_path}")
+
+    sync.disconnect()
+    plt.close(fig)
+    close_cache(handle)
+
+
+if __name__ == "__main__":
+    main()

lightspeed_series-0.0.1/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=77", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# The PyPI name. "lightspeed" is refused as too close to the existing
+# light-speed project, so the distribution is lightspeed-series; the import
+# name stays lightspeed.
+name = "lightspeed-series"
+# The version is the latest python-v* git tag (python-v0.0.1 -> 0.0.1);
+# commits after it get a .devN suffix. The Haskell package is tagged
+# haskell-v* and released on its own. See [tool.setuptools_scm].
+dynamic = ["version"]
+description = "Fast, zoomable plots of very large series, from min/max level-of-detail pyramids cached in HDF5."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mike Hull", email = "mikehulluk@gmail.com" }]
+keywords = ["time series", "large data", "plotting", "level of detail", "hdf5", "matplotlib", "downsampling"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Typing :: Typed",
+]
+dependencies = [
+    "filelock>=3.12",
+    "h5py>=3.10",
+    "matplotlib>=3.8",
+    "numpy>=1.26",
+]
+
+[dependency-groups]
+dev = ["pytest>=8.0", "build>=1.2", "twine>=5.0"]
+
+[project.urls]
+Homepage = "https://github.com/mikehulluk/lightspeed"
+Source = "https://github.com/mikehulluk/lightspeed"
+Issues = "https://github.com/mikehulluk/lightspeed/issues"
+
+[tool.setuptools_scm]
+# The git repository is the directory above this one.
+root = ".."
+fallback_version = "0.0.0"
+# Only python-v* tags count, so a Haskell release does not move this version.
+tag_regex = "^python-v(?P<version>[0-9]+(?:\\.[0-9]+)*(?:[-.+].*)?)$"
+
+[tool.setuptools_scm.scm.git]
+describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--match", "python-v*"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+lightspeed = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

lightspeed_series-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lightspeed_series-0.0.1/src/lightspeed/__init__.py

@@ -0,0 +1,43 @@
+"""Fast, zoomable plots of very large series.
+
+A series is reduced once into min/max level-of-detail pyramids, cached in
+an HDF5 file, and queried at the resolution the view needs.
+"""
+
+from .arraysource import ArraySource, HdfArraySource, SourceIdentity
+from .cache import CacheHandle, SourceSpec, build_or_get_cache, close_cache, open_existing_cache
+from .cachedir import resolve_cache_dir
+from .constants import DEFAULT_CHUNK_SIZE
+from .exceptions import (
+    CacheCorruptError,
+    InvalidSourceSpecError,
+    NonMonotonicXError,
+    LightspeedError,
+    UnsupportedQueryError,
+)
+from .mpl import ZoomSync, plot_envelope, update_envelope_artists
+from .query import QueryResult, full_x_range, query_range
+
+__all__ = [
+    "ArraySource",
+    "CacheCorruptError",
+    "CacheHandle",
+    "DEFAULT_CHUNK_SIZE",
+    "HdfArraySource",
+    "InvalidSourceSpecError",
+    "NonMonotonicXError",
+    "LightspeedError",
+    "QueryResult",
+    "SourceIdentity",
+    "SourceSpec",
+    "UnsupportedQueryError",
+    "ZoomSync",
+    "build_or_get_cache",
+    "close_cache",
+    "full_x_range",
+    "open_existing_cache",
+    "plot_envelope",
+    "query_range",
+    "resolve_cache_dir",
+    "update_envelope_artists",
+]

lightspeed_series-0.0.1/src/lightspeed/arraysource.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator, Protocol, runtime_checkable
+
+import h5py
+import numpy as np
+
+
+@runtime_checkable
+class ArraySource(Protocol):
+    """Disk-backed, random-seek 1-D numeric array data."""
+
+    @property
+    def length(self) -> int: ...
+
+    @property
+    def dtype(self) -> np.dtype: ...
+
+    def read_range(self, start: int, end: int) -> np.ndarray: ...
+
+    def iter_blocks(self, block_size: int) -> Iterator[np.ndarray]:
+        """Sequential streaming pass over the whole array, in order."""
+        ...
+
+    def close(self) -> None: ...
+
+
+@dataclass(frozen=True)
+class SourceIdentity:
+    """Enough information to detect whether an on-disk array has changed."""
+
+    path: Path
+    mtime_ns: int
+    size: int
+
+
+class HdfArraySource:
+    """Concrete ArraySource backed by one h5py Dataset in one HDF5 file.
+
+    A 1-D dataset as it stands, or one column of a 2-D (rows x columns)
+    dataset. Reading a column pulls each chunk the rows span in full and
+    keeps one column of it, so a first pass over a wide dataset costs its
+    whole width in I/O; the cache built from it is per column, and later
+    passes read from that.
+    """
+
+    def __init__(self, hdf5_path: Path, dataset_path: str, column: int | None = None) -> None:
+        self.hdf5_path = Path(hdf5_path)
+        self.dataset_path = dataset_path
+        self.column = column
+        self._file = h5py.File(self.hdf5_path, "r")
+        self._dataset = self._file[dataset_path]
+        if column is None:
+            if self._dataset.ndim != 1:
+                raise ValueError(f"{self.hdf5_path}:{dataset_path} is {self._dataset.ndim}-D; a column must be named")
+        else:
+            if self._dataset.ndim != 2:
+                raise ValueError(f"{self.hdf5_path}:{dataset_path} is {self._dataset.ndim}-D; column applies to a 2-D dataset")
+            if not 0 <= column < self._dataset.shape[1]:
+                raise ValueError(
+                    f"{self.hdf5_path}:{dataset_path} has {self._dataset.shape[1]} columns; no column {column}"
+                )
+
+    @property
+    def length(self) -> int:
+        return int(self._dataset.shape[0])
+
+    @property
+    def dtype(self) -> np.dtype:
+        return self._dataset.dtype
+
+    def read_range(self, start: int, end: int) -> np.ndarray:
+        if self.column is None:
+            return np.asarray(self._dataset[start:end])
+        return np.asarray(self._dataset[start:end, self.column])
+
+    def iter_blocks(self, block_size: int) -> Iterator[np.ndarray]:
+        length = self.length
+        for offset in range(0, length, block_size):
+            yield self.read_range(offset, min(offset + block_size, length))
+
+    def identity(self) -> SourceIdentity:
+        resolved = self.hdf5_path.resolve()
+        stat = resolved.stat()
+        return SourceIdentity(path=resolved, mtime_ns=stat.st_mtime_ns, size=stat.st_size)
+
+    def close(self) -> None:
+        self._file.close()
+
+    def __enter__(self) -> "HdfArraySource":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()