matterviz 0.3.7 → 0.4.0

package/dist/plot/sunburst/sunburst.js

@@ -0,0 +1,266 @@
+// Layout helpers for Sunburst charts, wrapping d3-hierarchy's partition.
+// Single source of truth for the hierarchy/angle math so the component stays
+// declarative and the layout is independently unit-testable. The partition is
+// computed in normalized coordinates (angle as fraction of full circle in [0, 1],
+// radius in integer ring units where y0 === depth) independent of pixel size and
+// zoom — the component maps these to screen space per frame (zoomable-sunburst trick).
+import { hsl } from 'd3-color';
+import { hierarchy, partition } from 'd3-hierarchy';
+import { DEFAULT_SERIES_COLORS } from '../core/types';
+// Compute normalized arc extents, resolved colors and breadcrumbs for a node tree.
+// Never mutates user data: d3-hierarchy wraps inputs in HierarchyNodes and all derived
+// fields (value overrides, ids, colors) are written onto the returned arcs only.
+export function compute_sunburst_layout(data, opts = {}) {
+    const { value_mode = `leaf-sum`, sort = `none`, level_lighten = 0, min_fraction = 0, other_label = `Other`, } = opts;
+    // Fresh object each call (not a shared constant) so callers can't corrupt each other
+    if (Array.isArray(data) ? data.length === 0 : !data) {
+        return { arcs: [], root: null, max_depth: 0 };
+    }
+    // Single root node is used directly; arrays get a synthetic invisible root
+    const root_data = Array.isArray(data) ? { children: data } : data;
+    const root = hierarchy(root_data, (node) => node.children);
+    // 'remainder': d3's .sum() adds the node's own value on top of its children's sum,
+    // which is exactly plotly's branchvalues='remainder'. 'leaf-sum' ignores parent values.
+    // 'total': every explicitly set value is authoritative (plotly branchvalues='total');
+    // nodes without one get their children's sum. Children summing to less than their
+    // parent leave a trailing angular gap; more than the parent overflows (plotly errors
+    // here; we warn and the component clamps angles).
+    if (value_mode === `remainder`)
+        root.sum((node) => node.value ?? 0);
+    else if (value_mode === `total`) {
+        root.eachAfter((node) => {
+            const child_sum = node.children?.reduce((sum, child) => sum + (child.value ?? 0), 0) ?? 0;
+            node.value = node.data.value ?? child_sum;
+            if (node.children && node.data.value != null && child_sum > node.data.value + 1e-9) {
+                console.warn(`Sunburst: children of "${node.data.label ?? node.data.id ?? `root`}" sum to ${child_sum}, exceeding its value of ${node.data.value} (value_mode='total')`);
+            }
+        });
+    }
+    else
+        root.sum((node) => (node.children?.length ? 0 : (node.value ?? 0)));
+    if (sort !== `none`) {
+        const sign = sort === `descending` ? -1 : 1;
+        root.sort((node_a, node_b) => sign * ((node_a.value ?? 0) - (node_b.value ?? 0)));
+    }
+    // 'Other' bucketing: move sub-threshold children to the end of each sibling list
+    // (after sorting, before partition) so the smalls occupy one contiguous angular run
+    // that flatten() below can merge into a single synthetic arc.
+    const bucket_threshold = min_fraction > 0 ? min_fraction * (root.value ?? 0) : 0;
+    if (bucket_threshold > 0) {
+        root.each((node) => {
+            if (!node.children)
+                return;
+            const small = node.children.filter((child) => (child.value ?? 0) < bucket_threshold);
+            if (small.length >= 2) {
+                const kept = node.children.filter((child) => (child.value ?? 0) >= bucket_threshold);
+                node.children = [...kept, ...small];
+            }
+        });
+    }
+    // x in [0, 1] (angle fraction), y in ring units (y0 === depth, y1 === depth + 1)
+    const part_root = partition().size([1, root.height + 1])(root);
+    const arcs = [];
+    const seen_ids = new Set();
+    const root_value = root.value ?? 0;
+    const palette_len = DEFAULT_SERIES_COLORS.length;
+    let depth1_count = 0; // running index among depth-1 nodes, for palette cycling
+    // Resolved fill for a node: explicit > depth-1 palette > inherited, optionally
+    // lightened by depth. base = unlightened color descendants inherit.
+    const resolve_color = (depth, explicit, parent_base) => {
+        const base = explicit ??
+            (depth === 1
+                ? DEFAULT_SERIES_COLORS[depth1_count++ % palette_len]
+                : (parent_base ?? `transparent`));
+        let color = base;
+        if (!explicit && depth > 1 && level_lighten > 0) {
+            color = hsl(base)
+                .brighter(level_lighten * (depth - 1))
+                .formatHex();
+        }
+        return { base, color };
+    };
+    // Construct + append an arc, deriving indices, breadcrumbs and fractions from the
+    // parent (shared by regular nodes and synthetic 'Other' arcs)
+    const push_arc = (parent, fields) => {
+        if (seen_ids.has(fields.id)) {
+            console.warn(`Sunburst: duplicate node id "${fields.id}" — set unique \`id\`s or labels.`);
+        }
+        seen_ids.add(fields.id);
+        const arc = {
+            node_idx: arcs.length,
+            subtree_end: arcs.length, // leaves keep this; branches update after recursion
+            parent_idx: parent?.node_idx ?? null,
+            path: parent ? [...parent.path, fields.id] : [],
+            label_path: parent ? [...parent.label_path, fields.label ?? `${fields.id}`] : [],
+            fraction: root_value > 0 ? fields.value / root_value : 0,
+            parent_fraction: parent ? (parent.value > 0 ? fields.value / parent.value : 0) : 1,
+            ...fields,
+        };
+        arcs.push(arc);
+        return arc;
+    };
+    // Pre-order DFS so each subtree occupies a contiguous node_idx range
+    const flatten = (node, parent, parent_base, // unlightened color descendants inherit
+    child_idx) => {
+        const { depth } = node;
+        const explicit = node.data.color;
+        const { base, color } = resolve_color(depth, explicit, parent_base);
+        // Stable id: explicit, else slash-joined label path (e.g. "cubic/Fm-3m")
+        const parent_prefix = parent && parent.id !== `` ? `${parent.id}/` : ``;
+        const segment = node.data.label ?? `${child_idx}`;
+        const id = node.data.id ?? (depth === 0 ? (node.data.label ?? ``) : `${parent_prefix}${segment}`);
+        const { x0, x1, y0, y1 } = node;
+        const arc = push_arc(parent, {
+            id,
+            label: node.data.label,
+            value: node.value ?? 0,
+            color,
+            depth,
+            is_leaf: !node.children?.length,
+            x0,
+            x1,
+            y0,
+            y1,
+            metadata: node.data.metadata,
+        });
+        // Children below the bucket threshold form a contiguous trailing run (reordered
+        // above); merge runs of >= 2 into one synthetic 'Other' leaf instead of recursing
+        const kids = node.children ?? [];
+        let cut = kids.length;
+        if (bucket_threshold > 0) {
+            const first_small = kids.findLastIndex((kid) => (kid.value ?? 0) >= bucket_threshold) + 1;
+            if (kids.length - first_small >= 2)
+                cut = first_small;
+        }
+        kids.forEach((child, idx) => {
+            if (idx < cut)
+                flatten(child, arc, explicit ?? base, idx);
+        });
+        if (cut < kids.length) {
+            const smalls = kids.slice(cut);
+            push_arc(arc, {
+                id: `${arc.id !== `` ? `${arc.id}/` : ``}${other_label}`,
+                label: other_label,
+                value: smalls.reduce((sum, child) => sum + (child.value ?? 0), 0),
+                color: resolve_color(depth + 1, undefined, explicit ?? base).color,
+                depth: depth + 1,
+                is_leaf: true,
+                is_other: true,
+                x0: smalls[0].x0,
+                x1: smalls[smalls.length - 1].x1,
+                y0: depth + 1,
+                y1: depth + 2,
+            });
+        }
+        arc.subtree_end = arcs.length - 1;
+    };
+    flatten(part_root, null, null, 0);
+    return { arcs, root: arcs[0], max_depth: root.height };
+}
+// Build a nested node tree from flat path rows (plotly-express style), e.g.
+// { path: ['cubic', 'Fm-3m'], value: 12 }. Rows sharing a full path accumulate their
+// values; rows whose path is a proper prefix of others set that interior node's own
+// value (meaningful with value_mode 'total'/'remainder').
+export function sunburst_from_paths(rows) {
+    const roots = new Map();
+    rows.forEach((row, row_idx) => {
+        if (!row.path || row.path.length === 0) {
+            throw new Error(`sunburst_from_paths: row ${row_idx} has an empty path`);
+        }
+        let level = roots;
+        let trie;
+        let id = ``;
+        for (const segment of row.path) {
+            id = id ? `${id}/${segment}` : `${segment}`;
+            trie = level.get(segment);
+            if (!trie) {
+                trie = { node: { id, label: `${segment}` }, children: new Map() };
+                level.set(segment, trie);
+            }
+            level = trie.children;
+        }
+        const node = trie.node;
+        node.value = (node.value ?? 0) + row.value;
+        if (row.color != null)
+            node.color = row.color;
+        if (row.metadata != null)
+            node.metadata = row.metadata;
+    });
+    const to_nodes = (level) => [...level.values()].map(({ node, children }) => children.size ? { ...node, children: to_nodes(children) } : node);
+    return to_nodes(roots);
+}
+// Build a nested node tree from plotly trace arrays (labels/parents/values [+ ids]),
+// the format pymatviz/matbench-discovery sunburst exports use (with branchvalues
+// 'total' -> pair with value_mode 'total'). parents entries of ''/null/undefined mark
+// root-level nodes; parents reference ids when given, else labels.
+export function sunburst_from_labels_parents(labels, parents, values, opts = {}) {
+    const { ids, colors, metadata } = opts;
+    for (const [name, arr] of [
+        [`parents`, parents],
+        [`values`, values],
+        [`ids`, ids],
+        [`colors`, colors],
+        [`metadata`, metadata],
+    ]) {
+        if (arr && arr.length !== labels.length) {
+            throw new Error(`sunburst_from_labels_parents: labels (${labels.length}) and ${name} (${arr.length}) must have equal length`);
+        }
+    }
+    const key_to_idx = new Map();
+    const nodes = labels.map((label, idx) => {
+        const key = ids?.[idx] ?? label;
+        if (key_to_idx.has(key)) {
+            throw new Error(`sunburst_from_labels_parents: duplicate node ${ids ? `id` : `label`} "${key}"${ids ? `` : ` — pass opts.ids to disambiguate`}`);
+        }
+        key_to_idx.set(key, idx);
+        const node = { id: key, label };
+        if (values?.[idx] != null)
+            node.value = values[idx];
+        if (colors?.[idx] != null)
+            node.color = colors[idx];
+        if (metadata?.[idx] != null)
+            node.metadata = metadata[idx];
+        return node;
+    });
+    // Resolve all parent references up front (one map lookup per node)
+    const parent_idxs = labels.map((_, idx) => {
+        const ref = parents[idx];
+        if (ref == null || ref === ``)
+            return null;
+        const found = key_to_idx.get(ref);
+        if (found === undefined) {
+            throw new Error(`sunburst_from_labels_parents: node "${ids?.[idx] ?? labels[idx]}" references unknown parent "${ref}"`);
+        }
+        return found;
+    });
+    // O(n) cycle detection: walk each unvisited parent chain once, marking nodes
+    // 'in-progress' on the way up. Hitting an in-progress node = cycle; hitting a
+    // 'done' node = chain already verified acyclic.
+    const state = new Uint8Array(nodes.length); // 0 = unvisited, 1 = in progress, 2 = done
+    for (let idx = 0; idx < nodes.length; idx++) {
+        if (state[idx] !== 0)
+            continue;
+        let cur = idx;
+        while (cur != null && state[cur] === 0) {
+            state[cur] = 1;
+            cur = parent_idxs[cur];
+        }
+        if (cur != null && state[cur] === 1) {
+            throw new Error(`sunburst_from_labels_parents: cycle detected involving node "${ids?.[cur] ?? labels[cur]}"`);
+        }
+        // Mark the walked chain as verified
+        for (let mark = idx; mark != null && state[mark] === 1;) {
+            state[mark] = 2;
+            mark = parent_idxs[mark];
+        }
+    }
+    const roots = [];
+    nodes.forEach((node, idx) => {
+        const parent = parent_idxs[idx];
+        if (parent == null)
+            roots.push(node);
+        else
+            (nodes[parent].children ??= []).push(node);
+    });
+    return roots;
+}

package/dist/rdf/RdfPlot.svelte

@@ -10,6 +10,7 @@
   import { is_crystal } from '../structure/validation'
   import type { ComponentProps, Snippet } from 'svelte'
   import { calculate_all_pair_rdfs, calculate_rdf, type RdfEntry } from './index'
+  import { to_error } from '../utils'
 
   let {
     patterns,
@@ -66,7 +67,7 @@
       }
     } catch (exc) {
       error_msg = `Failed to process structure: ${
-        exc instanceof Error ? exc.message : String(exc)
+        to_error(exc).message
       }`
     }
   }

package/dist/rdf/calc-rdf.js

@@ -6,7 +6,7 @@ const sum_occu = (sites, elem) => sites.reduce((sum, site) => sum + get_occu(sit
 // Calculate radial distribution function
 export function calculate_rdf(structure, options = {}) {
     const { center_species, neighbor_species, cutoff = 15, n_bins = 75, auto_expand = true, expansion_factor = 2.0, } = options;
-    let { pbc = [true, true, true] } = options;
+    const { pbc = [true, true, true] } = options;
     if (cutoff <= 0 || n_bins <= 0) {
         throw new Error(`cutoff and n_bins must be positive`);
     }
@@ -16,6 +16,7 @@ export function calculate_rdf(structure, options = {}) {
     }
     let lattice = structure.lattice.matrix;
     let { sites } = structure;
+    let center_sites = sites;
     // Expand structure if needed to ensure shortest lattice vector is expansion_factor× the cutoff
     // This prevents artificial close contacts at cell boundaries when using PBC
     // Standard practice uses 2.0-2.5× to eliminate finite-size effects
@@ -27,7 +28,10 @@ export function calculate_rdf(structure, options = {}) {
             const expanded_structure = make_supercell(structure, [n_a, n_b, n_c], false);
             sites = expanded_structure.sites;
             lattice = expanded_structure.lattice.matrix;
-            pbc = [false, false, false]; // Disable PBC since we explicitly expanded the structure
+            // Keep PBC: min-image is exact once every lattice vector ≥ 2× cutoff (disabling PBC
+            // starves boundary atoms and biases g(r) low). Under full PBC all periodic copies are
+            // equivalent, so restrict centers to the first copy (make_supercell emits (0,0,0) first)
+            center_sites = pbc.every(Boolean) ? sites.slice(0, structure.sites.length) : sites;
         }
     }
     const bin_size = cutoff / n_bins;
@@ -36,7 +40,7 @@ export function calculate_rdf(structure, options = {}) {
     if (sites.length === 0)
         return { r, g_r };
     // Get occupancy weight for a site-species pair (supports mixed occupancy)
-    const centers = sites.filter((site) => has_species(site, center_species));
+    const centers = center_sites.filter((site) => has_species(site, center_species));
     const neighbors = sites.filter((site) => has_species(site, neighbor_species));
     if (centers.length === 0 || neighbors.length === 0) {
         const element_pair = center_species && neighbor_species
@@ -45,7 +49,7 @@ export function calculate_rdf(structure, options = {}) {
         return { r, g_r, element_pair };
     }
     // Calculate distances and bin them with occupancy weighting
-    const use_pbc = pbc.some((flag) => flag);
+    const use_pbc = pbc.some(Boolean);
     const converters = use_pbc ? create_lattice_converters(lattice) : undefined;
     for (const center of centers) {
         for (const neighbor of neighbors) {
@@ -85,26 +89,9 @@ export function calculate_all_pair_rdfs(structure, options = {}) {
     const elems = [
         ...new Set(structure.sites.flatMap((site) => site.species.map((spec) => spec.element))),
     ].sort();
-    // If auto_expand is true, expand the structure once and reuse it for all pairs
-    // to avoid repeated supercell computations
-    let structure_to_use = structure;
-    if (options.auto_expand !== false) {
-        const { cutoff = 15, expansion_factor = 2.0 } = options;
-        const lattice = structure.lattice?.matrix;
-        if (lattice) {
-            const { a, b, c } = calc_lattice_params(lattice);
-            const min_size = cutoff * expansion_factor;
-            const [n_a, n_b, n_c] = [a, b, c].map((len) => Math.ceil(min_size / len));
-            if (n_a > 1 || n_b > 1 || n_c > 1) {
-                structure_to_use = make_supercell(structure, [n_a, n_b, n_c], false);
-            }
-        }
-    }
-    // Pass auto_expand=false since we've already expanded, and pbc=false for expanded structure
-    const pbc = [false, false, false];
-    const rdf_options = { ...options, auto_expand: false, pbc };
-    return elems.flatMap((el1, idx1) => elems.slice(idx1).map((el2) => calculate_rdf(structure_to_use, {
-        ...rdf_options,
+    // Forward options unchanged (preserves caller's pbc); each calculate_rdf expands itself
+    return elems.flatMap((el1, idx1) => elems.slice(idx1).map((el2) => calculate_rdf(structure, {
+        ...options,
         center_species: el1,
         neighbor_species: el2,
     })));

package/dist/sanitize.js

@@ -53,7 +53,7 @@ function sanitize_svg_content(html, allowed_tags, allowed_attrs) {
     });
     const open_end = wrapped.indexOf(`>`);
     const close_start = wrapped.lastIndexOf(`</svg>`);
-    if (open_end < 0 || close_start < 0)
+    if (open_end === -1 || close_start === -1)
         return wrapped;
     return wrapped.slice(open_end + 1, close_start);
 }

package/dist/settings.d.ts

@@ -2,7 +2,7 @@ import type { ColorScaleType, D3InterpolateName } from './colors';
 import type { HullFaceColorMode } from './convex-hull/types';
 import type { D3SymbolName } from './labels';
 import type { Vec3 } from './math';
-import type { Orientation } from './plot';
+import type { BandwidthOption, Orientation, SankeyNodeAlign, SankeyOrientation, SunburstLabelRotation, SunburstLabelText, SunburstShape, SunburstValueMode, ViolinKind, ViolinSide, WhiskerMode } from './plot';
 import type { BondingStrategy } from './structure/bonding';
 export interface SettingType<T = unknown> {
     value: T;
@@ -63,6 +63,31 @@ type SimpleLineStyleType = {
     width: SettingType<number>;
     color: SettingType<string>;
 };
+type BoxStyleType = {
+    color: SettingType<string>;
+    opacity: SettingType<number>;
+    stroke_width: SettingType<number>;
+    stroke_color: SettingType<string>;
+    border_radius: SettingType<number>;
+};
+type BoxWhiskerStyleType = {
+    width: SettingType<number>;
+    color: SettingType<string>;
+    cap_fraction: SettingType<number>;
+};
+type BoxLineStyleType = {
+    width: SettingType<number>;
+    color: SettingType<string>;
+};
+type BoxOutlierStyleType = {
+    radius: SettingType<number>;
+    opacity: SettingType<number>;
+    stroke_width: SettingType<number>;
+};
+type BoxViolinStyleType = {
+    opacity: SettingType<number>;
+    stroke_width: SettingType<number>;
+};
 type ConvexHullCommonType = {
     camera_zoom: SettingType<number>;
     camera_center_x: SettingType<number>;
@@ -226,6 +251,45 @@ export interface SettingsConfig {
         bar: SimpleBarStyleType;
         line: SimpleLineStyleType;
     };
+    box: {
+        whisker_mode: SettingType<WhiskerMode>;
+        box_width: SettingType<number>;
+        show_outliers: SettingType<boolean>;
+        show_mean: SettingType<boolean>;
+        kind: SettingType<ViolinKind>;
+        side: SettingType<ViolinSide>;
+        bandwidth: SettingType<Exclude<BandwidthOption, number>>;
+        violin_width: SettingType<number>;
+        violin_box_width: SettingType<number>;
+        box: BoxStyleType;
+        whisker: BoxWhiskerStyleType;
+        median: BoxLineStyleType;
+        outlier: BoxOutlierStyleType;
+        violin: BoxViolinStyleType;
+        display: DisplayConfigType;
+    };
+    sankey: {
+        orientation: SettingType<SankeyOrientation>;
+        node_align: SettingType<SankeyNodeAlign>;
+        node_width: SettingType<number>;
+        node_padding: SettingType<number>;
+        link_opacity: SettingType<number>;
+        show_node_labels: SettingType<boolean>;
+        iterations: SettingType<number>;
+    };
+    sunburst: {
+        shape: SettingType<SunburstShape>;
+        value_mode: SettingType<SunburstValueMode>;
+        max_depth: SettingType<number>;
+        inner_radius: SettingType<number>;
+        pad_angle: SettingType<number>;
+        min_fraction: SettingType<number>;
+        show_labels: SettingType<boolean>;
+        label_rotation: SettingType<SunburstLabelRotation>;
+        label_text: SettingType<SunburstLabelText>;
+        zoom_on_click: SettingType<boolean>;
+        show_breadcrumbs: SettingType<boolean>;
+    };
     composition: {
         display_mode: SettingType<`pie` | `bubble` | `bar`>;
         color_scheme: SettingType<string>;