matterviz 0.3.6 → 0.3.7

package/dist/plot/data-cleaning.js

@@ -0,0 +1,855 @@
+// 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 = 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 = 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 = 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 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 = 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 = 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_val) => x_val * 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 }, () => Array(rows).fill(0));
+    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 }, () => 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));
+}