matterviz 0.3.6 → 0.4.0

package/dist/plot/box/BoxPlot.svelte.d.ts

@@ -0,0 +1,94 @@
+import type { BandwidthOption, BasePlotProps, BoxHandlerProps, BoxPlotSeries, LegendConfig, Orientation, PanConfig, PlotConfig, RefLine, RefLineEvent, UserContentProps, ViolinKind, ViolinSide, WhiskerMode } from '..';
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+declare function $$render<Metadata extends Record<string, unknown> = Record<string, unknown>>(): {
+    props: HTMLAttributes<HTMLDivElement> & BasePlotProps & PlotConfig & {
+        series?: BoxPlotSeries<Metadata>[];
+        orientation?: Orientation;
+        legend?: LegendConfig | null;
+        show_legend?: boolean;
+        box?: {
+            color?: string;
+            opacity?: number;
+            stroke_width?: number;
+            stroke_color?: string;
+            border_radius?: number;
+        };
+        whisker?: {
+            width?: number;
+            color?: string;
+            cap_fraction?: number;
+        };
+        median_style?: {
+            width?: number;
+            color?: string;
+        };
+        outlier_style?: {
+            radius?: number;
+            opacity?: number;
+            stroke_width?: number;
+        };
+        whisker_mode?: WhiskerMode;
+        whisker_range?: number;
+        whisker_percentiles?: [number, number];
+        show_outliers?: boolean;
+        show_mean?: boolean;
+        show_value_labels?: boolean;
+        value_label_stat?: `median` | `mean`;
+        value_label_format?: string;
+        kind?: ViolinKind;
+        side?: ViolinSide;
+        bandwidth?: BandwidthOption;
+        violin_width?: number;
+        violin_style?: {
+            opacity?: number;
+            stroke_width?: number;
+        };
+        kde_points?: number;
+        kde_cut?: number;
+        kde_max_samples?: number;
+        kde_clip?: [number | null, number | null];
+        tooltip?: Snippet<[BoxHandlerProps<Metadata>]>;
+        user_content?: Snippet<[UserContentProps]>;
+        header_controls?: Snippet<[{
+            height: number;
+            width: number;
+            fullscreen: boolean;
+        }]>;
+        controls_extra?: Snippet<[{
+            orientation: Orientation;
+        } & Required<PlotConfig>]>;
+        change?: (data: BoxHandlerProps<Metadata> | null) => void;
+        on_box_click?: (data: BoxHandlerProps<Metadata> & {
+            event: MouseEvent | KeyboardEvent;
+        }) => void;
+        on_box_hover?: (data: (BoxHandlerProps<Metadata> & {
+            event: MouseEvent | FocusEvent | KeyboardEvent;
+        }) | null) => void;
+        ref_lines?: RefLine[];
+        on_ref_line_click?: (event: RefLineEvent) => void;
+        on_ref_line_hover?: (event: RefLineEvent | null) => void;
+        pan?: PanConfig;
+    };
+    exports: {};
+    bindings: "orientation" | "display" | "show_controls" | "fullscreen" | "series" | "hovered" | "ref_lines" | "controls_open" | "x_axis" | "y_axis" | "whisker_mode" | "x2_axis" | "y2_axis" | "show_outliers" | "show_mean" | "kind" | "side";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Metadata extends Record<string, unknown> = Record<string, unknown>> {
+    props(): ReturnType<typeof $$render<Metadata>>['props'];
+    events(): ReturnType<typeof $$render<Metadata>>['events'];
+    slots(): ReturnType<typeof $$render<Metadata>>['slots'];
+    bindings(): "orientation" | "display" | "show_controls" | "fullscreen" | "series" | "hovered" | "ref_lines" | "controls_open" | "x_axis" | "y_axis" | "whisker_mode" | "x2_axis" | "y2_axis" | "show_outliers" | "show_mean" | "kind" | "side";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <Metadata extends Record<string, unknown> = Record<string, unknown>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Metadata>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Metadata>['props']>, ReturnType<__sveltets_Render<Metadata>['events']>, ReturnType<__sveltets_Render<Metadata>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Metadata>['bindings']>;
+    } & ReturnType<__sveltets_Render<Metadata>['exports']>;
+    <Metadata extends Record<string, unknown> = Record<string, unknown>>(internal: unknown, props: ReturnType<__sveltets_Render<Metadata>['props']> & {}): ReturnType<__sveltets_Render<Metadata>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const BoxPlot: $$IsomorphicComponent;
+type BoxPlot<Metadata extends Record<string, unknown> = Record<string, unknown>> = InstanceType<typeof BoxPlot<Metadata>>;
+export default BoxPlot;

package/dist/plot/box/BoxPlotControls.svelte

@@ -0,0 +1,109 @@
+<script lang="ts">
+  import { SettingsSection } from '../../layout'
+  import type { Orientation, PlotConfig, ViolinKind, ViolinSide, WhiskerMode } from '..'
+  import { PlotControls } from '..'
+  import type { PlotControlsProps } from '../core/types'
+  import { unique_id } from '../core/utils'
+  import { DEFAULTS } from '../../settings'
+  import type { Snippet } from 'svelte'
+
+  // Unique ID prefix to avoid conflicts when multiple instances on same page
+  const uid = unique_id(`box-ctrl`)
+
+  let {
+    orientation = $bindable(`vertical`),
+    whisker_mode = $bindable(`tukey`),
+    show_outliers = $bindable(true),
+    show_mean = $bindable(false),
+    kind = $bindable(`box`),
+    side = $bindable(`both`),
+    x_axis = $bindable({}),
+    x2_axis = $bindable({}),
+    y_axis = $bindable({}),
+    y2_axis = $bindable({}),
+    display = $bindable({}),
+    show_controls = $bindable(false),
+    controls_open = $bindable(false),
+    children,
+    ...rest
+  }: Omit<PlotControlsProps, `children` | `post_children`> & {
+    orientation?: Orientation
+    whisker_mode?: WhiskerMode
+    show_outliers?: boolean
+    show_mean?: boolean
+    kind?: ViolinKind
+    side?: ViolinSide
+    show_controls?: boolean
+    controls_open?: boolean
+    children?: Snippet<[{ orientation: Orientation } & Required<PlotConfig>]>
+  } = $props()
+</script>
+
+<PlotControls
+  bind:show_controls
+  bind:controls_open
+  bind:x_axis
+  bind:x2_axis
+  bind:y_axis
+  bind:y2_axis
+  bind:display
+  {...rest}
+>
+  {@render children?.({ orientation, x_axis, x2_axis, y_axis, y2_axis, display })}
+  <SettingsSection
+    title="Box / Violin"
+    current_values={{ orientation, kind, side, whisker_mode, show_outliers, show_mean }}
+    on_reset={() => {
+      orientation = `vertical`
+      kind = DEFAULTS.box.kind
+      side = DEFAULTS.box.side
+      whisker_mode = DEFAULTS.box.whisker_mode
+      show_outliers = DEFAULTS.box.show_outliers
+      show_mean = DEFAULTS.box.show_mean
+    }}
+    style="display: flex; flex-wrap: wrap; gap: 2ex"
+  >
+    <label style="flex: 1">
+      Orientation:
+      <select bind:value={orientation} id="{uid}-orientation">
+        <option value="vertical">Vertical</option>
+        <option value="horizontal">Horizontal</option>
+      </select>
+    </label>
+    <label style="flex: 1">
+      Glyph:
+      <select bind:value={kind} id="{uid}-kind">
+        <option value="box">Box</option>
+        <option value="violin">Violin</option>
+        <option value="violin+box">Violin + Box</option>
+      </select>
+    </label>
+    {#if kind !== `box`}
+      <label style="flex: 1">
+        Violin side:
+        <select bind:value={side} id="{uid}-side">
+          <option value="both">Both</option>
+          <option value="positive">Positive</option>
+          <option value="negative">Negative</option>
+        </select>
+      </label>
+    {/if}
+    <label style="flex: 1">
+      Whiskers:
+      <select bind:value={whisker_mode} id="{uid}-whisker-mode">
+        <option value="tukey">Tukey (1.5·IQR)</option>
+        <option value="minmax">Min/Max</option>
+        <option value="percentile">Percentile</option>
+        <option value="std">Std Dev</option>
+      </select>
+    </label>
+    <label style="flex: 1 1 100%">
+      <input type="checkbox" bind:checked={show_outliers} />
+      Show outliers
+    </label>
+    <label style="flex: 1 1 100%">
+      <input type="checkbox" bind:checked={show_mean} />
+      Show mean
+    </label>
+  </SettingsSection>
+</PlotControls>

package/dist/plot/box/BoxPlotControls.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { Orientation, PlotConfig, ViolinKind, ViolinSide, WhiskerMode } from '..';
+import type { PlotControlsProps } from '../core/types';
+import type { Snippet } from 'svelte';
+type $$ComponentProps = Omit<PlotControlsProps, `children` | `post_children`> & {
+    orientation?: Orientation;
+    whisker_mode?: WhiskerMode;
+    show_outliers?: boolean;
+    show_mean?: boolean;
+    kind?: ViolinKind;
+    side?: ViolinSide;
+    show_controls?: boolean;
+    controls_open?: boolean;
+    children?: Snippet<[{
+        orientation: Orientation;
+    } & Required<PlotConfig>]>;
+};
+declare const BoxPlotControls: import("svelte").Component<$$ComponentProps, {}, "orientation" | "display" | "show_controls" | "controls_open" | "x_axis" | "y_axis" | "whisker_mode" | "x2_axis" | "y2_axis" | "show_outliers" | "show_mean" | "kind" | "side">;
+type BoxPlotControls = ReturnType<typeof BoxPlotControls>;
+export default BoxPlotControls;

package/dist/plot/box/Violin.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  // Thin wrapper around BoxPlot with violin defaults. A violin is the same chart as a box
+  // plot (per-series raw distribution on a categorical axis), so all the scaffolding is shared.
+  import type { ComponentProps } from 'svelte'
+  import BoxPlot from './BoxPlot.svelte'
+
+  let {
+    series = $bindable([]),
+    kind = $bindable(`violin`),
+    ...rest
+  }: ComponentProps<typeof BoxPlot> = $props()
+</script>
+
+<BoxPlot bind:series bind:kind {...rest} />

package/dist/plot/box/Violin.svelte.d.ts

@@ -0,0 +1,70 @@
+declare const Violin: import("svelte").Component<import("svelte/elements").HTMLAttributes<HTMLDivElement> & import("..").BasePlotProps & import("..").PlotConfig & {
+    series?: import("./box-plot").BoxPlotSeries<Record<string, unknown>>[] | undefined;
+    orientation?: import("..").Orientation;
+    legend?: import("..").LegendConfig | null;
+    show_legend?: boolean;
+    box?: {
+        color?: string;
+        opacity?: number;
+        stroke_width?: number;
+        stroke_color?: string;
+        border_radius?: number;
+    } | undefined;
+    whisker?: {
+        width?: number;
+        color?: string;
+        cap_fraction?: number;
+    } | undefined;
+    median_style?: {
+        width?: number;
+        color?: string;
+    } | undefined;
+    outlier_style?: {
+        radius?: number;
+        opacity?: number;
+        stroke_width?: number;
+    } | undefined;
+    whisker_mode?: import("./box-plot").WhiskerMode;
+    whisker_range?: number;
+    whisker_percentiles?: [number, number];
+    show_outliers?: boolean;
+    show_mean?: boolean;
+    show_value_labels?: boolean;
+    value_label_stat?: `median` | `mean`;
+    value_label_format?: string;
+    kind?: import("./box-plot").ViolinKind;
+    side?: import("./box-plot").ViolinSide;
+    bandwidth?: import("./box-plot").BandwidthOption;
+    violin_width?: number;
+    violin_style?: {
+        opacity?: number;
+        stroke_width?: number;
+    } | undefined;
+    kde_points?: number;
+    kde_cut?: number;
+    kde_max_samples?: number;
+    kde_clip?: [number | null, number | null];
+    tooltip?: import("svelte").Snippet<[import("./box-plot").BoxHandlerProps<Record<string, unknown>>]> | undefined;
+    user_content?: import("svelte").Snippet<[import("..").UserContentProps]>;
+    header_controls?: import("svelte").Snippet<[{
+        height: number;
+        width: number;
+        fullscreen: boolean;
+    }]> | undefined;
+    controls_extra?: import("svelte").Snippet<[{
+        orientation: import("..").Orientation;
+    } & Required<import("..").PlotConfig>]> | undefined;
+    change?: ((data: import("./box-plot").BoxHandlerProps<Record<string, unknown>> | null) => void) | undefined;
+    on_box_click?: ((data: import("./box-plot").BoxHandlerProps<Record<string, unknown>> & {
+        event: MouseEvent | KeyboardEvent;
+    }) => void) | undefined;
+    on_box_hover?: ((data: (import("./box-plot").BoxHandlerProps<Record<string, unknown>> & {
+        event: MouseEvent | FocusEvent | KeyboardEvent;
+    }) | null) => void) | undefined;
+    ref_lines?: import("..").RefLine[];
+    on_ref_line_click?: ((event: import("..").RefLineEvent) => void) | undefined;
+    on_ref_line_hover?: ((event: import("..").RefLineEvent | null) => void) | undefined;
+    pan?: import("..").PanConfig;
+}, {}, "series" | "kind">;
+type Violin = ReturnType<typeof Violin>;
+export default Violin;

package/dist/plot/box/box-plot.d.ts

@@ -0,0 +1,55 @@
+import type { HandlerProps } from '../core/types';
+export type WhiskerMode = `tukey` | `minmax` | `percentile` | `std`;
+export type ViolinKind = `box` | `violin` | `violin+box`;
+export type ViolinSide = `both` | `positive` | `negative`;
+export type BandwidthOption = number | `silverman` | `scott`;
+export interface BoxPlotSeries<Metadata = Record<string, unknown>> {
+    id?: string | number;
+    y: readonly number[];
+    label?: string;
+    color?: string;
+    box_width?: number;
+    visible?: boolean;
+    legend_group?: string;
+    metadata?: Metadata;
+    x_axis?: `x1` | `x2`;
+    y_axis?: `y1` | `y2`;
+    whisker_mode?: WhiskerMode;
+    whisker_range?: number;
+    whisker_percentiles?: [number, number];
+    kind?: ViolinKind;
+    side?: ViolinSide;
+    bandwidth?: BandwidthOption;
+    violin_width?: number;
+    clip?: [number | null, number | null];
+    category?: string;
+}
+export interface BoxHandlerProps<Metadata = Record<string, unknown>> extends HandlerProps<Metadata> {
+    box_idx: number;
+    stats: BoxStats;
+    color: string;
+    category_label?: string;
+    active_y_axis: `y1` | `y2`;
+    active_x_axis: `x1` | `x2`;
+}
+export interface BoxStats {
+    min: number;
+    max: number;
+    q1: number;
+    median: number;
+    q3: number;
+    mean: number;
+    whisker_low: number;
+    whisker_high: number;
+    outliers: number[];
+    n: number;
+}
+export interface BoxStatsOptions {
+    whisker_mode?: WhiskerMode;
+    whisker_range?: number;
+    whisker_percentiles?: [number, number];
+    collect_outliers?: boolean;
+}
+export declare const WHISKER_MODES: readonly ["tukey", "minmax", "percentile", "std"];
+export declare const is_whisker_mode: (val: string) => val is WhiskerMode;
+export declare function compute_box_stats(values: readonly number[], opts?: BoxStatsOptions): BoxStats;

package/dist/plot/box/box-plot.js

@@ -0,0 +1,126 @@
+// Box plot statistics: compute quartiles, whiskers and outliers from a raw distribution.
+// Single source of truth for the quantile math used by BoxPlot.svelte.
+import { ascending } from 'd3-array';
+import { quantile_unordered } from './quantile';
+export const WHISKER_MODES = [`tukey`, `minmax`, `percentile`, `std`];
+const WHISKER_MODE_SET = new Set(WHISKER_MODES);
+export const is_whisker_mode = (val) => WHISKER_MODE_SET.has(val);
+const EMPTY_STATS = {
+    min: NaN,
+    max: NaN,
+    q1: NaN,
+    median: NaN,
+    q3: NaN,
+    mean: NaN,
+    whisker_low: NaN,
+    whisker_high: NaN,
+    outliers: [],
+    n: 0,
+};
+const clamp01 = (val) => Math.max(0, Math.min(1, val));
+function collect_outliers_by_scan(values, low_bound, high_bound, collect) {
+    if (!collect)
+        return [];
+    const outliers = [];
+    for (const val of values)
+        if (val < low_bound || val > high_bound)
+            outliers.push(val);
+    outliers.sort(ascending);
+    return outliers;
+}
+function tukey_scan(values, low_bound, high_bound, collect, data_min, data_max) {
+    let whisker_low = Infinity;
+    let whisker_high = -Infinity;
+    const outliers = [];
+    for (const val of values) {
+        if (val < low_bound || val > high_bound) {
+            if (collect)
+                outliers.push(val);
+        }
+        else {
+            if (val < whisker_low)
+                whisker_low = val;
+            if (val > whisker_high)
+                whisker_high = val;
+        }
+    }
+    if (collect)
+        outliers.sort(ascending);
+    return {
+        whisker_low: whisker_low === Infinity ? data_min : whisker_low,
+        whisker_high: whisker_high === -Infinity ? data_max : whisker_high,
+        outliers,
+    };
+}
+// Compute box plot statistics for a raw numeric distribution.
+// Quartiles use type-7 linear interpolation, matching d3/numpy/pandas defaults.
+// Non-finite values are filtered out; the input array is never mutated.
+export function compute_box_stats(values, opts = {}) {
+    const { whisker_mode = `tukey`, whisker_range = 1.5, whisker_percentiles = [5, 95], collect_outliers = true, } = opts;
+    const vals = values.filter((val) => Number.isFinite(val));
+    const n_vals = vals.length;
+    if (n_vals === 0)
+        return { ...EMPTY_STATS, outliers: [] };
+    let sum = 0;
+    let data_min = Infinity;
+    let data_max = -Infinity;
+    for (const val of vals) {
+        sum += val;
+        if (val < data_min)
+            data_min = val;
+        if (val > data_max)
+            data_max = val;
+    }
+    const mean = sum / n_vals;
+    const qtl = (p) => quantile_unordered(vals, p);
+    const collect_beyond = (lo, hi) => collect_outliers_by_scan(vals, lo, hi, collect_outliers);
+    const q1 = qtl(0.25);
+    const median = qtl(0.5);
+    const q3 = qtl(0.75);
+    let whisker_low;
+    let whisker_high;
+    let outliers = [];
+    if (whisker_mode === `minmax`) {
+        whisker_low = data_min;
+        whisker_high = data_max;
+    }
+    else if (whisker_mode === `percentile`) {
+        // Order-defensively so reversed input like [95, 5] still yields low <= high
+        const pct_low = Math.min(...whisker_percentiles);
+        const pct_high = Math.max(...whisker_percentiles);
+        whisker_low = qtl(clamp01(pct_low / 100));
+        whisker_high = qtl(clamp01(pct_high / 100));
+        outliers = collect_beyond(whisker_low, whisker_high);
+    }
+    else if (whisker_mode === `std`) {
+        let variance_sum = 0;
+        for (const val of vals) {
+            const delta = val - mean;
+            variance_sum += delta * delta;
+        }
+        const std = n_vals > 1 ? Math.sqrt(variance_sum / (n_vals - 1)) : 0;
+        const low_bound = mean - whisker_range * std;
+        const high_bound = mean + whisker_range * std;
+        // Clamp whisker ends to the data extent so they never extend past real values
+        whisker_low = Math.max(data_min, low_bound);
+        whisker_high = Math.min(data_max, high_bound);
+        outliers = collect_beyond(low_bound, high_bound);
+    }
+    else {
+        // tukey (default): whiskers extend to the most extreme datum within range*IQR of the quartiles
+        const iqr = q3 - q1;
+        ({ whisker_low, whisker_high, outliers } = tukey_scan(vals, q1 - whisker_range * iqr, q3 + whisker_range * iqr, collect_outliers, data_min, data_max));
+    }
+    return {
+        min: data_min,
+        max: data_max,
+        q1,
+        median,
+        q3,
+        mean,
+        whisker_low,
+        whisker_high,
+        outliers,
+        n: n_vals,
+    };
+}

package/dist/plot/box/index.d.ts

@@ -0,0 +1,5 @@
+export * from './box-plot';
+export * from './kde';
+export { default as BoxPlot } from './BoxPlot.svelte';
+export { default as BoxPlotControls } from './BoxPlotControls.svelte';
+export { default as Violin } from './Violin.svelte';

package/dist/plot/box/index.js

@@ -0,0 +1,5 @@
+export * from './box-plot';
+export * from './kde';
+export { default as BoxPlot } from './BoxPlot.svelte';
+export { default as BoxPlotControls } from './BoxPlotControls.svelte';
+export { default as Violin } from './Violin.svelte';

package/dist/plot/box/kde.d.ts

@@ -0,0 +1,16 @@
+export interface KdeResult {
+    grid: number[];
+    density: number[];
+    bandwidth: number;
+}
+export interface KdeOptions {
+    bandwidth?: number | `silverman` | `scott`;
+    n_points?: number;
+    cut?: number;
+    clip?: [number | null, number | null];
+    range?: [number, number];
+    max_samples?: number;
+}
+export declare function silverman_bandwidth(sorted: readonly number[]): number;
+export declare function scott_bandwidth(samples: readonly number[]): number;
+export declare function gaussian_kde(samples: readonly number[], opts?: KdeOptions): KdeResult;

package/dist/plot/box/kde.js

@@ -0,0 +1,160 @@
+// 1-D Gaussian kernel density estimation for violin plots.
+// Pure and unit-tested; mirrors the style of box-plot.ts. Never mutates inputs.
+import { quantile_sorted, quantile_unordered } from './quantile';
+const KDE_EXACT_SAMPLE_LIMIT = 1024;
+const KDE_TAIL_SIGMA = 6;
+function sample_deviation(sorted) {
+    const n_vals = sorted.length;
+    if (n_vals < 2)
+        return 0;
+    let sum = 0;
+    for (const val of sorted)
+        sum += val;
+    const mean = sum / n_vals;
+    let variance_sum = 0;
+    for (const val of sorted) {
+        const delta = val - mean;
+        variance_sum += delta * delta;
+    }
+    return Math.sqrt(variance_sum / (n_vals - 1));
+}
+// Silverman's rule of thumb: 0.9 * min(std, IQR/1.34) * n^(-1/5). Matches scipy/seaborn.
+// (`sigma` floors to std then 1 to avoid a zero bandwidth.)
+const silverman_from_stats = (n_vals, std, iqr) => {
+    const spread = iqr > 0 ? Math.min(std, iqr / 1.34) : std;
+    const sigma = spread > 0 ? spread : std > 0 ? std : 1;
+    return 0.9 * sigma * n_vals ** (-1 / 5);
+};
+export function silverman_bandwidth(sorted) {
+    if (sorted.length < 2)
+        return 1;
+    const iqr = quantile_sorted(sorted, 0.75) - quantile_sorted(sorted, 0.25);
+    return silverman_from_stats(sorted.length, sample_deviation(sorted), iqr);
+}
+function silverman_bandwidth_unordered(samples) {
+    if (samples.length < 2)
+        return 1;
+    const q1 = quantile_unordered(samples, 0.25);
+    const q3 = quantile_unordered(samples, 0.75);
+    return silverman_from_stats(samples.length, sample_deviation(samples), q3 - q1);
+}
+// Scott's rule: std * n^(-1/5) for 1-D data.
+// `samples` need not be sorted (only uses sample_deviation, unlike silverman_bandwidth)
+export function scott_bandwidth(samples) {
+    const n_vals = samples.length;
+    if (n_vals < 2)
+        return 1;
+    const std = sample_deviation(samples) || 1;
+    return std * n_vals ** (-1 / 5);
+}
+function exact_density(eval_samples, grid, band) {
+    const n_eval = eval_samples.length;
+    const norm = 1 / (n_eval * band * Math.sqrt(2 * Math.PI));
+    const density = Array.from({ length: grid.length }, () => 0);
+    for (let grid_idx = 0; grid_idx < grid.length; grid_idx++) {
+        const g_val = grid[grid_idx];
+        let sum = 0;
+        for (const sample of eval_samples) {
+            const u = (g_val - sample) / band;
+            sum += Math.exp(-0.5 * u * u);
+        }
+        density[grid_idx] = sum * norm;
+    }
+    return density;
+}
+function binned_density(eval_samples, grid, band) {
+    const n_eval = eval_samples.length;
+    let sample_min = Infinity;
+    let sample_max = -Infinity;
+    for (const sample of eval_samples) {
+        if (sample < sample_min)
+            sample_min = sample;
+        if (sample > sample_max)
+            sample_max = sample;
+    }
+    if (sample_max <= sample_min)
+        return exact_density(eval_samples, grid, band);
+    const bin_count = Math.min(1024, Math.max(128, grid.length * 4));
+    const counts = new Float64Array(bin_count);
+    const span = sample_max - sample_min;
+    const inv_bin_width = bin_count / span;
+    for (const sample of eval_samples) {
+        const idx = Math.min(bin_count - 1, Math.floor((sample - sample_min) * inv_bin_width));
+        counts[idx] += 1;
+    }
+    const centers = new Float64Array(bin_count);
+    const bin_width = span / bin_count;
+    for (let idx = 0; idx < bin_count; idx++)
+        centers[idx] = sample_min + (idx + 0.5) * bin_width;
+    const density = Array.from({ length: grid.length }, () => 0);
+    const norm = 1 / (n_eval * band * Math.sqrt(2 * Math.PI));
+    const radius = KDE_TAIL_SIGMA * band;
+    for (let grid_idx = 0; grid_idx < grid.length; grid_idx++) {
+        const g_val = grid[grid_idx];
+        const start = Math.max(0, Math.floor((g_val - radius - sample_min) * inv_bin_width));
+        const stop = Math.min(bin_count - 1, Math.floor((g_val + radius - sample_min) * inv_bin_width));
+        let sum = 0;
+        for (let bin_idx = start; bin_idx <= stop; bin_idx++) {
+            const count = counts[bin_idx];
+            if (count === 0)
+                continue;
+            const u = (g_val - centers[bin_idx]) / band;
+            sum += count * Math.exp(-0.5 * u * u);
+        }
+        density[grid_idx] = sum * norm;
+    }
+    return density;
+}
+// Estimate a smooth density from raw samples via a Gaussian kernel.
+export function gaussian_kde(samples, opts = {}) {
+    const { bandwidth = `silverman`, n_points = 100, cut = 2, clip, range, max_samples } = opts;
+    const finite = samples.filter((val) => Number.isFinite(val));
+    const n_vals = finite.length;
+    if (n_vals === 0)
+        return { grid: [], density: [], bandwidth: 0 };
+    let data_min = Infinity;
+    let data_max = -Infinity;
+    for (const sample of finite) {
+        if (sample < data_min)
+            data_min = sample;
+        if (sample > data_max)
+            data_max = sample;
+    }
+    // Deterministic stride subsample for the density sum on large inputs.
+    // Do this before unordered quantile selection mutates `finite`.
+    let eval_samples = finite;
+    if (max_samples && n_vals > max_samples) {
+        const step = n_vals / max_samples;
+        const sampled = Array.from({ length: max_samples }, () => 0);
+        for (let idx = 0; idx < max_samples; idx++)
+            sampled[idx] = finite[Math.floor(idx * step)];
+        eval_samples = sampled;
+    }
+    let band = typeof bandwidth === `number`
+        ? bandwidth
+        : bandwidth === `scott`
+            ? scott_bandwidth(finite)
+            : silverman_bandwidth_unordered(finite);
+    band = Math.max(band, 1e-12); // guard against zero/negative bandwidth
+    const n_eval = eval_samples.length;
+    let lo = range ? range[0] : data_min - cut * band;
+    let hi = range ? range[1] : data_max + cut * band;
+    if (clip) {
+        if (clip[0] != null)
+            lo = Math.max(lo, clip[0]);
+        if (clip[1] != null)
+            hi = Math.min(hi, clip[1]);
+    }
+    // An inverted/collapsed range (e.g. clip [10, 5], or a clip bound outside the data) leaves
+    // no valid grid -> degrade to an empty density rather than a corrupted descending grid.
+    if (hi <= lo)
+        return { grid: [], density: [], bandwidth: band };
+    const points = Math.max(2, Math.floor(n_points));
+    const grid = Array.from({ length: points }, () => 0);
+    for (let idx = 0; idx < points; idx++)
+        grid[idx] = lo + ((hi - lo) * idx) / (points - 1);
+    const density = max_samples && n_eval > KDE_EXACT_SAMPLE_LIMIT
+        ? binned_density(eval_samples, grid, band)
+        : exact_density(eval_samples, grid, band);
+    return { grid, density, bandwidth: band };
+}