matterviz 0.3.6 → 0.3.7

package/dist/plot/scales.js

@@ -0,0 +1,481 @@
+import * as math from '../math';
+import { get_arcsinh_threshold, get_scale_type_name, is_time_scale } from './types';
+import { extent, range } from 'd3-array';
+import { scaleLinear, scaleLog, scaleSequential, scaleSequentialLog, scaleTime, } from 'd3-scale';
+import * as d3_sc from 'd3-scale-chromatic';
+// Dedupe and sort numeric array (used in tick generation)
+const dedupe_sort = (arr) => [...new Set(arr)].sort((a, b) => a - b);
+// Create an arcsinh scale with configurable threshold
+export function scale_arcsinh(threshold = 1) {
+    if (!Number.isFinite(threshold) || threshold <= 0) {
+        throw new Error(`arcsinh threshold must be a positive finite number, got ${threshold}`);
+    }
+    let current_domain = [0, 1];
+    let current_range = [0, 1];
+    // Forward transform: data value → arcsinh-space
+    const arcsinh_transform = (x) => Math.asinh(x / threshold);
+    // Inverse transform: arcsinh-space → data value
+    const sinh_transform = (y) => Math.sinh(y) * threshold;
+    // Map from data domain to output range
+    // Accepts Date for compatibility with D3 time scales
+    const scale = ((value) => {
+        const num_value = value instanceof Date ? value.getTime() : value;
+        const [d_min, d_max] = current_domain;
+        const [r_min, r_max] = current_range;
+        // Handle identical domain endpoints (degenerate case)
+        if (d_max === d_min)
+            return (r_min + r_max) / 2;
+        // Transform domain endpoints
+        const t_min = arcsinh_transform(d_min);
+        const t_max = arcsinh_transform(d_max);
+        // Transform input value
+        const t_val = arcsinh_transform(num_value);
+        // Linear interpolation in transformed space
+        if (t_max === t_min)
+            return (r_min + r_max) / 2;
+        const t = (t_val - t_min) / (t_max - t_min);
+        return r_min + t * (r_max - r_min);
+    });
+    // Domain getter/setter
+    scale.domain = function (domain) {
+        if (domain === undefined)
+            return current_domain;
+        current_domain = domain;
+        return scale;
+    };
+    // Range getter/setter
+    scale.range = function (output_range) {
+        if (output_range === undefined)
+            return current_range;
+        current_range = output_range;
+        return scale;
+    };
+    // Invert: screen position → data value
+    scale.invert = (value) => {
+        const [d_min, d_max] = current_domain;
+        const [r_min, r_max] = current_range;
+        // Handle identical domain endpoints (degenerate case)
+        if (d_max === d_min)
+            return (d_min + d_max) / 2;
+        // Transform domain endpoints
+        const t_min = arcsinh_transform(d_min);
+        const t_max = arcsinh_transform(d_max);
+        // Inverse linear interpolation
+        if (r_max === r_min)
+            return (d_min + d_max) / 2;
+        const t = (value - r_min) / (r_max - r_min);
+        const t_val = t_min + t * (t_max - t_min);
+        // Inverse transform
+        return sinh_transform(t_val);
+    };
+    // Copy the scale
+    scale.copy = () => {
+        const copy = scale_arcsinh(threshold);
+        copy.domain(current_domain);
+        copy.range(current_range);
+        return copy;
+    };
+    // Generate nice ticks for arcsinh scale
+    scale.ticks = (count = 10) => {
+        return generate_arcsinh_ticks(current_domain[0], current_domain[1], threshold, count);
+    };
+    scale.threshold = threshold;
+    return scale;
+}
+// Generate nice tick values for arcsinh scale
+// Strategy: symmetric around zero when possible, with powers of 10 for large values
+// Note: For small count values (1 or 2) on mixed ranges, zero takes priority as the
+// most important tick. E.g., count=1 yields [0], count=2 yields [0] plus one boundary.
+export function generate_arcsinh_ticks(min, max, threshold = 1, count = 10) {
+    // Guard against invalid/non-positive threshold to prevent division issues
+    const safe_threshold = Math.max(threshold, Number.EPSILON);
+    // Normalize reversed domains (min > max)
+    const [lo, hi] = min <= max ? [min, max] : [max, min];
+    // For purely positive or purely negative ranges, use log-like spacing
+    if (lo >= 0) {
+        return generate_positive_arcsinh_ticks(lo, hi, safe_threshold, count);
+    }
+    if (hi <= 0) {
+        // Negative range: mirror the positive logic
+        return generate_positive_arcsinh_ticks(-hi, -lo, safe_threshold, count)
+            .map((tick) => -tick)
+            .toReversed();
+    }
+    // Mixed range: symmetric ticks around zero (includes_zero is always true here)
+    // For very small counts, we prioritize zero as the most meaningful tick
+    const half_count = Math.floor((count - 1) / 2);
+    const ticks = [0];
+    // Add positive ticks
+    const pos_ticks = generate_positive_arcsinh_ticks(0, hi, safe_threshold, half_count);
+    ticks.push(...pos_ticks.filter((tick) => tick > 0));
+    // Add negative ticks (mirror of positive)
+    const neg_ticks = generate_positive_arcsinh_ticks(0, -lo, safe_threshold, half_count);
+    ticks.push(...neg_ticks.filter((tick) => tick > 0).map((tick) => -tick));
+    // For small counts where half_count is 0 or 1, ensure at least some boundary coverage
+    if (half_count <= 1 && count >= 2) {
+        // Add boundaries if not already present and we have room
+        const sorted = dedupe_sort(ticks);
+        if (sorted.length < count) {
+            // Snap the larger-magnitude boundary to a clean power of 10 (raw extremes would render
+            // as long unrounded labels); keeps some coverage for very small tick counts.
+            const boundary = Math.abs(hi) >= Math.abs(lo) ? hi : lo;
+            const nice = Math.sign(boundary) * 10 ** Math.floor(Math.log10(Math.abs(boundary)));
+            if (Number.isFinite(nice) && nice !== 0 && !sorted.includes(nice))
+                ticks.push(nice);
+        }
+    }
+    return dedupe_sort(ticks);
+}
+// Generate positive arcsinh ticks (helper)
+// Ensures domain boundaries (min, max) are included when they provide meaningful
+// visual anchors that powers-of-10 alone might miss.
+function generate_positive_arcsinh_ticks(min, max, threshold, count) {
+    if (count <= 0 || max <= min)
+        return [];
+    const ticks = [];
+    // For values near threshold, use linear-like spacing
+    // For values >> threshold, use log-like spacing (powers of 10)
+    if (max <= threshold * 2) {
+        // Small range: use linear ticks
+        const step = (max - min) / count;
+        for (let idx = 0; idx <= count; idx++) {
+            const val = min + step * idx;
+            if (val >= min && val <= max)
+                ticks.push(val);
+        }
+    }
+    else {
+        // Large range: combine linear near zero with powers of 10.
+        // Domain endpoints are intentionally NOT added as ticks: raw extremes render as long
+        // unrounded labels (e.g. 1325.8239811994677). Powers of 10 plus 2x/5x multiples below
+        // already give clean round ticks; pass axis.ticks/axis.format for custom labels.
+        // Add threshold as a tick if in range
+        if (threshold >= min && threshold <= max)
+            ticks.push(threshold);
+        // Add powers of 10 that are in range
+        const min_power = Math.floor(Math.log10(Math.max(min, threshold / 10)));
+        const max_power = Math.ceil(Math.log10(max));
+        for (let power = min_power; power <= max_power; power++) {
+            const val = Math.pow(10, power);
+            if (val >= min && val <= max)
+                ticks.push(val);
+        }
+        // Add intermediate values (2x, 5x) for sparser regions
+        if (ticks.length < count) {
+            for (let power = min_power; power < max_power; power++) {
+                const base = Math.pow(10, power);
+                for (const mult of [2, 5]) {
+                    const val = base * mult;
+                    if (val >= min && val <= max)
+                        ticks.push(val);
+                }
+            }
+        }
+    }
+    return dedupe_sort(ticks);
+}
+// Create a scale function based on type, domain, and range
+// Note: Time scales are handled separately via create_time_scale() since ScaleTime
+// has incompatible types (invert returns Date, not number). Use is_time_scale()
+// to detect time mode and call create_time_scale() directly when needed.
+export function create_scale(scale_type, domain, output_range) {
+    const [min_val, max_val] = domain;
+    const type_name = get_scale_type_name(scale_type);
+    if (type_name === `log`) {
+        return scaleLog()
+            .domain([Math.max(min_val, math.LOG_EPS), max_val])
+            .range(output_range);
+    }
+    if (type_name === `arcsinh`) {
+        const threshold = get_arcsinh_threshold(scale_type);
+        return scale_arcsinh(threshold).domain(domain).range(output_range);
+    }
+    // For 'time' or 'linear', return linear scale (time scales need create_time_scale())
+    return scaleLinear().domain(domain).range(output_range);
+}
+// Create a time scale for time-based data
+export const create_time_scale = (domain, output_range) => scaleTime()
+    .domain([new Date(domain[0]), new Date(domain[1])])
+    .range(output_range);
+// Unified tick generation function
+export function generate_ticks(domain, scale_type, ticks_option, scale_fn, // D3 scale function with .ticks() method
+options = {}) {
+    const { format, default_count = 8, interval_padding = 0.1 } = options;
+    const [min_val, max_val] = domain;
+    // If ticks_option is an object (value-to-label mapping), extract values
+    if (ticks_option && typeof ticks_option === `object` && !Array.isArray(ticks_option)) {
+        const [domain_min, domain_max] = [Math.min(...domain), Math.max(...domain)];
+        return Object.keys(ticks_option)
+            .map(Number)
+            .filter((val) => Number.isFinite(val) && val >= domain_min && val <= domain_max)
+            .sort((a, b) => a - b);
+    }
+    // If ticks_option is already an array, use it directly
+    if (Array.isArray(ticks_option))
+        return ticks_option;
+    // Time-based ticks (explicit scale_type: 'time' or format heuristic for backwards compatibility)
+    if (is_time_scale(scale_type, format)) {
+        const time_scale = scaleTime().domain([new Date(min_val), new Date(max_val)]);
+        let count = 10; // default
+        if (typeof ticks_option === `number`) {
+            count =
+                ticks_option < 0
+                    ? Math.ceil((max_val - min_val) / Math.abs(ticks_option) / 86_400_000) // milliseconds per day
+                    : ticks_option;
+        }
+        else if (typeof ticks_option === `string`) {
+            count = ticks_option === `day` ? 30 : ticks_option === `month` ? 12 : 10;
+        }
+        const ticks = time_scale.ticks(count);
+        if (typeof ticks_option === `string`) {
+            if (ticks_option === `month`) {
+                return ticks.filter((d) => d.getDate() === 1).map((d) => d.getTime());
+            }
+            if (ticks_option === `year`) {
+                return ticks
+                    .filter((d) => d.getMonth() === 0 && d.getDate() === 1)
+                    .map((d) => d.getTime());
+            }
+        }
+        return ticks.map((d) => d.getTime());
+    }
+    const type_name = get_scale_type_name(scale_type);
+    // Log scale ticks
+    if (type_name === `log`)
+        return generate_log_ticks(min_val, max_val, ticks_option);
+    // Arcsinh scale ticks
+    if (type_name === `arcsinh`) {
+        const threshold = get_arcsinh_threshold(scale_type);
+        const tick_count = typeof ticks_option === `number` && ticks_option > 0 ? ticks_option : default_count;
+        return generate_arcsinh_ticks(min_val, max_val, threshold, tick_count);
+    }
+    // Linear scale with interval (negative number indicates interval)
+    if (typeof ticks_option === `number` && ticks_option < 0) {
+        const interval = Math.abs(ticks_option);
+        const start = Math.ceil(min_val / interval) * interval;
+        return range(start, max_val + interval * interval_padding, interval);
+    }
+    // Default ticks using scale function
+    const tick_count = typeof ticks_option === `number` && ticks_option > 0 ? ticks_option : default_count;
+    const ticks = scale_fn.ticks(tick_count);
+    return ticks.map(Number);
+}
+// Calculate domain from array of values (simple version)
+export function calculate_domain(values, scale_type = `linear`) {
+    const [min_val, max_val] = extent(values);
+    if (min_val === undefined || max_val === undefined)
+        return [0, 1];
+    const type_name = get_scale_type_name(scale_type);
+    // Only log scale needs domain clamping to positive values
+    // Arcsinh and linear can handle any values
+    return type_name === `log` ? [Math.max(min_val, math.LOG_EPS), max_val] : [min_val, max_val];
+}
+// Advanced domain calculation with padding and nice boundaries (from ScatterPlot)
+export function get_nice_data_range(points, get_value, limits, scale_type, padding_factor, is_time = false) {
+    const [min, max] = limits;
+    const [min_ext, max_ext] = extent(points, get_value);
+    let data_min = min ?? min_ext ?? 0;
+    let data_max = max ?? max_ext ?? 1;
+    const type_name = get_scale_type_name(scale_type);
+    // Apply padding *only if* limits were NOT provided
+    if (min === null && max === null && points.length > 0) {
+        if (data_min !== data_max) {
+            // Apply percentage padding based on scale type if there's a range
+            const span = data_max - data_min;
+            if (is_time) {
+                const padding_ms = span * padding_factor;
+                data_min = data_min - padding_ms;
+                data_max = data_max + padding_ms;
+            }
+            else if (type_name === `log`) {
+                const log_min = Math.log10(Math.max(data_min, math.LOG_EPS));
+                const log_max = Math.log10(Math.max(data_max, math.LOG_EPS));
+                const log_span = log_max - log_min;
+                data_min = Math.pow(10, log_min - log_span * padding_factor);
+                data_max = Math.pow(10, log_max + log_span * padding_factor);
+            }
+            else if (type_name === `arcsinh`) {
+                // Arcsinh: apply padding in arcsinh-transformed space
+                // Guard against extremely small thresholds that could cause precision issues
+                const threshold = Math.max(get_arcsinh_threshold(scale_type), Number.EPSILON);
+                const asinh_min = Math.asinh(data_min / threshold);
+                const asinh_max = Math.asinh(data_max / threshold);
+                const asinh_span = asinh_max - asinh_min;
+                data_min = Math.sinh(asinh_min - asinh_span * padding_factor) * threshold;
+                data_max = Math.sinh(asinh_max + asinh_span * padding_factor) * threshold;
+            }
+            else {
+                // Linear scale
+                const padding_abs = span * padding_factor;
+                data_min = data_min - padding_abs;
+                data_max = data_max + padding_abs;
+            }
+        }
+        else {
+            // Handle single data point case with fixed relative padding
+            if (is_time) {
+                const one_day = 86_400_000; // milliseconds in a day
+                data_min = data_min - one_day;
+                data_max = data_max + one_day;
+            }
+            else if (type_name === `log`) {
+                data_min = Math.max(math.LOG_EPS, data_min / 1.1); // 10% multiplicative padding
+                data_max = data_max * 1.1;
+            }
+            else if (type_name === `arcsinh`) {
+                // Arcsinh: 10% padding in transformed space
+                // Guard against extremely small thresholds that could cause precision issues
+                const threshold = Math.max(get_arcsinh_threshold(scale_type), Number.EPSILON);
+                const asinh_val = Math.asinh(data_min / threshold);
+                const padding = Math.abs(asinh_val) * 0.1 || 0.1; // Use 0.1 if transformed value is 0 (i.e. data_min = 0)
+                data_min = Math.sinh(asinh_val - padding) * threshold;
+                data_max = Math.sinh(asinh_val + padding) * threshold;
+            }
+            else {
+                const padding_abs = data_min === 0 ? 1 : Math.abs(data_min * 0.1); // 10% additive padding, or 1 if value is 0
+                data_min = data_min - padding_abs;
+                data_max = data_max + padding_abs;
+            }
+        }
+    }
+    // If time or no range after padding, return the (potentially padded) domain directly
+    if (is_time || data_min === data_max)
+        return [data_min, data_max];
+    // Use D3's nice() to create pretty boundaries
+    // For arcsinh, we don't use D3's nice() - just return padded domain
+    if (type_name === `arcsinh`) {
+        return [data_min, data_max];
+    }
+    // Create the scale with the *padded* data domain
+    const scale = type_name === `log`
+        ? scaleLog().domain([
+            Math.max(data_min, math.LOG_EPS),
+            Math.max(data_max, data_min * 1.1),
+        ]) // Ensure log domain > 0
+        : scaleLinear().domain([data_min, data_max]);
+    scale.nice();
+    const [nice_min = data_min, nice_max = data_max] = scale.domain();
+    return [nice_min, nice_max];
+}
+// Generate logarithmic ticks (from ScatterPlot)
+export function generate_log_ticks(min, max, ticks_option) {
+    // If ticks_option is already an array, use it directly
+    if (Array.isArray(ticks_option))
+        return ticks_option;
+    min = Math.max(min, math.LOG_EPS);
+    // Ensure a strictly increasing domain for tick generation
+    max = Math.max(max, min * 1.1);
+    const min_power = Math.floor(Math.log10(min));
+    const max_power = Math.ceil(Math.log10(max));
+    // For very wide ranges, extend the range to include more ticks
+    const range_size = max_power - min_power;
+    const extended_min_power = range_size <= 2 ? min_power - 1 : min_power - Math.max(1, Math.floor(range_size / 4));
+    const extended_max_power = range_size <= 2 ? max_power + 1 : max_power;
+    const powers = range(extended_min_power, extended_max_power + 1).map((power) => Math.pow(10, power));
+    // For narrow ranges, include intermediate values
+    if (max_power - min_power < 3 && typeof ticks_option === `number` && ticks_option > 5) {
+        const detailed_ticks = [];
+        powers.forEach((power) => {
+            detailed_ticks.push(power);
+            if (power * 2 <= Math.pow(10, extended_max_power))
+                detailed_ticks.push(power * 2);
+            if (power * 5 <= Math.pow(10, extended_max_power))
+                detailed_ticks.push(power * 5);
+        });
+        return detailed_ticks.filter((tick) => tick >= min && tick <= max);
+    }
+    return powers.filter((power) => power >= min && power <= max);
+}
+// Get custom label for a tick value if provided, otherwise return null
+export function get_tick_label(tick_value, ticks_option) {
+    if (ticks_option && typeof ticks_option === `object` && !Array.isArray(ticks_option)) {
+        return ticks_option[tick_value] ?? null;
+    }
+    return null;
+}
+// Create a color scale function from configuration
+export function create_color_scale(color_scale_config, auto_color_range) {
+    const scheme = typeof color_scale_config === `string` ? color_scale_config : color_scale_config.scheme;
+    const candidate_interpolator = Object.entries(d3_sc).find(([key]) => key === scheme)?.[1];
+    const interpolator = typeof candidate_interpolator === `function`
+        ? candidate_interpolator
+        : d3_sc.interpolateViridis;
+    const [min_val, max_val] = (typeof color_scale_config === `string` ? undefined : color_scale_config.value_range) ??
+        auto_color_range;
+    const scale_type = typeof color_scale_config === `string` ? undefined : color_scale_config.type;
+    const type_name = get_scale_type_name(scale_type);
+    if (type_name === `log`) {
+        return scaleSequentialLog(interpolator).domain([
+            Math.max(min_val, math.LOG_EPS),
+            Math.max(max_val, min_val * 1.1),
+        ]);
+    }
+    if (type_name === `arcsinh`) {
+        // For arcsinh color scale, we create a custom scale that wraps the interpolator
+        const threshold = get_arcsinh_threshold(scale_type);
+        return create_arcsinh_color_scale(interpolator, [min_val, max_val], threshold);
+    }
+    return scaleSequential(interpolator).domain([min_val, max_val]);
+}
+// Create an arcsinh-based color scale (custom sequential scale)
+// Returns a D3-compatible scale with both getter and setter for domain
+// Scale function reads from closure state on each call for stable identity
+function create_arcsinh_color_scale(interpolator, initial_domain, threshold) {
+    // Guard against extremely small thresholds that could cause precision issues
+    const safe_threshold = Math.max(threshold, Number.EPSILON);
+    let current_domain = initial_domain;
+    // Single scale function that reads current domain on each call
+    const scale = ((value) => {
+        const [d_min, d_max] = current_domain;
+        // Handle identical domain endpoints - return middle of color range
+        if (d_max === d_min)
+            return interpolator(0.5);
+        const t_min = Math.asinh(d_min / safe_threshold);
+        const t_max = Math.asinh(d_max / safe_threshold);
+        const t_val = Math.asinh(value / safe_threshold);
+        // Normalize to [0, 1]
+        const normalized = t_max === t_min ? 0.5 : (t_val - t_min) / (t_max - t_min);
+        return interpolator(Math.max(0, Math.min(1, normalized)));
+    });
+    // Domain getter/setter for D3 compatibility - returns same scale instance
+    scale.domain = function (new_domain) {
+        if (new_domain === undefined)
+            return current_domain;
+        current_domain = new_domain;
+        return scale;
+    };
+    return scale;
+}
+// Create a size scale function from configuration
+export function create_size_scale(config, all_size_values) {
+    const [min_radius, max_radius] = config.radius_range ?? [2, 10];
+    const auto_range = all_size_values.length > 0
+        ? extent(all_size_values.filter((val) => val !== null))
+        : [0, 1];
+    const [min_val, max_val] = config.value_range ?? auto_range;
+    const safe_min = min_val ?? 0;
+    const safe_max = max_val ?? (safe_min > 0 ? safe_min * 1.1 : 1);
+    const type_name = get_scale_type_name(config.type);
+    if (type_name === `log`) {
+        return scaleLog()
+            .domain([Math.max(safe_min, math.LOG_EPS), Math.max(safe_max, safe_min * 1.1)])
+            .range([min_radius, max_radius])
+            .clamp(true);
+    }
+    if (type_name === `arcsinh`) {
+        // Create arcsinh-based size scale
+        const threshold = get_arcsinh_threshold(config.type);
+        const arcsinh_scale = scale_arcsinh(threshold)
+            .domain([safe_min, safe_max])
+            .range([min_radius, max_radius]);
+        // Wrap with clamping
+        const clamped_scale = ((value) => {
+            const result = arcsinh_scale(value);
+            return Math.max(min_radius, Math.min(max_radius, result));
+        });
+        clamped_scale.domain = () => arcsinh_scale.domain();
+        clamped_scale.range = () => arcsinh_scale.range();
+        return clamped_scale;
+    }
+    return scaleLinear().domain([safe_min, safe_max]).range([min_radius, max_radius]).clamp(true);
+}

package/dist/plot/svg.d.ts

@@ -0,0 +1 @@
+export declare function bar_path(x: number, y: number, w: number, h: number, r: number, vertical?: boolean): string;

package/dist/plot/svg.js

@@ -0,0 +1,11 @@
+// SVG path and rendering utilities for plot components.
+//
+// Generate SVG path for a bar with rounded corners on the "free" end (away from axis).
+// For vertical bars, rounds top corners. For horizontal bars, rounds right corners.
+export function bar_path(x, y, w, h, r, vertical = true) {
+    if (r <= 0)
+        return `M${x},${y}h${w}v${h}h${-w}Z`;
+    return vertical
+        ? `M${x},${y + h}V${y + r}A${r},${r} 0 0 1 ${x + r},${y}H${x + w - r}A${r},${r} 0 0 1 ${x + w},${y + r}V${y + h}Z`
+        : `M${x},${y}H${x + w - r}A${r},${r} 0 0 1 ${x + w},${y + r}V${y + h - r}A${r},${r} 0 0 1 ${x + w - r},${y + h}H${x}Z`;
+}