matterviz 0.4.0 → 0.4.2

package/dist/plot/core/marginals.js

@@ -0,0 +1,436 @@
+// Shared marginal-distribution model for all 2D plots. Pure and unit-tested: types,
+// shorthand resolution, pad reservation, strip geometry, and the curve math (histogram /
+// kde / cdf / rug). The PlotMarginals.svelte renderer consumes these; each plot only adapts
+// its data to MarginalSeriesInput and folds reserve_marginal_pad into its `pad`.
+import { sorted_range } from './interactions';
+import { get_scale_type_name } from './types';
+import { gaussian_kde } from '../box/kde';
+import { bin } from 'd3-array';
+export const MARGINAL_SIDES = [`top`, `bottom`, `left`, `right`];
+// Top/bottom strips run along the x (horizontal) positional axis; left/right run along y
+const is_x_side = (side) => side === `top` || side === `bottom`;
+// Build a MarginalAxis from a host plot's scale fn + current range, reading scale_type/format/label
+// off the plot's AxisConfig (DRYs the per-axis object every host plot passes to PlotMarginals; the
+// renderer defaults a missing scale_type to `linear`). `tick_label` maps a position to a label.
+export const marginal_axis = (scale, range, axis, tick_label) => ({
+    scale,
+    range,
+    scale_type: axis.scale_type,
+    format: axis.format,
+    label: axis.label,
+    tick_label,
+});
+// Pixel tolerance for rug-tick hit-testing (a tick farther than this from the pointer is a miss)
+export const MARGINAL_HIT_TOLERANCE_PX = 10;
+// Pure hit-test: given a strip's render context and a pointer position in wrapper px, return the
+// nearest datum as a MarginalHover (or null for a miss). ctx.curves is kind-homogeneous, so we
+// branch once on the first curve's kind, matching only along the shared positional axis. Non-finite
+// data is skipped (consistent with the renderer) so custom reduce/data curves can't yield ghost hits.
+export function marginal_hit(ctx, px, py) {
+    const { side, curves, positional_scale, value_scale, baseline, config, scale_type } = ctx;
+    const is_x = is_x_side(side);
+    const pointer_pos = is_x ? px : py; // along the shared positional axis
+    const pointer_cross = is_x ? py : px; // across the strip thickness (the value direction)
+    const kind = curves[0]?.curve.kind;
+    if (!kind)
+        return null;
+    const contains_cross = (value_px) => Number.isFinite(value_px) &&
+        pointer_cross >= Math.min(baseline, value_px) &&
+        pointer_cross <= Math.max(baseline, value_px);
+    const hover = (curve, extra) => ({
+        side,
+        x: px,
+        y: py,
+        color: config.color ?? curve.color,
+        label: curve.label,
+        kind,
+        config,
+        scale_type,
+        format: ctx.format,
+        pos_label: ctx.tick_label?.(extra.pos),
+        axis_title: ctx.axis_title,
+        ...extra,
+    });
+    if (kind === `bars`) {
+        // Among bins whose rendered rect contains the pointer, pick the largest-value (tallest) bar.
+        // Baseline-anchored bars nest, so the tallest containing bar wins render-order independently.
+        let best = null;
+        for (const series_curve of curves) {
+            if (series_curve.curve.kind !== `bars`)
+                continue;
+            for (const bar of series_curve.curve.bins) {
+                if (!Number.isFinite(bar.value) || bar.value <= 0)
+                    continue; // finite positive only (matches renderer)
+                const edge_a = positional_scale(bar.pos0);
+                const edge_b = positional_scale(bar.pos1);
+                if (!Number.isFinite(edge_a) || !Number.isFinite(edge_b))
+                    continue;
+                if (pointer_pos < Math.min(edge_a, edge_b) || pointer_pos > Math.max(edge_a, edge_b)) {
+                    continue;
+                }
+                if (!contains_cross(value_scale(bar.value)))
+                    continue;
+                if (!best || bar.value > best.bar.value)
+                    best = { curve: series_curve, bar };
+            }
+        }
+        if (!best)
+            return null;
+        const { bar } = best;
+        return hover(best.curve, {
+            pos: (bar.pos0 + bar.pos1) / 2,
+            pos0: bar.pos0,
+            pos1: bar.pos1,
+            value: bar.value,
+        });
+    }
+    if (kind === `line`) {
+        let chosen = null;
+        let best_extent = -1;
+        for (const series_curve of curves) {
+            if (series_curve.curve.kind !== `line`)
+                continue;
+            const pts = [];
+            let min_pos = Infinity;
+            let max_pos = -Infinity;
+            for (const pt of series_curve.curve.points) {
+                const px_pos = positional_scale(pt.pos);
+                const px_val = value_scale(pt.value);
+                if (!Number.isFinite(px_pos) || !Number.isFinite(px_val))
+                    continue;
+                pts.push({ curve: series_curve, pos: pt.pos, value: pt.value, px_pos, px_val });
+                min_pos = Math.min(min_pos, px_pos);
+                max_pos = Math.max(max_pos, px_pos);
+            }
+            if (pts.length < 2)
+                continue; // renderer skips line/area paths without two finite points
+            if (pointer_pos < min_pos || pointer_pos > max_pos)
+                continue;
+            let near = null;
+            let near_dist = Infinity;
+            for (const pt of pts) {
+                const pos_dist = Math.abs(pt.px_pos - pointer_pos);
+                if (pos_dist < near_dist) {
+                    near_dist = pos_dist;
+                    near = pt;
+                }
+            }
+            if (!near || !contains_cross(near.px_val))
+                continue;
+            const extent = Math.abs(near.px_val - baseline);
+            if (extent > best_extent)
+                [best_extent, chosen] = [extent, near];
+        }
+        return chosen ? hover(chosen.curve, { pos: chosen.pos, value: chosen.value }) : null;
+    }
+    // rug: nearest tick along the positional axis, within a pixel tolerance (no value/cross axis)
+    let best = null;
+    for (const series_curve of curves) {
+        if (series_curve.curve.kind !== `rug`)
+            continue;
+        for (const pos of series_curve.curve.positions) {
+            const px_pos = positional_scale(pos);
+            if (!Number.isFinite(px_pos))
+                continue;
+            const dist = Math.abs(px_pos - pointer_pos);
+            if (dist < (best?.dist ?? Infinity))
+                best = { curve: series_curve, pos, dist };
+        }
+    }
+    if (!best || best.dist > MARGINAL_HIT_TOLERANCE_PX)
+        return null;
+    return hover(best.curve, { pos: best.pos });
+}
+// Co-located defaults (mirrors REF_LINE_STYLE_DEFAULTS in types.ts). Deliberately NOT part of
+// settings.ts DEFAULTS to avoid pulling marginals into the settings-UI JSON schema.
+export const MARGINAL_DEFAULTS = {
+    type: `histogram`,
+    size: 64,
+    gap: 6,
+    placement: `auto`,
+    per_series: true,
+    bins: 60,
+    bandwidth: `silverman`,
+    stroke_width: 1.5,
+    opacity: 1,
+    value_axis: true,
+};
+// Normalize a single side's shorthand to a MarginalConfig, `false` (explicit disable), or
+// undefined (not specified -> fall back to default)
+const to_config = (input) => {
+    if (input === undefined)
+        return undefined;
+    if (input === false)
+        return false;
+    if (input === true)
+        return {};
+    if (typeof input === `string`)
+        return { type: input };
+    return input;
+};
+// Merge a user side-input over the plot's default side-input into a resolved config (or null)
+const resolve_side = (user_input, default_input) => {
+    const user = to_config(user_input);
+    if (user === false)
+        return null; // explicit disable wins over any default
+    const base = to_config(default_input);
+    const base_cfg = base === false ? undefined : base;
+    if (user === undefined && base_cfg === undefined)
+        return null; // side inactive
+    return { ...MARGINAL_DEFAULTS, ...base_cfg, ...user };
+};
+// Expand the `marginals` prop into a per-side resolved config, merging with the plot's
+// `default_sides` (the sensible defaults a given plot enables when `marginals` is `true`).
+// - `true`: enable exactly the plot's default sides
+// - a type string: that type on the plot's default sides (or top+right if none), inheriting
+//   each default side's config (e.g. shared bins)
+// - a per-side map: enable ONLY the sides the user lists (default sides do not auto-activate),
+//   merging the plot's per-side default config under the user's
+export function normalize_marginals(prop, default_sides = {}) {
+    const result = { top: null, bottom: null, left: null, right: null };
+    if (prop == null || prop === false)
+        return result;
+    if (prop === true) {
+        for (const side of MARGINAL_SIDES)
+            result[side] = resolve_side(undefined, default_sides[side]);
+        return result;
+    }
+    if (typeof prop === `string`) {
+        const sides = Object.keys(default_sides).length > 0 ? default_sides : { top: true, right: true };
+        for (const side of MARGINAL_SIDES) {
+            if (!(side in sides))
+                continue;
+            result[side] = resolve_side(prop, default_sides[side]);
+        }
+        return result;
+    }
+    // Explicit per-side map: only sides the user names become active
+    for (const side of MARGINAL_SIDES) {
+        if (prop[side] === undefined)
+            continue;
+        result[side] = resolve_side(prop[side], default_sides[side]);
+    }
+    return result;
+}
+// Padding (px) each plot must add to its `pad` to make room for active marginal strips
+export function reserve_marginal_pad(resolved) {
+    const reserve = (cfg) => (cfg ? cfg.size + cfg.gap : 0);
+    return {
+        t: reserve(resolved.top),
+        b: reserve(resolved.bottom),
+        l: reserve(resolved.left),
+        r: reserve(resolved.right),
+    };
+}
+// Sum two padding objects (used to fold marginal reservation into the decoration pad)
+export const add_sides = (a, b) => ({
+    t: a.t + b.t,
+    b: a.b + b.b,
+    l: a.l + b.l,
+    r: a.r + b.r,
+});
+// Default axis a side binds to when `config.axis` is unset
+export const default_axis_for_side = (side) => is_x_side(side) ? `x1` : `y1`;
+// Which sides carry an axis (drives `auto` placement). Bottom/left hold the primary x/y axes and
+// are always present; top/right only when the plot shows a secondary axis there.
+export const marginal_axis_presence = (top, right) => ({ top, bottom: true, left: true, right });
+// Whether the strip should hug the plot edge (`flush`) vs sit beyond the ticks (`outer`)
+const is_flush = (placement, has_axis) => placement === `flush` || (placement === `auto` && !has_axis);
+// Pixel rect of a marginal strip. The cross dimension spans the plot area (so it aligns with
+// the shared positional scale); the thickness is `config.size`, positioned per placement.
+export function marginal_strip_rect(side, pad, width, height, config, has_axis) {
+    const { size, gap } = config;
+    const flush = is_flush(config.placement, has_axis);
+    const is_x = is_x_side(side);
+    const grows_negative = side === `top` || side === `left`;
+    // thickness-axis position of the strip's near edge: flush sits a gap from the plot, outer at
+    // the container edge (top/left strips go before the plot, bottom/right strips after it)
+    const plot_near = is_x ? pad.t : pad.l;
+    const plot_far = is_x ? height - pad.b : width - pad.r;
+    const container_far = is_x ? height : width;
+    const thick = flush
+        ? grows_negative
+            ? plot_near - gap - size
+            : plot_far + gap
+        : grows_negative
+            ? 0
+            : container_far - size;
+    // cross axis spans the plot area so the strip aligns with the shared positional scale
+    const cross_min = is_x ? pad.l : pad.t;
+    const cross = Math.max(0, (is_x ? width - pad.r : height - pad.b) - cross_min);
+    return is_x
+        ? { x: cross_min, y: thick, width: cross, height: size }
+        : { x: thick, y: cross_min, width: size, height: cross };
+}
+// Linear value scale across a strip's thickness, growing away from the plot. `domain` is the
+// marginal value range (typically [0, max]); `baseline` is the plot-facing value=domain[0] edge.
+export function marginal_value_scale(side, rect, domain) {
+    const [lo, hi] = domain;
+    const span = hi - lo || 1;
+    const is_x = is_x_side(side);
+    const thickness = is_x ? rect.height : rect.width;
+    const near = is_x ? rect.y : rect.x; // strip edge at the smaller pixel coordinate
+    // top/left strips grow toward smaller pixel coords; their baseline (value=lo, plot-facing) sits
+    // at the far edge, and value increases in the negative pixel direction
+    const grows_negative = side === `top` || side === `left`;
+    const baseline = grows_negative ? near + thickness : near;
+    const sign = grows_negative ? -1 : 1;
+    return { scale: (val) => baseline + sign * ((val - lo) / span) * thickness, baseline };
+}
+// Drop non-finite positions (and matching weights), restrict to the current positional range
+// so every marginal type tracks zoom/pan consistently (histogram already clips via bin domain),
+// and drop non-positive positions on a log axis.
+const clean_pairs = (positions, weights, positional_range, scale_type) => {
+    const [lo, hi] = positional_range; // ascending (canonicalized by compute_marginal_curve)
+    const require_positive = get_scale_type_name(scale_type) === `log`;
+    const out_pos = [];
+    const out_wts = weights ? [] : undefined;
+    for (let idx = 0; idx < positions.length; idx++) {
+        const pos = positions[idx];
+        if (!Number.isFinite(pos) || pos < lo || pos > hi)
+            continue;
+        if (require_positive && pos <= 0)
+            continue;
+        if (weights && out_wts) {
+            const weight = weights[idx];
+            // skip non-finite and negative weights: a negative makes a weighted CDF non-monotone and
+            // skews histogram normalization. zero is kept (it contributes nothing and the renderer
+            // already drops zero-value bars, so skipping it would only needlessly drop rug/kde positions)
+            if (!Number.isFinite(weight) || weight < 0)
+                continue;
+            out_wts.push(weight);
+        }
+        out_pos.push(pos);
+    }
+    return { positions: out_pos, weights: out_wts };
+};
+function compute_histogram(positions, weights, config, positional_range) {
+    const indices = positions.map((_, idx) => idx);
+    const binner = bin()
+        .domain(positional_range)
+        .thresholds(config.bins)
+        .value((idx) => positions[idx]);
+    const binned = binner(indices);
+    let max = 0;
+    const bins = binned.map((items) => {
+        const value = weights ? items.reduce((sum, idx) => sum + weights[idx], 0) : items.length;
+        if (value > max)
+            max = value;
+        return { pos0: items.x0 ?? 0, pos1: items.x1 ?? 0, value };
+    });
+    // count: raw; probability: value/total; density: value/(total*bin_width)
+    if (config.normalize && config.normalize !== `count`) {
+        const grand = bins.reduce((sum, item) => sum + item.value, 0) || 1;
+        max = 0;
+        for (const item of bins) {
+            const width = item.pos1 - item.pos0;
+            item.value =
+                config.normalize === `density`
+                    ? item.value / (grand * (width || 1))
+                    : item.value / grand;
+            if (item.value > max)
+                max = item.value;
+        }
+    }
+    return { kind: `bars`, bins, max };
+}
+function compute_cdf(positions, weights) {
+    const order = positions.map((_, idx) => idx).sort((a, b) => positions[a] - positions[b]);
+    const total = weights ? weights.reduce((sum, weight) => sum + weight, 0) : positions.length;
+    const points = [];
+    let cum = 0;
+    for (const idx of order) {
+        cum += weights ? weights[idx] : 1;
+        const pos = positions[idx];
+        const value = total > 0 ? cum / total : 0;
+        // collapse ties so positions stay strictly increasing (keeps monotone curves well-behaved)
+        const last = points[points.length - 1];
+        if (last?.pos === pos)
+            last.value = value;
+        else
+            points.push({ pos, value });
+    }
+    return { kind: `line`, points, max: 1 };
+}
+// Smallest strictly-positive value (Infinity if none): repairs a degenerate log lower bound (<= 0)
+// so kde grids / histogram bins don't dip to non-renderable positions
+const smallest_positive = (vals) => vals.reduce((min, val) => (val > 0 && val < min ? val : min), Infinity);
+function compute_kde(positions, config, positional_range, scale_type) {
+    // The grid spans the current positional range, so on a normal log axis (range[0] > 0) no
+    // clamping is needed. Only repair a degenerate log range whose lower bound is <= 0 (would
+    // otherwise emit grid points at <= 0 -> NaN pixels) by clamping to the smallest positive sample.
+    let clip;
+    if (get_scale_type_name(scale_type) === `log` && positional_range[0] <= 0) {
+        const min_pos = smallest_positive(positions);
+        if (Number.isFinite(min_pos))
+            clip = [min_pos, null];
+    }
+    const kde = gaussian_kde(positions, {
+        bandwidth: config.bandwidth,
+        n_points: 100,
+        range: positional_range,
+        clip,
+        max_samples: 5000,
+    });
+    let max = 0;
+    for (const density of kde.density)
+        if (density > max)
+            max = density;
+    const points = kde.grid.map((pos, idx) => ({ pos, value: kde.density[idx] }));
+    return { kind: `line`, points, max };
+}
+// Summarize 1-D values into a renderable curve per the marginal type. Filters non-finite
+// inputs and returns an empty curve for empty input (so nothing renders).
+export function compute_marginal_curve(positions, weights, config, positional_range, scale_type) {
+    // Canonicalize to an ascending range so a reversed (inverted-axis) range doesn't crash
+    // d3.bin (negative-length bin array) or empty the kde grid
+    const range = sorted_range(positional_range[0], positional_range[1]);
+    const { positions: pos, weights: wts } = clean_pairs(positions, weights, range, scale_type);
+    // rug returns the raw positions (empty or not); other types short-circuit on empty input
+    if (config.type === `rug`)
+        return { kind: `rug`, positions: pos };
+    if (pos.length === 0) {
+        return config.type === `histogram`
+            ? { kind: `bars`, bins: [], max: 0 }
+            : { kind: `line`, points: [], max: 0 };
+    }
+    if (config.type === `histogram`) {
+        // on a degenerate log axis (lower bound <= 0) bin over the smallest positive sample instead, so
+        // bins aren't spread below the smallest renderable position (mirrors compute_kde's clip)
+        const hist_range = get_scale_type_name(scale_type) === `log` && range[0] <= 0
+            ? [smallest_positive(pos), range[1]]
+            : range;
+        return compute_histogram(pos, wts, config, hist_range);
+    }
+    if (config.type === `cdf`)
+        return compute_cdf(pos, wts);
+    return compute_kde(pos, config, range, scale_type);
+}
+// Max value across a set of curves (for a shared per-side value scale)
+export const curves_max = (curves) => curves.reduce((max, curve) => (curve.kind === `rug` ? max : Math.max(max, curve.max)), 0);
+// Value-axis title for a strip: explicit `config.label` wins, else auto per type (histogram uses
+// its normalization). `rug` has no value axis so returns an empty string.
+export const default_marginal_label = (config) => {
+    if (config.label != null)
+        return config.label;
+    if (config.type === `cdf`)
+        return `CDF`;
+    if (config.type === `kde`)
+        return `density`;
+    if (config.type === `histogram`)
+        return config.normalize ?? `count`;
+    return ``;
+};
+// d3-format spec for the strip's value-axis tick labels, picked to suit each type's value units
+export const marginal_value_format = (config) => {
+    if (config.type === `cdf`)
+        return `.0%`;
+    if (config.type === `histogram`) {
+        if (config.normalize === `probability`)
+            return `.0%`;
+        if (config.normalize === `density`)
+            return `.2~g`;
+        return `.3~s`;
+    }
+    return `.2~g`; // kde density
+};

package/dist/plot/core/pan-zoom.svelte.d.ts

@@ -0,0 +1,35 @@
+import type { Point2D, Vec2 } from '../../math';
+import type { AxisRanges, PanConfig, ScaleType } from './types';
+type Axis = `x` | `x2` | `y` | `y2`;
+export interface PanZoomOptions {
+    ranges: () => AxisRanges;
+    scale_type: (axis: Axis) => ScaleType | undefined;
+    plot_dims: () => {
+        width: number;
+        height: number;
+    };
+    pan: () => PanConfig | undefined;
+    set_range: (axis: Axis, range: Vec2) => void;
+    svg: () => SVGElement | null;
+    on_rect_zoom: (start: Point2D, current: Point2D) => void;
+    on_reset: () => void;
+    on_drag_move?: (coords: Point2D, inside_svg: boolean) => void;
+}
+export declare function create_pan_zoom(opts: PanZoomOptions): {
+    readonly drag_start: Point2D | null;
+    readonly drag_current: Point2D | null;
+    readonly is_pan_dragging: boolean;
+    readonly cursor: string;
+    set_focused: (focused: boolean) => void;
+    on_mouse_down: (evt: MouseEvent) => void;
+    on_wheel: (evt: WheelEvent) => void;
+    on_touch_start: (evt: TouchEvent) => void;
+    on_touch_move: (evt: TouchEvent) => void;
+    on_touch_end: () => void;
+    on_key_down: (evt: KeyboardEvent) => void;
+    on_window_key_down: (evt: KeyboardEvent) => void;
+    on_window_key_up: (evt: KeyboardEvent) => void;
+    reset_view: () => void;
+    destroy: () => void;
+};
+export {};