matterviz 0.3.4 → 0.3.6

package/dist/plot/data-cleaning.js

@@ -1,855 +0,0 @@
-// Data cleaning utilities for plot data
-// Detects oscillations, enforces physical bounds, and handles multi-dimensional datasets
-import { apply_gaussian_smearing } from '../spectral/helpers';
-// Default configuration values
-const DEFAULT_WINDOW_SIZE = 5;
-const DEFAULT_OSCILLATION_THRESHOLD = 3.0;
-const DEFAULT_POLYNOMIAL_ORDER = 2;
-// --- Core Detection Functions ---
-// Compute rolling variance using Welford's online algorithm - O(n)
-// Returns variance for each point based on surrounding window
-export function compute_local_variance(values, window_size) {
-    const len = values.length;
-    if (len === 0)
-        return [];
-    if (len === 1)
-        return [0];
-    const half_window = Math.floor(window_size / 2);
-    const result = new Array(len);
-    // Single pass for each index, no slice allocation (avoids O(n × window) allocations)
-    for (let idx = 0; idx < len; idx++) {
-        const start = Math.max(0, idx - half_window);
-        const end = Math.min(len, idx + half_window + 1);
-        // Welford's online variance calculation
-        let [mean, m2, count] = [0, 0, 0];
-        for (let jdx = start; jdx < end; jdx++) {
-            const val = values[jdx];
-            if (!Number.isFinite(val))
-                continue;
-            count++;
-            const delta = val - mean;
-            mean += delta / count;
-            const delta2 = val - mean;
-            m2 += delta * delta2;
-        }
-        result[idx] = count > 1 ? m2 / (count - 1) : 0;
-    }
-    return result;
-}
-// Compute first-order finite differences (discrete derivative)
-function compute_derivatives(values) {
-    if (values.length < 2)
-        return [];
-    const derivs = new Array(values.length - 1);
-    for (let idx = 0; idx < values.length - 1; idx++) {
-        derivs[idx] = values[idx + 1] - values[idx];
-    }
-    return derivs;
-}
-// Detect derivative variance spikes (method 1)
-// Returns onset index where derivative variance exceeds threshold
-function detect_derivative_variance(values, window_size, threshold_multiplier) {
-    const derivs = compute_derivatives(values);
-    if (derivs.length < window_size) {
-        return { onset_index: -1, score: 0 };
-    }
-    const local_var = compute_local_variance(derivs, window_size);
-    // Compute baseline variance from first stable portion
-    const baseline_end = Math.min(Math.floor(derivs.length / 4), 50);
-    const baseline_vars = local_var.slice(0, Math.max(baseline_end, window_size));
-    const baseline_median = median(baseline_vars.filter((val) => val > 0));
-    if (baseline_median === 0) {
-        return { onset_index: -1, score: 0 };
-    }
-    // Find first point where variance exceeds threshold
-    let max_score = 0;
-    for (let idx = baseline_end; idx < local_var.length; idx++) {
-        const ratio = local_var[idx] / baseline_median;
-        if (ratio > max_score)
-            max_score = ratio;
-        if (ratio > threshold_multiplier) {
-            return { onset_index: idx + 1, score: ratio }; // +1 to convert from deriv index to value index
-        }
-    }
-    return { onset_index: -1, score: max_score };
-}
-// Detect exponential amplitude growth (method 2)
-// Looks for values growing exponentially from their mean
-function detect_amplitude_growth(values, window_size) {
-    if (values.length < window_size * 3) {
-        return { onset_index: -1, score: 0 };
-    }
-    // Compute running amplitude (deviation from local mean)
-    const amplitudes = [];
-    const half_window = Math.floor(window_size / 2);
-    for (let idx = half_window; idx < values.length - half_window; idx++) {
-        const start = idx - half_window;
-        const end = idx + half_window + 1;
-        const window_len = end - start;
-        // Compute local mean without slice allocation
-        let sum = 0;
-        for (let jdx = start; jdx < end; jdx++)
-            sum += values[jdx];
-        const local_mean = sum / window_len;
-        // Find max deviation without slice allocation
-        let max_deviation = 0;
-        for (let jdx = start; jdx < end; jdx++) {
-            const deviation = Math.abs(values[jdx] - local_mean);
-            if (deviation > max_deviation)
-                max_deviation = deviation;
-        }
-        amplitudes.push(max_deviation);
-    }
-    if (amplitudes.length < 10) {
-        return { onset_index: -1, score: 0 };
-    }
-    // Detect exponential growth by checking if amplitude ratio increases
-    const baseline_amp = median(amplitudes.slice(0, Math.floor(amplitudes.length / 4)));
-    if (baseline_amp === 0) {
-        return { onset_index: -1, score: 0 };
-    }
-    let max_score = 0;
-    for (let idx = Math.floor(amplitudes.length / 4); idx < amplitudes.length; idx++) {
-        const ratio = amplitudes[idx] / baseline_amp;
-        if (ratio > max_score)
-            max_score = ratio;
-        // Exponential growth threshold: amplitude 10x baseline
-        if (ratio > 10) {
-            return { onset_index: idx + half_window, score: ratio / 10 };
-        }
-    }
-    return { onset_index: -1, score: max_score / 10 };
-}
-// Count derivative sign changes per window (method 3)
-// Detects high-frequency oscillations
-function detect_sign_change_frequency(values, window_size, max_changes_per_window = 3) {
-    const derivs = compute_derivatives(values);
-    if (derivs.length < window_size * 2) {
-        return { onset_index: -1, score: 0 };
-    }
-    // Count sign changes in sliding windows
-    const half_window = Math.floor(window_size / 2);
-    let max_score = 0;
-    for (let idx = half_window; idx < derivs.length - half_window; idx++) {
-        const start = idx - half_window;
-        const end = idx + half_window + 1;
-        let sign_changes = 0;
-        // Count sign changes without slice allocation
-        for (let jdx = start + 1; jdx < end; jdx++) {
-            if (derivs[jdx] * derivs[jdx - 1] < 0) {
-                sign_changes++;
-            }
-        }
-        const normalized_score = sign_changes / max_changes_per_window;
-        if (normalized_score > max_score)
-            max_score = normalized_score;
-        if (sign_changes > max_changes_per_window) {
-            return { onset_index: idx + 1, score: normalized_score };
-        }
-    }
-    return { onset_index: -1, score: max_score };
-}
-// Combined detection with configurable weights
-export function detect_instability(x_values, y_values, config = {}) {
-    const window_size = config.window_size ?? DEFAULT_WINDOW_SIZE;
-    const threshold = config.oscillation_threshold ?? DEFAULT_OSCILLATION_THRESHOLD;
-    const weights = {
-        derivative_variance: config.oscillation_weights?.derivative_variance ?? 1.0,
-        amplitude_growth: config.oscillation_weights?.amplitude_growth ?? 1.0,
-        sign_changes: config.oscillation_weights?.sign_changes ?? 1.0,
-    };
-    // Filter out invalid values for detection
-    const valid_indices = [];
-    const valid_y = [];
-    for (let idx = 0; idx < y_values.length; idx++) {
-        if (Number.isFinite(y_values[idx])) {
-            valid_indices.push(idx);
-            valid_y.push(y_values[idx]);
-        }
-    }
-    if (valid_y.length < window_size * 2) {
-        const method_scores = { derivative_variance: 0, amplitude_growth: 0, sign_changes: 0 };
-        const detected = false;
-        return { detected, onset_index: -1, onset_x: NaN, combined_score: 0, method_scores };
-    }
-    // Run all three detection methods
-    const deriv_result = detect_derivative_variance(valid_y, window_size, threshold);
-    const amp_result = detect_amplitude_growth(valid_y, window_size);
-    const sign_result = detect_sign_change_frequency(valid_y, window_size);
-    const method_scores = {
-        derivative_variance: deriv_result.score,
-        amplitude_growth: amp_result.score,
-        sign_changes: sign_result.score,
-    };
-    // Compute weighted combined score
-    const total_weight = weights.derivative_variance + weights.amplitude_growth + weights.sign_changes;
-    const combined_score = total_weight > 0
-        ? (weights.derivative_variance * deriv_result.score +
-            weights.amplitude_growth * amp_result.score +
-            weights.sign_changes * sign_result.score) /
-            total_weight
-        : 0;
-    // Find earliest onset across all methods that exceeded threshold
-    const onset_candidates = [
-        {
-            idx: deriv_result.onset_index,
-            score: deriv_result.score * weights.derivative_variance,
-        },
-        { idx: amp_result.onset_index, score: amp_result.score * weights.amplitude_growth },
-        { idx: sign_result.onset_index, score: sign_result.score * weights.sign_changes },
-    ].filter((candidate) => candidate.idx >= 0);
-    let onset_index = -1;
-    if (onset_candidates.length > 0) {
-        // Take earliest detected onset
-        onset_index = Math.min(...onset_candidates.map((candidate) => candidate.idx));
-        // Map back to original index if we filtered values
-        if (onset_index >= 0 && onset_index < valid_indices.length) {
-            onset_index = valid_indices[onset_index];
-        }
-    }
-    const detected = combined_score >= threshold || onset_index >= 0;
-    const onset_x = onset_index >= 0 && onset_index < x_values.length ? x_values[onset_index] : NaN;
-    return { detected, onset_index, onset_x, combined_score, method_scores };
-}
-// --- Smoothing Functions ---
-// Moving average - O(n)
-export function smooth_moving_average(values, window) {
-    if (values.length === 0 || window <= 1)
-        return [...values];
-    const result = new Array(values.length);
-    const half_window = Math.floor(window / 2);
-    for (let idx = 0; idx < values.length; idx++) {
-        const start = Math.max(0, idx - half_window);
-        const end = Math.min(values.length, idx + half_window + 1);
-        let [sum, count] = [0, 0];
-        for (let jdx = start; jdx < end; jdx++) {
-            if (Number.isFinite(values[jdx])) {
-                sum += values[jdx];
-                count++;
-            }
-        }
-        result[idx] = count > 0 ? sum / count : values[idx];
-    }
-    return result;
-}
-// Savitzky-Golay filter coefficients for polynomial smoothing
-// Uses least-squares polynomial fitting in each window
-function compute_savgol_coefficients(window, order) {
-    // Ensure window is odd
-    const half = Math.floor(window / 2);
-    const size = 2 * half + 1;
-    // Build Vandermonde matrix for polynomial fitting
-    const vandermonde = [];
-    for (let idx = -half; idx <= half; idx++) {
-        const row = [];
-        for (let power = 0; power <= order; power++) {
-            row.push(Math.pow(idx, power));
-        }
-        vandermonde.push(row);
-    }
-    // Compute (V^T V)^-1 V^T using simple pseudoinverse
-    // For smoothing, we only need the first row (constant term coefficients)
-    const vtv = multiply_matrices(transpose(vandermonde), vandermonde);
-    const vtv_inv = invert_matrix(vtv);
-    if (!vtv_inv) {
-        // Fallback to uniform weights
-        return new Array(size).fill(1 / size);
-    }
-    const vt = transpose(vandermonde);
-    const coeffs_matrix = multiply_matrices(vtv_inv, vt);
-    // First row gives smoothing coefficients
-    return coeffs_matrix[0];
-}
-// Savitzky-Golay filter (derivative-preserving) - O(n * window)
-export function smooth_savitzky_golay(values, window, polynomial_order = DEFAULT_POLYNOMIAL_ORDER) {
-    if (values.length === 0)
-        return [];
-    // Ensure window is odd and >= polynomial_order + 1
-    let actual_window = window % 2 === 0 ? window + 1 : window;
-    actual_window = Math.max(actual_window, polynomial_order + 2);
-    actual_window = Math.min(actual_window, values.length);
-    if (actual_window < 3)
-        return [...values];
-    const coeffs = compute_savgol_coefficients(actual_window, polynomial_order);
-    const half = Math.floor(actual_window / 2);
-    const result = new Array(values.length);
-    // Cache coefficient sum to avoid O(n × window) redundant reductions in loop
-    const coeffs_sum = coeffs.reduce((a, b) => a + b, 0);
-    for (let idx = 0; idx < values.length; idx++) {
-        let [sum, weight_sum] = [0, 0];
-        for (let jdx = 0; jdx < actual_window; jdx++) {
-            const data_idx = idx - half + jdx;
-            if (data_idx >= 0 && data_idx < values.length && Number.isFinite(values[data_idx])) {
-                sum += coeffs[jdx] * values[data_idx];
-                weight_sum += coeffs[jdx];
-            }
-        }
-        result[idx] = weight_sum !== 0 ? (sum / weight_sum) * coeffs_sum : values[idx];
-    }
-    return result;
-}
-// Apply smoothing based on config
-function apply_smoothing(x_values, y_values, config) {
-    if (config.type === `moving_avg`) {
-        return smooth_moving_average(y_values, config.window);
-    }
-    else if (config.type === `savgol`) {
-        return smooth_savitzky_golay(y_values, config.window, config.polynomial_order ?? DEFAULT_POLYNOMIAL_ORDER);
-    }
-    else if (config.type === `gaussian`) {
-        return apply_gaussian_smearing(x_values, y_values, config.sigma);
-    }
-    return y_values;
-}
-// --- Local Outlier Detection ---
-// Default values for local outlier detection
-const DEFAULT_LOCAL_WINDOW_HALF = 7;
-const DEFAULT_LOCAL_MAD_THRESHOLD = 2.0;
-const DEFAULT_LOCAL_MAX_ITERATIONS = 5;
-// Compute local median within a window, excluding the center point
-// This allows detecting if the center point is an outlier relative to its neighbors
-function compute_local_median_excluding_center(values, center_idx, window_half) {
-    const window_values = [];
-    const start = Math.max(0, center_idx - window_half);
-    const end = Math.min(values.length - 1, center_idx + window_half);
-    for (let idx = start; idx <= end; idx++) {
-        if (idx !== center_idx && Number.isFinite(values[idx])) {
-            window_values.push(values[idx]);
-        }
-    }
-    if (window_values.length === 0)
-        return values[center_idx];
-    return median(window_values);
-}
-// Compute local MAD (median absolute deviation) within a window, excluding center
-function compute_local_mad_excluding_center(values, center_idx, window_half, local_median) {
-    const abs_devs = [];
-    const start = Math.max(0, center_idx - window_half);
-    const end = Math.min(values.length - 1, center_idx + window_half);
-    for (let idx = start; idx <= end; idx++) {
-        if (idx !== center_idx && Number.isFinite(values[idx])) {
-            abs_devs.push(Math.abs(values[idx] - local_median));
-        }
-    }
-    if (abs_devs.length === 0)
-        return 0;
-    return median(abs_devs);
-}
-// Remove local outliers using iterative sliding window MAD-based detection
-// Detects points that deviate significantly from their local neighborhood
-// Returns only the indices to keep, preserving good data before AND after bad regions
-export function remove_local_outliers(y_values, config = {}) {
-    const window_half = config.window_half ?? DEFAULT_LOCAL_WINDOW_HALF;
-    const mad_threshold = config.mad_threshold ?? DEFAULT_LOCAL_MAD_THRESHOLD;
-    const max_iterations = config.max_iterations ?? DEFAULT_LOCAL_MAX_ITERATIONS;
-    const len = y_values.length;
-    if (len === 0) {
-        return { kept_indices: [], removed_indices: [], iterations_used: 0 };
-    }
-    // Need enough neighbors for meaningful local statistics
-    const min_points_needed = window_half * 2 + 1;
-    if (len < min_points_needed) {
-        return {
-            kept_indices: Array.from({ length: len }, (_, idx) => idx),
-            removed_indices: [],
-            iterations_used: 0,
-        };
-    }
-    let kept_mask = new Array(len).fill(true);
-    let iterations_used = 0;
-    for (let iter = 0; iter < max_iterations; iter++) {
-        let removed_any = false;
-        const new_kept_mask = [...kept_mask];
-        // Note: Local statistics are computed from original values, not filtered values.
-        // This prevents cascading removals where one outlier's removal dramatically
-        // shifts statistics and causes false positives on neighboring points.
-        for (let idx = 0; idx < len; idx++) {
-            if (!kept_mask[idx])
-                continue; // Already removed
-            if (!Number.isFinite(y_values[idx]))
-                continue; // Skip invalid values
-            const local_median = compute_local_median_excluding_center(y_values, idx, window_half);
-            const local_mad = compute_local_mad_excluding_center(y_values, idx, window_half, local_median);
-            // Cannot compute robust threshold if MAD is zero (all neighbors identical)
-            if (local_mad === 0)
-                continue;
-            const threshold = local_mad * mad_threshold;
-            const deviation = Math.abs(y_values[idx] - local_median);
-            if (deviation > threshold) {
-                new_kept_mask[idx] = false;
-                removed_any = true;
-            }
-        }
-        kept_mask = new_kept_mask;
-        iterations_used = iter + 1;
-        if (!removed_any)
-            break;
-    }
-    const kept_indices = [];
-    const removed_indices = [];
-    for (let idx = 0; idx < len; idx++) {
-        if (kept_mask[idx]) {
-            kept_indices.push(idx);
-        }
-        else {
-            removed_indices.push(idx);
-        }
-    }
-    return { kept_indices, removed_indices, iterations_used };
-}
-// --- Helper Functions ---
-// Handle NaN/Infinity based on mode
-export function handle_invalid_values(values, mode) {
-    const removed_indices = [];
-    let invalid_count = 0;
-    if (mode === `propagate`) {
-        for (const val of values) {
-            if (!Number.isFinite(val))
-                invalid_count++;
-        }
-        return { cleaned: [...values], removed_indices: [], invalid_count };
-    }
-    if (mode === `remove`) {
-        const cleaned = [];
-        for (let idx = 0; idx < values.length; idx++) {
-            if (Number.isFinite(values[idx])) {
-                cleaned.push(values[idx]);
-            }
-            else {
-                removed_indices.push(idx);
-                invalid_count++;
-            }
-        }
-        return { cleaned, removed_indices, invalid_count };
-    }
-    // Interpolate mode
-    const cleaned = [...values];
-    for (let idx = 0; idx < cleaned.length; idx++) {
-        if (!Number.isFinite(cleaned[idx])) {
-            invalid_count++;
-            // Find nearest valid neighbors
-            let left_idx = idx - 1;
-            while (left_idx >= 0 && !Number.isFinite(cleaned[left_idx]))
-                left_idx--;
-            let right_idx = idx + 1;
-            while (right_idx < cleaned.length && !Number.isFinite(cleaned[right_idx])) {
-                right_idx++;
-            }
-            if (left_idx >= 0 && right_idx < cleaned.length) {
-                // Linear interpolation
-                const t = (idx - left_idx) / (right_idx - left_idx);
-                cleaned[idx] = cleaned[left_idx] + t * (cleaned[right_idx] - cleaned[left_idx]);
-            }
-            else if (left_idx >= 0) {
-                cleaned[idx] = cleaned[left_idx];
-            }
-            else if (right_idx < cleaned.length) {
-                cleaned[idx] = cleaned[right_idx];
-            }
-            else {
-                cleaned[idx] = 0;
-            }
-        }
-    }
-    return { cleaned, removed_indices: [], invalid_count };
-}
-// Apply physical bounds
-export function apply_bounds(x_values, y_values, bounds) {
-    const result = [...y_values];
-    const filtered_indices = [];
-    let violations = 0;
-    for (let idx = 0; idx < result.length; idx++) {
-        const x_val = x_values[idx];
-        const y_val = result[idx];
-        const min_bound = typeof bounds.min === `function` ? bounds.min(x_val) : bounds.min;
-        const max_bound = typeof bounds.max === `function` ? bounds.max(x_val) : bounds.max;
-        let violated = false;
-        if (min_bound !== undefined && y_val < min_bound)
-            violated = true;
-        if (max_bound !== undefined && y_val > max_bound)
-            violated = true;
-        if (violated) {
-            violations++;
-            const mode = bounds.mode ?? `clamp`;
-            if (mode === `clamp`) {
-                if (min_bound !== undefined && y_val < min_bound)
-                    result[idx] = min_bound;
-                if (max_bound !== undefined && y_val > max_bound)
-                    result[idx] = max_bound;
-            }
-            else if (mode === `filter`) {
-                filtered_indices.push(idx);
-            }
-            else if (mode === `null`) {
-                result[idx] = NaN;
-            }
-        }
-    }
-    return { y: result, violations, filtered_indices };
-}
-// Sync metadata arrays with filtered data
-export function sync_metadata(metadata, kept_indices) {
-    if (metadata === undefined)
-        return undefined;
-    if (!Array.isArray(metadata))
-        return metadata; // Scalar metadata unchanged
-    return kept_indices.map((idx) => metadata[idx]);
-}
-// Filter arrays by kept indices
-function filter_by_indices(arr, kept_indices) {
-    return kept_indices.map((idx) => arr[idx]);
-}
-// Check if value is within bounds (static or x-dependent)
-function is_in_bounds(val, x_val, bounds) {
-    const min = typeof bounds.min === `function` ? bounds.min(x_val) : bounds.min;
-    const max = typeof bounds.max === `function` ? bounds.max(x_val) : bounds.max;
-    if (min !== undefined && val < min)
-        return false;
-    if (max !== undefined && val > max)
-        return false;
-    return true;
-}
-// Compute kept indices by excluding removed indices
-function kept_indices_excluding(length, removed) {
-    const removed_set = new Set(removed);
-    return Array.from({ length }, (_, idx) => idx).filter((idx) => !removed_set.has(idx));
-}
-// --- Main API ---
-// Clean a single series - main entry point
-export function clean_series(series, config = {}) {
-    const in_place = config.in_place ?? true;
-    const invalid_mode = config.invalid_values ?? `remove`;
-    const truncation_mode = config.truncation_mode ?? `mark_unstable`;
-    // Always work with copies initially
-    let x_arr = [...series.x];
-    let y_arr = [...series.y];
-    let metadata = series.metadata;
-    let color_values = series.color_values ? [...series.color_values] : undefined;
-    let size_values = series.size_values ? [...series.size_values] : undefined;
-    const quality = {
-        points_removed: 0,
-        invalid_values_found: 0,
-        oscillation_detected: false,
-        bounds_violations: 0,
-    };
-    // Helper to apply filtering to all arrays
-    const apply_filter = (kept, removed_count) => {
-        x_arr = filter_by_indices(x_arr, kept);
-        y_arr = filter_by_indices(y_arr, kept);
-        if (Array.isArray(metadata)) {
-            metadata = filter_by_indices(metadata, kept);
-        }
-        if (color_values)
-            color_values = filter_by_indices(color_values, kept);
-        if (size_values)
-            size_values = filter_by_indices(size_values, kept);
-        quality.points_removed += removed_count;
-    };
-    // Step 1: Handle invalid values
-    const invalid_result = handle_invalid_values(y_arr, invalid_mode);
-    quality.invalid_values_found = invalid_result.invalid_count;
-    if (invalid_mode === `remove` && invalid_result.removed_indices.length > 0) {
-        const kept = kept_indices_excluding(x_arr.length, invalid_result.removed_indices);
-        apply_filter(kept, invalid_result.removed_indices.length);
-    }
-    else {
-        y_arr = invalid_result.cleaned;
-    }
-    // Step 2: Apply physical bounds
-    if (config.bounds) {
-        const bounds_result = apply_bounds(x_arr, y_arr, config.bounds);
-        y_arr = bounds_result.y;
-        quality.bounds_violations = bounds_result.violations;
-        if (config.bounds.mode === `filter` && bounds_result.filtered_indices.length > 0) {
-            const kept = kept_indices_excluding(x_arr.length, bounds_result.filtered_indices);
-            apply_filter(kept, bounds_result.filtered_indices.length);
-        }
-    }
-    // Step 3: Remove local outliers (if configured)
-    if (config.local_outliers) {
-        const outlier_result = remove_local_outliers(y_arr, config.local_outliers);
-        quality.outliers_removed = outlier_result.removed_indices.length;
-        if (outlier_result.removed_indices.length > 0) {
-            apply_filter(outlier_result.kept_indices, outlier_result.removed_indices.length);
-        }
-    }
-    // Step 4: Apply smoothing
-    if (config.smooth) {
-        y_arr = apply_smoothing(x_arr, y_arr, config.smooth);
-    }
-    // Step 5: Detect instability
-    const instability = detect_instability(x_arr, y_arr, config);
-    quality.oscillation_detected = instability.detected;
-    quality.oscillation_score = instability.combined_score;
-    if (instability.detected && instability.onset_index >= 0) {
-        if (truncation_mode === `hard_cut`) {
-            const kept = Array.from({ length: instability.onset_index }, (_, idx) => idx);
-            quality.truncated_at_x = instability.onset_x;
-            apply_filter(kept, x_arr.length - instability.onset_index);
-        }
-        else {
-            quality.stable_range = [x_arr[0], instability.onset_x];
-        }
-    }
-    // Build result series
-    const result_series = (in_place ? series : { ...series });
-    result_series.x = x_arr;
-    result_series.y = y_arr;
-    if (metadata !== undefined)
-        result_series.metadata = metadata;
-    if (color_values)
-        result_series.color_values = color_values;
-    if (size_values)
-        result_series.size_values = size_values;
-    return { series: result_series, quality };
-}
-// Clean multiple y-series with shared x, filtering to intersection of valid indices
-export function clean_multi_series(x_values, y_arrays, config = {}) {
-    if (y_arrays.length === 0) {
-        return { x: [...x_values], cleaned_y: [], quality: [] };
-    }
-    const invalid_mode = config.invalid_values ?? `remove`;
-    const length = Math.min(x_values.length, ...y_arrays.map((arr) => arr.length));
-    const { bounds, smooth } = config;
-    // Find indices valid across ALL y series (remove mode filters invalid values)
-    let kept_indices = Array.from({ length }, (_, idx) => idx);
-    if (invalid_mode === `remove`) {
-        kept_indices = kept_indices.filter((idx) => y_arrays.every((y_arr) => Number.isFinite(y_arr[idx])));
-    }
-    // Apply bounds filter across all series
-    if (bounds?.mode === `filter`) {
-        kept_indices = kept_indices.filter((idx) => {
-            const x_val = x_values[idx];
-            return y_arrays.every((y_arr) => is_in_bounds(y_arr[idx], x_val, bounds));
-        });
-    }
-    const filtered_x = kept_indices.map((idx) => x_values[idx]);
-    const cleaned_y = [];
-    const quality_reports = [];
-    for (const y_arr of y_arrays) {
-        let filtered_y = kept_indices.map((idx) => y_arr[idx]);
-        // Count invalid values only in aligned prefix (not beyond length)
-        let invalid_count = 0;
-        for (let idx = 0; idx < length; idx++) {
-            if (!Number.isFinite(y_arr[idx]))
-                invalid_count++;
-        }
-        const quality = {
-            points_removed: length - kept_indices.length,
-            invalid_values_found: invalid_count,
-            oscillation_detected: false,
-            bounds_violations: 0,
-        };
-        if (invalid_mode === `interpolate`) {
-            filtered_y = handle_invalid_values(filtered_y, `interpolate`).cleaned;
-        }
-        if (bounds && bounds.mode !== `filter`) {
-            const result = apply_bounds(filtered_x, filtered_y, bounds);
-            filtered_y = result.y;
-            quality.bounds_violations = result.violations;
-        }
-        if (smooth) {
-            filtered_y = apply_smoothing(filtered_x, filtered_y, smooth);
-        }
-        cleaned_y.push(filtered_y);
-        quality_reports.push(quality);
-    }
-    return { x: filtered_x, cleaned_y, quality: quality_reports };
-}
-// Clean correlated x/y/z for 3D data
-// All three arrays are filtered to the intersection of valid indices
-export function clean_xyz(x_values, y_values, z_values, config = {}) {
-    const invalid_mode = config.invalid_values ?? `remove`;
-    const length = Math.min(x_values.length, y_values.length, z_values.length);
-    const all_arrays = [x_values, y_values, z_values];
-    const { bounds, smooth } = config;
-    // Count invalid values across all arrays
-    let invalid_count = 0;
-    for (let idx = 0; idx < length; idx++) {
-        if (!all_arrays.every((arr) => Number.isFinite(arr[idx])))
-            invalid_count++;
-    }
-    // Find indices where ALL values are valid (remove mode filters)
-    let kept_indices = Array.from({ length }, (_, idx) => idx);
-    if (invalid_mode === `remove`) {
-        kept_indices = kept_indices.filter((idx) => all_arrays.every((arr) => Number.isFinite(arr[idx])));
-    }
-    let filtered = {
-        x: kept_indices.map((idx) => x_values[idx]),
-        y: kept_indices.map((idx) => y_values[idx]),
-        z: kept_indices.map((idx) => z_values[idx]),
-    };
-    const quality = {
-        points_removed: length - kept_indices.length,
-        invalid_values_found: invalid_count,
-        oscillation_detected: false,
-        bounds_violations: 0,
-    };
-    if (invalid_mode === `interpolate`) {
-        filtered.x = handle_invalid_values(filtered.x, `interpolate`).cleaned;
-        filtered.y = handle_invalid_values(filtered.y, `interpolate`).cleaned;
-        filtered.z = handle_invalid_values(filtered.z, `interpolate`).cleaned;
-    }
-    // Apply bounds filter on primary axis
-    if (bounds?.mode === `filter`) {
-        const primary = config.primary_axis ?? `x`;
-        const bounds_kept = [];
-        for (let idx = 0; idx < filtered.x.length; idx++) {
-            const primary_val = filtered[primary][idx];
-            // Use x-axis value for dynamic bounds computation (e.g., max: (x) => x * 2)
-            if (is_in_bounds(primary_val, filtered.x[idx], bounds)) {
-                bounds_kept.push(idx);
-            }
-            else {
-                quality.bounds_violations++;
-            }
-        }
-        filtered = {
-            x: bounds_kept.map((idx) => filtered.x[idx]),
-            y: bounds_kept.map((idx) => filtered.y[idx]),
-            z: bounds_kept.map((idx) => filtered.z[idx]),
-        };
-        quality.points_removed += kept_indices.length - bounds_kept.length;
-    }
-    // Smooth dependent axes (y, z) using x as independent reference
-    // x-axis is never smoothed as it's typically the independent variable (time, index, etc.)
-    if (smooth) {
-        filtered.y = apply_smoothing(filtered.x, filtered.y, smooth);
-        filtered.z = apply_smoothing(filtered.x, filtered.z, smooth);
-    }
-    return { ...filtered, quality };
-}
-// Clean trajectory properties, filtering to intersection of valid indices
-export function clean_trajectory_props(props, config = {}) {
-    const entries = Object.entries(props);
-    if (entries.length === 0) {
-        return { props: {}, quality: {} };
-    }
-    const independent_axis = config.independent_axis ?? `Step`;
-    const invalid_mode = config.invalid_values ?? `remove`;
-    const { smooth } = config;
-    const length = Math.min(...entries.map(([, arr]) => arr.length));
-    // Use existing or generate independent axis
-    const x_values = props[independent_axis] ?? Array.from({ length }, (_, idx) => idx);
-    // Count invalid values per property (only within aligned prefix)
-    const invalid_counts = Object.fromEntries(entries.map(([key, arr]) => {
-        let count = 0;
-        for (let idx = 0; idx < length; idx++) {
-            if (!Number.isFinite(arr[idx]))
-                count++;
-        }
-        return [key, count];
-    }));
-    // Find indices valid across ALL properties (remove mode filters)
-    let kept_indices = Array.from({ length }, (_, idx) => idx);
-    if (invalid_mode === `remove`) {
-        kept_indices = kept_indices.filter((idx) => entries.every(([, arr]) => Number.isFinite(arr[idx])));
-    }
-    const filtered_x = kept_indices.map((idx) => x_values[idx]);
-    const result_props = {};
-    const quality_reports = {};
-    for (const [key, arr] of entries) {
-        let filtered = kept_indices.map((idx) => arr[idx]);
-        const quality = {
-            points_removed: length - kept_indices.length,
-            invalid_values_found: invalid_counts[key],
-            oscillation_detected: false,
-            bounds_violations: 0,
-        };
-        if (invalid_mode === `interpolate`) {
-            filtered = handle_invalid_values(filtered, `interpolate`).cleaned;
-        }
-        if (smooth && key !== independent_axis) {
-            filtered = apply_smoothing(filtered_x, filtered, smooth);
-        }
-        result_props[key] = filtered;
-        quality_reports[key] = quality;
-    }
-    // Add independent axis if not in original props
-    if (!props[independent_axis]) {
-        result_props[independent_axis] = filtered_x;
-        quality_reports[independent_axis] = {
-            points_removed: length - kept_indices.length,
-            invalid_values_found: 0,
-            oscillation_detected: false,
-            bounds_violations: 0,
-        };
-    }
-    return { props: result_props, quality: quality_reports };
-}
-// --- Utility Functions ---
-function median(values) {
-    if (values.length === 0)
-        return 0;
-    const sorted = [...values].sort((a, b) => a - b);
-    const mid = Math.floor(sorted.length / 2);
-    return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
-}
-// Simple matrix operations for Savitzky-Golay
-function transpose(matrix) {
-    if (matrix.length === 0)
-        return [];
-    const rows = matrix.length;
-    const cols = matrix[0].length;
-    const result = Array.from({ length: cols }, () => new Array(rows));
-    for (let row = 0; row < rows; row++) {
-        for (let col = 0; col < cols; col++) {
-            result[col][row] = matrix[row][col];
-        }
-    }
-    return result;
-}
-function multiply_matrices(a, b) {
-    const rows_a = a.length;
-    const cols_a = a[0]?.length ?? 0;
-    const cols_b = b[0]?.length ?? 0;
-    const result = Array.from({ length: rows_a }, () => new Array(cols_b).fill(0));
-    for (let row = 0; row < rows_a; row++) {
-        for (let col = 0; col < cols_b; col++) {
-            for (let k = 0; k < cols_a; k++) {
-                result[row][col] += a[row][k] * b[k][col];
-            }
-        }
-    }
-    return result;
-}
-function invert_matrix(matrix) {
-    const n = matrix.length;
-    if (n === 0 || matrix[0].length !== n)
-        return null;
-    // Create augmented matrix [A | I]
-    const aug = matrix.map((row, idx) => [
-        ...row,
-        ...Array.from({ length: n }, (_, jdx) => (idx === jdx ? 1 : 0)),
-    ]);
-    // Gaussian elimination with partial pivoting
-    for (let col = 0; col < n; col++) {
-        // Find pivot
-        let max_row = col;
-        for (let row = col + 1; row < n; row++) {
-            if (Math.abs(aug[row][col]) > Math.abs(aug[max_row][col])) {
-                max_row = row;
-            }
-        }
-        if (Math.abs(aug[max_row][col]) < 1e-10) {
-            return null; // Singular
-        } // Swap rows
-        ;
-        [aug[col], aug[max_row]] = [aug[max_row], aug[col]];
-        // Eliminate column
-        const pivot = aug[col][col];
-        for (let jdx = 0; jdx < 2 * n; jdx++) {
-            aug[col][jdx] /= pivot;
-        }
-        for (let row = 0; row < n; row++) {
-            if (row !== col) {
-                const factor = aug[row][col];
-                for (let jdx = 0; jdx < 2 * n; jdx++) {
-                    aug[row][jdx] -= factor * aug[col][jdx];
-                }
-            }
-        }
-    }
-    // Extract inverse
-    return aug.map((row) => row.slice(n));
-}