qplotter 1.6.0b3__py3-none-any.whl

qplot/tools/__init__.py

@@ -0,0 +1,13 @@
+from .general import (
+    data2matrix,
+    unpack_param,
+)
+from .worker import (
+    loader,
+)
+
+__all__ = [
+    "data2matrix",
+    "unpack_param",
+    "loader",
+    ]

qplot/tools/finite_means.py

@@ -0,0 +1,114 @@
+"""Bounded finite bin means with a rare exact fallback for risky sums."""
+
+from fractions import Fraction
+
+import numpy as np
+
+
+class FiniteBinMeans:
+    """Keep only one count/sum per bin, never the original sample history."""
+
+    def __init__(self, shape, check_cancelled=lambda: None):
+        self.sums = np.zeros(shape, dtype=float)
+        self.counts = np.zeros(shape, dtype=np.int64)
+        self.exact = {}
+        self.check_cancelled = check_cancelled
+        self._largest = 0.
+        self._samples = 0
+        self._positive = np.zeros(shape, dtype=bool)
+        self._negative = np.zeros(shape, dtype=bool)
+        self._integer = np.zeros(shape, dtype=bool)
+        self._absolute_sums = np.zeros(shape, dtype=float)
+
+    def add(self, indices, values):
+        self.check_cancelled()
+        original = np.asarray(values).ravel()
+        values = original.astype(float)
+        if not values.size:
+            return
+        targets = np.ravel_multi_index(indices, self.sums.shape)
+        np.logical_or.at(self._positive.ravel(), targets, values > 0)
+        np.logical_or.at(self._negative.ravel(), targets, values < 0)
+        mixed = self._positive & self._negative
+        # Original object cells may retain clipped decimal bounds or mixed
+        # integer records. Large integer cells also need exact replay even
+        # when all samples have the same sign: conversion or summation can
+        # round before their mean is formed.
+        sensitive = np.zeros(self.sums.shape, dtype=bool)
+        if original.dtype.kind == "O":
+            sensitive.ravel()[targets] = True
+        elif original.dtype.kind in "iu":
+            self._integer.ravel()[targets] = True
+        # Several individually exact integers can have an inexact total.
+        # Retain the accumulated absolute bound and integer presence across
+        # chunks, including a later floating record in the same bin.
+        with np.errstate(over="ignore", invalid="ignore"):
+            np.add.at(self._absolute_sums.ravel(), targets, np.abs(values))
+        sensitive |= self._integer & (self._absolute_sums >= 2**53)
+        self._largest = max(self._largest, float(np.max(np.abs(values))))
+        self._samples += values.size
+        # Leave headroom for rounded additions at the finite sum boundary.
+        # This conservative global bound makes the normal path vectorized.
+        # It changes only whether we retain sums for recovery, never scaling
+        # the values in other bins (which could erase small measurements).
+        safe_sample = (np.finfo(float).max / 2) / self._samples
+        risk = (bool(self.exact) or self._largest > safe_sample
+                or np.any(mixed) or np.any(sensitive))
+        previous = self.sums.copy() if risk else None
+        with np.errstate(over="ignore", invalid="ignore"):
+            np.add.at(self.sums.ravel(), targets, values)
+        np.add.at(self.counts.ravel(), targets, 1)
+        if risk:
+            assert previous is not None
+            # Promote before overflow: waiting for a later chunk to overflow
+            # would already have rounded away small cancellation residuals.
+            largest = np.abs(previous)
+            np.maximum.at(largest.ravel(), targets, np.abs(values))
+            for index, target in enumerate(np.flatnonzero(
+                    (largest > safe_sample) | mixed | sensitive)):
+                if index % 1024 == 0:
+                    self.check_cancelled()
+                self.exact.setdefault(int(target), Fraction(float(previous.ravel()[target])))
+            if self.exact:
+                self._add_exact(targets, original)
+                self.sums.ravel()[list(self.exact)] = 0.
+        self.check_cancelled()
+
+    def _add_exact(self, targets, values):
+        selected = np.flatnonzero(np.isin(targets, list(self.exact)))
+        for index, position in enumerate(selected):
+            if index % 1024 == 0:
+                self.check_cancelled()
+            value = values[position]
+            if isinstance(value, np.generic):
+                value = value.item()
+            self.exact[int(targets[position])] += Fraction(value)
+
+    def begin_exact_replay(self):
+        """Discard rounded history for promoted bins, retaining their counts."""
+        self.check_cancelled()
+        for index, target in enumerate(self.exact):
+            if index % 1024 == 0:
+                self.check_cancelled()
+            self.exact[target] = Fraction()
+        return bool(self.exact)
+
+    def replay(self, indices, values):
+        """Revisit original samples once; only promoted totals are changed."""
+        self.check_cancelled()
+        targets = np.ravel_multi_index(indices, self.sums.shape)
+        # Retain original integer/object values instead of converting these
+        # selected samples through the ordinary display-sum float dtype.
+        self._add_exact(targets, np.asarray(values).ravel())
+        self.check_cancelled()
+
+    def means(self):
+        self.check_cancelled()
+        result = np.full(self.sums.shape, np.nan)
+        np.divide(self.sums, self.counts, out=result, where=self.counts > 0)
+        for index, (target, total) in enumerate(self.exact.items()):
+            if index % 1024 == 0:
+                self.check_cancelled()
+            result.ravel()[target] = float(total / int(self.counts.ravel()[target]))
+        self.check_cancelled()
+        return result

qplot/tools/general.py

@@ -0,0 +1,134 @@
+from decimal import Decimal, localcontext
+from fractions import Fraction
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from numpy.typing import ArrayLike
+from qcodes import dataset
+
+from qplot.tools.sample_statistics import finite_mean
+
+
+def data2matrix(indep1 : ArrayLike,
+                indep2 : ArrayLike,
+                depvar : ArrayLike,
+                *,
+                check_cancelled=lambda: None,
+                ):
+    """
+    Converts 3 numpy.ndarry into a datagrid via pandas.DataFrame.
+    This is used for producing a data grid to be passed to a heatmap, also 
+    handles numpy.Nan values in depvar and duplicates
+
+    Parameters
+    ----------
+    indep1 : np.array
+        Array to be placed in the pandas.DataFrame index column.
+    indep2 : np.array
+        Array to be placed in the pandas.DataFrame header row.
+    depvar : np.array
+        Array to take up the .
+
+    Returns
+    -------
+    matrix : pandas.DataFrame
+        The data frame containing all 3 inputted arrays as a dataframe.
+
+    """
+    values = np.asarray(depvar)
+    if values.dtype.kind in "iuO":
+        # A floating pivot mean rounds even a cell containing a single large
+        # integer. Retain those cells, including holes; repeated coordinates
+        # still mean-average their acquired samples, using exact arithmetic.
+        rows, row_indices = np.unique(indep1, return_inverse=True)
+        columns, column_indices = np.unique(indep2, return_inverse=True)
+        grid = np.full((len(rows), len(columns)), np.nan, dtype=object)
+        cells: dict[tuple[int, int], list[Any]] = {}
+        for index, (row, column, value) in enumerate(
+            zip(row_indices, column_indices, values, strict=True)
+        ):
+            if index % 1024 == 0:
+                check_cancelled()
+            if isinstance(value, np.generic):
+                value = value.item()
+            if not np.isfinite(float(value)):
+                continue
+            cells.setdefault((row, column), []).append(value)
+        for index, (position, samples) in enumerate(cells.items()):
+            if index % 1024 == 0:
+                check_cancelled()
+            if len(samples) == 1:
+                grid[position] = samples[0]
+            else:
+                mean = sum((Fraction(value) for value in samples), Fraction()) / len(samples)
+                if mean.denominator == 1:
+                    grid[position] = int(mean)
+                else:
+                    # Decimal keeps the offset and fractional detail while
+                    # remaining a numeric CSV cell (Fraction writes "a/b").
+                    with localcontext() as context:
+                        context.prec = max(34, len(str(abs(mean.numerator))) + 17)
+                        grid[position] = Decimal(mean.numerator) / Decimal(mean.denominator)
+        check_cancelled()
+        return pd.DataFrame(grid, index=rows, columns=columns)
+
+    # Widen narrow floats before pandas accumulates repeated measured cells.
+    # The source array remains untouched for raw export and later operations.
+    if values.dtype.kind == "f":
+        values = values.astype(np.result_type(values.dtype, np.float64), copy=False)
+
+    # convert to 3 column dataframe
+    df = pd.DataFrame({
+        'indep1': indep1,
+        'indep2': indep2,
+        'depvar': values
+    })
+    # convert dataframe to grid
+    if values.dtype.kind == "f" and (
+            np.any(np.abs(values) > np.finfo(values.dtype).max / max(1, values.size))
+            or (np.any(values < 0) and np.any(values > 0))):
+        # The ordinary vectorized mean is fast, but an intermediate group sum
+        # can overflow even when the final mean is finite. Retain failed groups
+        # before pivot_table would drop their rows and columns, then repair only
+        # those groups using a scaled mean of their original finite samples.
+        check_cancelled()
+        grouped = df.groupby(['indep1', 'indep2'])['depvar']
+        means = grouped.mean()
+        check_cancelled()
+        mixed = (grouped.min().to_numpy() < 0) & (grouped.max().to_numpy() > 0)
+        for group_position in np.flatnonzero(~np.isfinite(means.to_numpy()) | mixed):
+            check_cancelled()
+            samples = grouped.get_group(means.index[group_position]).to_numpy()
+            if np.any(np.isinf(samples)):
+                continue
+            samples = samples[np.isfinite(samples)]
+            if not samples.size:
+                continue
+            means.iloc[group_position] = finite_mean(samples, check_cancelled=check_cancelled)
+        check_cancelled()
+        return means.unstack().dropna(how='all', axis=0).dropna(how='all', axis=1)
+    matrix = df.pivot_table(index='indep1', columns='indep2', values='depvar', fill_value=np.nan)
+    return matrix
+
+
+def unpack_param(dataset : dataset.data_set.DataSet, paramName : str):
+    """
+    Gets specified parameter from list all parameters in a dataset.
+
+    Parameters
+    ----------
+    dataset : qcodes.dataset.data_set.DataSet
+        Dataset to ook through.
+    paramName : str
+        Name of parameter.
+
+    Returns
+    -------
+    ParamSpec : qcodes.dataset.descriptions.param_spec.ParamSpec
+        The desired parameter data.
+
+    """
+    for ParamSpec in dataset.get_parameters():
+        if ParamSpec.name == paramName:
+            return ParamSpec

qplot/tools/heatmap_geometry.py

@@ -0,0 +1,381 @@
+"""Coordinate geometry for rectilinear heatmaps.
+
+This module deliberately has no Qt dependencies.  It defines the coordinate
+contract shared by heatmap rendering and interactions: axis values are pixel
+centres, while the derived edges are pixel boundaries.
+"""
+
+import math
+import operator
+from bisect import bisect_left, bisect_right
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+_DEFAULT_SINGLETON_SPAN = 1.0
+_DEFAULT_UNIFORM_REL_TOL = 1e-9
+
+
+def bounded_grid_shape(x_count, y_count, *, max_cells, max_side):
+    max_cells = max(1, int(max_cells))
+    x_bins = max(1, min(int(x_count), max_side))
+    y_bins = max(1, min(int(y_count), max_side))
+    if x_bins * y_bins <= max_cells:
+        return x_bins, y_bins
+    scale = math.sqrt(max_cells / (x_bins * y_bins))
+    x_bins = max(1, int(x_bins * scale))
+    y_bins = max(1, int(y_bins * scale))
+    while x_bins * y_bins > max_cells:
+        if x_bins >= y_bins and x_bins > 1:
+            x_bins -= 1
+        elif y_bins > 1:
+            y_bins -= 1
+        else:
+            break
+    return x_bins, y_bins
+
+
+def spatial_axis_bins(lower, upper, source_count, bin_count):
+    if not np.isfinite(lower) or not np.isfinite(upper):
+        return np.array([], dtype=float), 0.0, 1.0
+    if source_count <= 1 or bin_count <= 1 or lower == upper:
+        return np.array([lower], dtype=float), lower, 1.0
+    source_step = (upper - lower) / (source_count - 1)
+    lower_edge = lower - source_step / 2
+    upper_edge = upper + source_step / 2
+    bin_width = (upper_edge - lower_edge) / bin_count
+    centres = lower_edge + (np.arange(bin_count, dtype=float) + 0.5) * bin_width
+    return centres, lower_edge, 1.0 / bin_width
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class AxisGeometry:
+    """Immutable geometry for one strictly increasing heatmap axis.
+
+    Descending axes are rejected rather than silently reordered because axis
+    indices must remain aligned with the corresponding dimension of the data
+    grid.  A caller that receives descending data must reverse both together.
+
+    Parameters
+    ----------
+    centres:
+        Finite, strictly increasing cell-centre coordinates.
+    singleton_span:
+        Width assigned to an axis containing one centre.  Callers can supply a
+        known neighbouring step; otherwise one coordinate unit is used.
+    uniform_rel_tol, uniform_abs_tol:
+        Tolerances used only when classifying an axis as uniform.
+    """
+
+    centres: tuple[float, ...]
+    edges: tuple[float, ...]
+    is_uniform: bool
+
+    def __init__(
+            self,
+            centres: Iterable[float],
+            *,
+            singleton_span: float = _DEFAULT_SINGLETON_SPAN,
+            uniform_rel_tol: float = _DEFAULT_UNIFORM_REL_TOL,
+            uniform_abs_tol: float = 0.0,
+            ) -> None:
+        values = tuple(float(value) for value in centres)
+        span = float(singleton_span)
+        rel_tol = float(uniform_rel_tol)
+        abs_tol = float(uniform_abs_tol)
+
+        if not values:
+            raise ValueError("A heatmap axis requires at least one centre.")
+        if not all(math.isfinite(value) for value in values):
+            raise ValueError("Heatmap axis centres must all be finite.")
+        if not math.isfinite(span) or span <= 0.0:
+            raise ValueError("singleton_span must be positive and finite.")
+        if not math.isfinite(rel_tol) or rel_tol < 0.0:
+            raise ValueError("uniform_rel_tol must be non-negative and finite.")
+        if not math.isfinite(abs_tol) or abs_tol < 0.0:
+            raise ValueError("uniform_abs_tol must be non-negative and finite.")
+
+        deltas = tuple(
+            right - left
+            for left, right in zip(values[:-1], values[1:], strict=True)
+        )
+        if deltas and all(delta < 0.0 for delta in deltas):
+            raise ValueError(
+                "descending heatmap axes are not supported; reverse both the "
+                "axis centres and the corresponding data dimension."
+            )
+        if any(delta <= 0.0 for delta in deltas):
+            raise ValueError("Heatmap axis centres must be strictly increasing.")
+
+        derived_edges: tuple[float, ...]
+        if len(values) == 1:
+            half_span = span / 2.0
+            derived_edges = (values[0] - half_span, values[0] + half_span)
+        else:
+            interior_edges = tuple(
+                left / 2.0 + right / 2.0
+                for left, right in zip(values[:-1], values[1:], strict=True)
+            )
+            derived_edges = (
+                values[0] - (interior_edges[0] - values[0]),
+                *interior_edges,
+                values[-1] + (values[-1] - interior_edges[-1]),
+            )
+
+        if not all(math.isfinite(edge) for edge in derived_edges):
+            raise ValueError("Derived heatmap axis edges must all be finite.")
+        if any(
+                right <= left
+                for left, right in zip(
+                    derived_edges[:-1],
+                    derived_edges[1:],
+                    strict=True,
+                    )
+                ):
+            raise ValueError(
+                "Heatmap cell edges collapse at floating-point precision."
+                )
+
+        uniform = len(deltas) <= 1 or all(
+            math.isclose(
+                delta,
+                deltas[0],
+                rel_tol=rel_tol,
+                abs_tol=abs_tol,
+            )
+            for delta in deltas[1:]
+        )
+
+        object.__setattr__(self, "centres", values)
+        object.__setattr__(self, "edges", derived_edges)
+        object.__setattr__(self, "is_uniform", uniform)
+
+    @property
+    def count(self) -> int:
+        """Number of cells along this axis."""
+
+        return len(self.centres)
+
+    @property
+    def bounds(self) -> tuple[float, float]:
+        """Inclusive outer coordinate bounds of the axis."""
+
+        return self.edges[0], self.edges[-1]
+
+    @property
+    def span(self) -> float:
+        """Positive distance between the outer axis edges."""
+
+        return self.edges[-1] - self.edges[0]
+
+    def centre(self, index: int) -> float:
+        """Return the recorded centre coordinate of one cell."""
+
+        return self.centres[self._checked_index(index)]
+
+    def cell_bounds(self, index: int) -> tuple[float, float]:
+        """Return the lower and upper boundary of one cell."""
+
+        checked_index = self._checked_index(index)
+        return self.edges[checked_index], self.edges[checked_index + 1]
+
+    def index_at(self, value: float, *, clamp: bool = False) -> int | None:
+        """Return the cell containing ``value``.
+
+        An interior boundary belongs to the cell on its right.  Both outer
+        boundaries are included.  Out-of-bounds coordinates return ``None``
+        unless ``clamp`` is true, in which case the nearest outer cell is used.
+        Non-finite coordinates always return ``None``.
+        """
+
+        coordinate = float(value)
+        if not math.isfinite(coordinate):
+            return None
+
+        lower, upper = self.bounds
+        if coordinate < lower:
+            return 0 if clamp else None
+        if coordinate > upper:
+            return self.count - 1 if clamp else None
+        if coordinate == upper:
+            return self.count - 1
+
+        return bisect_right(self.edges, coordinate) - 1
+
+    def snap_interval(self, low: float, high: float) -> tuple[float, float]:
+        """Expand an interval to the cell edges that contain it."""
+
+        start, stop = self._cell_interval(low, high)
+        return self.edges[start], self.edges[stop]
+
+    def slice_for_interval(self, low: float, high: float) -> slice:
+        """Return the cells covered by an interval as a NumPy-style slice."""
+
+        start, stop = self._cell_interval(low, high)
+        return slice(start, stop)
+
+    def _cell_interval(self, low: float, high: float) -> tuple[int, int]:
+        low_value = float(low)
+        high_value = float(high)
+        if not math.isfinite(low_value) or not math.isfinite(high_value):
+            raise ValueError("heatmap selection coordinates must be finite.")
+
+        low_value, high_value = sorted((low_value, high_value))
+        lower_bound, upper_bound = self.bounds
+        low_value = min(max(low_value, lower_bound), upper_bound)
+        high_value = min(max(high_value, lower_bound), upper_bound)
+
+        start = bisect_right(self.edges, low_value) - 1
+        start = min(max(start, 0), self.count - 1)
+        stop = bisect_left(self.edges, high_value)
+        stop = min(max(stop, start + 1), self.count)
+        return start, stop
+
+    def _checked_index(self, index: int) -> int:
+        try:
+            checked_index = operator.index(index)
+        except TypeError as error:
+            raise TypeError("axis cell index must be an integer") from error
+        if not 0 <= checked_index < self.count:
+            raise IndexError(
+                f"axis cell index {checked_index} is outside "
+                f"0..{self.count - 1}"
+            )
+        return checked_index
+
+
+@dataclass(frozen=True, slots=True)
+class HeatmapGeometry:
+    """Immutable two-dimensional rectilinear heatmap geometry."""
+
+    x: AxisGeometry
+    y: AxisGeometry
+
+    @classmethod
+    def from_centres(
+            cls,
+            x_centres: Iterable[float],
+            y_centres: Iterable[float],
+            *,
+            x_singleton_span: float = _DEFAULT_SINGLETON_SPAN,
+            y_singleton_span: float = _DEFAULT_SINGLETON_SPAN,
+            uniform_rel_tol: float = _DEFAULT_UNIFORM_REL_TOL,
+            uniform_abs_tol: float = 0.0,
+            ) -> "HeatmapGeometry":
+        """Build heatmap geometry from X and Y cell-centre coordinates."""
+
+        return cls(
+            x=AxisGeometry(
+                x_centres,
+                singleton_span=x_singleton_span,
+                uniform_rel_tol=uniform_rel_tol,
+                uniform_abs_tol=uniform_abs_tol,
+            ),
+            y=AxisGeometry(
+                y_centres,
+                singleton_span=y_singleton_span,
+                uniform_rel_tol=uniform_rel_tol,
+                uniform_abs_tol=uniform_abs_tol,
+            ),
+        )
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        """Expected data-grid shape in NumPy row-major order: ``(Y, X)``."""
+
+        return self.y.count, self.x.count
+
+    @property
+    def bounds(self) -> tuple[float, float, float, float]:
+        """Return ``(left, bottom, right, top)`` outer cell boundaries."""
+
+        return self.x.edges[0], self.y.edges[0], self.x.edges[-1], self.y.edges[-1]
+
+    @property
+    def rect(self) -> tuple[float, float, float, float]:
+        """Return a Qt-free ``(left, bottom, width, height)`` rectangle."""
+
+        return self.x.edges[0], self.y.edges[0], self.x.span, self.y.span
+
+    @property
+    def is_uniform(self) -> bool:
+        """Whether both axes use uniform cell spacing."""
+
+        return self.x.is_uniform and self.y.is_uniform
+
+    def index_at(
+            self,
+            x_value: float,
+            y_value: float,
+            *,
+            clamp: bool = False,
+            ) -> tuple[int, int] | None:
+        """Return the ``(X, Y)`` cell containing a plot coordinate."""
+
+        x_index = self.x.index_at(x_value, clamp=clamp)
+        y_index = self.y.index_at(y_value, clamp=clamp)
+        if x_index is None or y_index is None:
+            return None
+        return x_index, y_index
+
+    def cell_bounds(
+            self,
+            x_index: int,
+            y_index: int,
+            ) -> tuple[float, float, float, float]:
+        """Return ``(left, bottom, right, top)`` for one heatmap cell."""
+
+        left, right = self.x.cell_bounds(x_index)
+        bottom, top = self.y.cell_bounds(y_index)
+        return left, bottom, right, top
+
+    def cell_rect(
+            self,
+            x_index: int,
+            y_index: int,
+            ) -> tuple[float, float, float, float]:
+        """Return ``(left, bottom, width, height)`` for one heatmap cell."""
+
+        left, bottom, right, top = self.cell_bounds(x_index, y_index)
+        return left, bottom, right - left, top - bottom
+
+
+def canonicalize_heatmap_data(
+        x_centres: npt.ArrayLike,
+        y_centres: npt.ArrayLike,
+        data_grid: npt.ArrayLike,
+        ) -> tuple[
+            npt.NDArray[np.float64],
+            npt.NDArray[np.float64],
+            npt.NDArray[Any],
+            ]:
+    """Return increasing axes while preserving their grid-value mapping."""
+
+    x_values = np.asarray(x_centres, dtype=float)
+    y_values = np.asarray(y_centres, dtype=float)
+    grid = np.asarray(data_grid)
+
+    if x_values.ndim != 1 or y_values.ndim != 1:
+        raise ValueError("Heatmap axes must be one-dimensional.")
+    expected_shape = (y_values.size, x_values.size)
+    if grid.ndim != 2 or grid.shape != expected_shape:
+        raise ValueError(
+            f"Heatmap data shape {grid.shape} does not match "
+            f"axis shape {expected_shape}."
+            )
+
+    if x_values.size > 1 and not np.all(np.diff(x_values) > 0.0):
+        order = np.argsort(x_values)
+        x_values = x_values[order]
+        grid = grid[:, order]
+    if y_values.size > 1 and not np.all(np.diff(y_values) > 0.0):
+        order = np.argsort(y_values)
+        y_values = y_values[order]
+        grid = grid[order, :]
+
+    AxisGeometry(x_values)
+    AxisGeometry(y_values)
+    return x_values, y_values, grid