Add widget state export helpers and harden projected DOS tests (#340)

* Add widget display and state export helpers

- add `display()` convenience method to `MatterVizWidget` for notebook usage
- add `to_dict()` to export stable public widget state fields
- add parameterized tests to verify exported keys and runtime state updates

* fix ty errors

* Improve widget normalization and projected DOS stacking behavior

- add strict XRD normalization support for canonical and Ferrox dict schemas with validation and hkls normalization
- enforce exactly one Fermi surface data source and strengthen widget tests by asserting meaningful normalized state
- fix projected DOS stacked fill baseline per model group and update metallic-glass example docs/output formatting for optional values

* Refine XRD schema precedence and test readability

- detect canonical and Ferrox schemas only when all required keys are present, and keep targeted errors for partial schemas
- add regression coverage for mixed-key XRD dicts that should resolve through complete Ferrox schema
- simplify projected DOS stack reset test by reusing one located trace per model label

* Harden trajectory dict handling and normalize Ferrox HKLs

- extract Ferrox HKL normalization into a helper for cleaner XRD input handling
- validate trajectory dict schemas with clearer type/key errors while preserving legacy structure-frame dicts
- add and refine trajectory widget regression tests for invalid schemas and restored lifecycle state

* Harden trajectory normalization tests

- validate and complete trajectory dict inputs more robustly, including per-site coordinate checks and safer species handling
- simplify widget tests by removing tautological/perf-brittle assertions and replacing them with stronger behavioral checks

* fix ty + update readme citations

Author: janosh

.pre-commit-config.yaml

@@ -2,7 +2,7 @@ default_install_hook_types: [pre-commit, commit-msg]
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.0
+    rev: v0.15.2
     hooks:
       - id: ruff-check
         args: [--fix]
@@ -14,11 +14,11 @@ repos:
     hooks:
       - id: ty
         name: ty check
-        entry: ty check
+        entry: ty check --ignore unused-type-ignore-comment --ignore unused-ignore-comment
         language: python
         types: [python]
         pass_filenames: false
-        additional_dependencies: [ty>=0.0.15]
+        additional_dependencies: [ty==0.0.18]
       - id: check-readme-src-links
         name: Check README source links
         entry: python .github/scripts/check_readme_src_links.py
@@ -51,10 +51,10 @@ repos:
       - id: codespell
         stages: [pre-commit, commit-msg]
         exclude_types: [csv, svg, html, yaml, jupyter]
-        args: [--ignore-words-list, 'hist,mape,te,nd,fpr', --check-filenames]
+        args: [--ignore-words-list, 'hist,mape,te,nd,fpr,abou,nam', --check-filenames]
 
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.9.0
+    rev: 0.9.1
     hooks:
       - id: nbstripout
         args: [--drop-empty-cells, --keep-output]
@@ -81,7 +81,7 @@ repos:
           - --fix
 
   - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v10.0.0
+    rev: v10.0.1
     hooks:
       - id: eslint
         types: [file]
@@ -96,7 +96,7 @@ repos:
           - '@stylistic/eslint-plugin'
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.36.1
+    rev: 0.36.2
     hooks:
       - id: check-jsonschema
         files: ^pymatviz/keys\.yml$

assets/scripts/cluster/composition/cluster_compositions_matbench.py

@@ -230,7 +230,7 @@ def annotate_top_points(row: pd.Series) -> dict[str, Any] | None:
     "Bulk Modulus (GPa)",
     "K<sub>VRH</sub>",
 )
-plot_combinations: list[PlotConfig] = [  # ty: ignore[invalid-assignment]
+plot_combinations: list[PlotConfig] = [
     # 1. Steels with PCA (2D) - shows clear linear trends
     (*mb_steels, Embed.magpie, Project.pca, 2, {"x": 0.01, "xanchor": "left"}),
     # 2. Steels with t-SNE (2D) - shows non-linear clustering

assets/scripts/phonons/phonon_dos.py

@@ -23,6 +23,14 @@ class PhonopyDosMissingError(RuntimeError):
     """Raised when phonopy fails to compute a required DOS output."""
 
 
+class PhonopyTotalDosMissingError(PhonopyDosMissingError):
+    """Raised when phonopy total DOS is missing."""
+
+
+class PhonopyProjectedDosMissingError(PhonopyDosMissingError):
+    """Raised when phonopy projected DOS is missing."""
+
+
 def show_figure(plotly_figure: go.Figure, title: str, *, y_pos: float = 0.97) -> None:
     """Apply consistent layout settings and display the figure."""
     plotly_figure.layout.title = dict(text=title, x=0.5, y=y_pos)
@@ -59,7 +67,7 @@ def show_figure(plotly_figure: go.Figure, title: str, *, y_pos: float = 0.97) ->
 phonopy_nacl.run_mesh([10, 10, 10])
 phonopy_nacl.run_total_dos()
 if phonopy_nacl.total_dos is None:
-    raise PhonopyDosMissingError
+    raise PhonopyTotalDosMissingError
 
 plt = phonopy_nacl.plot_total_dos()
 plt.title("NaCl DOS plotted by phonopy")
@@ -75,9 +83,9 @@ def show_figure(plotly_figure: go.Figure, title: str, *, y_pos: float = 0.97) ->
 phonopy_nacl_pdos.run_projected_dos()
 phonopy_nacl_pdos.run_total_dos()
 if phonopy_nacl_pdos.total_dos is None:
-    raise PhonopyDosMissingError
+    raise PhonopyTotalDosMissingError
 if phonopy_nacl_pdos.projected_dos is None:
-    raise PhonopyDosMissingError
+    raise PhonopyProjectedDosMissingError
 
 struct = get_pmg_structure(phonopy_nacl_pdos.primitive)
 total_dos = PhononDos(

assets/scripts/track_pymatviz_citations.py

@@ -232,6 +232,13 @@ def save_papers(papers: list[ScholarPaper], filename: str) -> None:
         yaml.dump(papers, file, default_flow_style=False, allow_unicode=True)
 
 
+def clean_author_name(author_name: str) -> str:
+    """Remove footnote/superscript markers from an author name."""
+    cleaned_name = re.sub(r"\^[0-9]+", "", author_name)
+    cleaned_name = re.sub(r"[⁰¹²³⁴⁵⁶⁷⁸⁹]+", "", cleaned_name)
+    return re.sub(r"\s+", " ", cleaned_name).strip()
+
+
 def update_readme(
     papers: list[ScholarPaper], readme_path: str = f"{ROOT}/readme.md"
 ) -> None:
@@ -270,7 +277,9 @@ def update_readme(
         if not paper.get("authors"):
             print(f"Paper {paper['title']} has no authors, skipping")
             continue
-        authors_str = ", ".join(paper["authors"][:3])
+        authors_str = ", ".join(
+            clean_author_name(author) for author in paper["authors"][:3]
+        )
         if len(paper["authors"]) > 3:
             authors_str += " et al."
 

examples/ward_metallic_glasses/formula_features.py

@@ -111,7 +111,7 @@ def calc_reduced_binary_liquidus_temp(
     binary_interpolations: dict[str, interp1d],
     *,
     on_key_err: Literal["raise", "set-none"] = "set-none",
-) -> float:
+) -> float | None:
     """Calculate the reduced average binary liquidus temperature for a general alloy.
 
     NOTE the unary melting points from the tabulated data are not used here as
@@ -127,11 +127,11 @@ def calc_reduced_binary_liquidus_temp(
         on_key_err ("raise" | "set-none"): How to handle missing binary
             systems.
             If "raise", raises KeyError. If "set-none", returns None.
-            Defaults to "raise".
+            Defaults to "set-none".
 
     Returns:
-        float: The reduced binary liquidus temperature or None if on_key_err="set-none"
-            and a binary system is missing.
+        float | None: Reduced binary liquidus temperature or None if
+            on_key_err="set-none" and a binary system is missing.
     """
     if len(composition) < 2:
         return 1.0
@@ -149,7 +149,7 @@ def calc_reduced_binary_liquidus_temp(
         except KeyError:
             if on_key_err == "raise":
                 raise
-            return None  # type: ignore[return-value]
+            return None
         binary_weight = sum(comp_dict.values())
         temp_alloy += temp_binary * binary_weight
         temp_alloy_norm += binary_weight
@@ -335,13 +335,15 @@ def one_hot_encode(df_in: pd.DataFrame) -> pd.DataFrame:
     binary_interpolations = load_binary_liquidus_data(zip_path)
 
     # Test with a simple binary composition
-    test_comp = Composition("Pt50P50")
+    test_comp = "Pt50P50"
     features = calc_liu_features(
         [test_comp], binary_liquidus_data=binary_interpolations
     )
     print("\nFeatures for Pt50P50:")
     for feature, values in features.items():
-        print(f"{feature}: {values[test_comp]:.2f}")  # type: ignore[index]
+        feature_value = values.get(test_comp)
+        value_text = "N/A" if feature_value is None else f"{feature_value:.2f}"
+        print(f"{feature}: {value_text}")
 
     # Test with a more complex composition
     test_comp2 = "Zr6.2Ti45.8Cu39.9Ni5.1Sn3"
@@ -350,7 +352,9 @@ def one_hot_encode(df_in: pd.DataFrame) -> pd.DataFrame:
     )
     print(f"\nFeatures for {test_comp2}:")
     for feature, values in features2.items():
-        print(f"{feature}: {values[test_comp2]:.2f}")
+        feature_value = values.get(test_comp2)
+        value_text = "N/A" if feature_value is None else f"{feature_value:.2f}"
+        print(f"{feature}: {value_text}")
 
     # Example of batch processing with a DataFrame
     df_test = pd.DataFrame(

pymatviz/brillouin.py

@@ -85,8 +85,8 @@ def brillouin_zone_3d(
 
     for idx, (struct_key, structure) in enumerate(structures.items(), start=1):
         # Convert pymatgen Structure to seekpath input format
-        lattice = structure.lattice  # ty: ignore[possibly-missing-attribute]
-        frac_coords = structure.frac_coords  # ty: ignore[possibly-missing-attribute]
+        lattice = structure.lattice
+        frac_coords = structure.frac_coords
         spglib_atoms = (
             lattice.matrix,  # cell
             frac_coords,  # positions

pymatviz/classify/confusion_matrix.py

@@ -1,7 +1,7 @@
 """Confusion matrix plotting functions."""
 
 from collections.abc import Callable, Sequence
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 import numpy as np
 import plotly.graph_objects as go
@@ -133,6 +133,7 @@ def confusion_matrix(
     if annotations is None:
         processed_annotations = fmt_tile_vals
     elif callable(annotations):  # If annotations is a callable, apply it to each cell
+        annotation_func = cast("Callable[[int, int, float, float], str]", annotations)
         total = sample_counts.sum()
         anno_matrix = []
         for ii in range(len(conf_mat_arr)):
@@ -150,7 +151,7 @@ def confusion_matrix(
                     if conf_mat_arr[:, jj].sum() > 0
                     else 0
                 )
-                row += [annotations(count, total, row_pct, col_pct)]
+                row += [annotation_func(count, total, row_pct, col_pct)]
             anno_matrix += [row]
         processed_annotations = np.array(anno_matrix).T
     else:  # When custom annotations provided, append percentage values

pymatviz/cluster/composition/plot.py

@@ -5,7 +5,7 @@
 import math
 import warnings
 from collections.abc import Callable, Sequence
-from typing import TYPE_CHECKING, Any, Literal, Protocol, get_args
+from typing import TYPE_CHECKING, Any, Literal, Protocol, cast, get_args
 
 import numpy as np
 import pandas as pd
@@ -609,7 +609,8 @@ def cluster_compositions(
             # Create embeddings
             if callable(embedding_method):
                 # Use custom embedding function
-                embeddings = embedding_method(compositions, **(embedding_kwargs or {}))
+                embedding_fn = cast("EmbeddingCallable", embedding_method)
+                embeddings = embedding_fn(compositions, **(embedding_kwargs or {}))
             # Use built-in embedding methods
             elif embedding_method == "one-hot":
                 embeddings = one_hot_encode(compositions, **(embedding_kwargs or {}))
@@ -628,7 +629,8 @@ def cluster_compositions(
         # Project embeddings
         if callable(projection):
             # Use custom projection function
-            projected = projection(
+            projection_fn = cast("ProjectionCallable", projection)
+            projected = projection_fn(
                 embeddings,
                 n_components=n_components,
                 **projection_kwargs,

pymatviz/phonons/figures.py

@@ -4,7 +4,7 @@
 
 import sys
 from collections import defaultdict
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from typing import TYPE_CHECKING, Any, Literal, cast
 
 import numpy as np
@@ -271,7 +271,10 @@ def phonon_bands(
                 # Apply line style based on line_kwargs type
                 if callable(line_kwargs):
                     # Pass band data and index to callback
-                    custom_style = line_kwargs(frequencies, band_idx)
+                    line_style_callback = cast(
+                        "Callable[[np.ndarray, int], dict[str, Any]]", line_kwargs
+                    )
+                    custom_style = line_style_callback(frequencies, band_idx)
                     line_defaults |= custom_style
                 elif isinstance(line_kwargs, dict):
                     # check for custom line styles for one or both modes
@@ -413,6 +416,9 @@ def phonon_dos(
     )
 
     dos_dict: dict[str, PhononDos] = {}
+    stack_group_by_trace: dict[str, str] | None = (
+        {} if stack and project is not None else None
+    )
     total_overlay_dict: dict[str, PhononDos] = {}
     for label, raw_dos in raw_doses.items():
         label_prefix = f"{label} - " if label else ""
@@ -448,7 +454,11 @@ def phonon_dos(
                 for site_idx, site in enumerate(raw_dos.structure)
             }
         )
-        dos_dict |= {f"{label_prefix}{key}": dos for key, dos in projected_dos.items()}
+        for key, dos in projected_dos.items():
+            trace_name = f"{label_prefix}{key}"
+            dos_dict[trace_name] = dos
+            if stack_group_by_trace is not None:
+                stack_group_by_trace[trace_name] = label
         if show_total:
             total_overlay_dict[f"{label_prefix}Total"] = PhononDos(
                 raw_dos.frequencies, raw_dos.densities
@@ -493,20 +503,27 @@ def _prepare_dos(dos: PhononDos) -> tuple[np.ndarray, np.ndarray]:
 
     fig = go.Figure()
     cumulative_density_by_group: dict[str, np.ndarray] = {}
+    seen_stack_groups: set[str] = set()
+
+    def _stack_group(trace_name: str) -> str:
+        """Return stack accumulation group for this DOS trace."""
+        if project is None:
+            return ""
+        return stack_group_by_trace.get(trace_name, "") if stack_group_by_trace else ""
+
     for dos_name, dos_obj in dos_dict.items():
         frequencies, densities = _prepare_dos(dos_obj)
         scatter_kwargs: dict[str, Any] = {"mode": "lines"}
         if stack:
-            stack_group = (
-                ""
-                if project is None or " - " not in dos_name
-                else dos_name.split(" - ", maxsplit=1)[0]
-            )
+            stack_group = _stack_group(dos_name)
             densities = densities + cumulative_density_by_group.get(
                 stack_group, np.zeros_like(densities)
             )
             cumulative_density_by_group[stack_group] = densities
-            scatter_kwargs["fill"] = "tonexty"
+            scatter_kwargs["fill"] = (
+                "tozeroy" if stack_group not in seen_stack_groups else "tonexty"
+            )
+            seen_stack_groups.add(stack_group)
         fig.add_scatter(
             x=frequencies, y=densities, name=dos_name, **scatter_kwargs | kwargs
         )

pymatviz/powerups.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Sequence
-from typing import TYPE_CHECKING, Any, Literal, get_args
+from typing import TYPE_CHECKING, Any, Literal, cast, get_args
 
 import numpy as np
 import plotly.express as px
@@ -219,7 +219,10 @@ def _get_valid_traces(
             valid_range = f"0-{len(fig.data) - 1}"
             raise ValueError(f"No valid trace indices in {traces}, {valid_range=}")
     elif callable(traces):
-        selected_traces = [idx for idx, trace in enumerate(fig.data) if traces(trace)]
+        trace_predicate = cast("TracePredicate", traces)
+        selected_traces = [
+            idx for idx, trace in enumerate(fig.data) if trace_predicate(trace)
+        ]
         if not selected_traces:
             raise ValueError("No traces matched the filtering function")
     else:
@@ -884,10 +887,18 @@ def validate_ecdf_trace(trace: go.Scatter) -> bool:
             fig.data[-1].update(**current_trace_kwargs)
 
     # Make sure yaxis2 has color set if specified in trace_kwargs
-    if "line" in trace_kwargs and "color" in trace_kwargs["line"]:
-        fig.layout.yaxis2.color = trace_kwargs["line"]["color"]
-    elif "line_color" in trace_kwargs:
-        fig.layout.yaxis2.color = trace_kwargs["line_color"]
+    yaxis2_color: str | None = None
+    line_settings = trace_kwargs.get("line")
+    if isinstance(line_settings, dict):
+        line_color = line_settings.get("color")
+        if isinstance(line_color, str):
+            yaxis2_color = line_color
+    if yaxis2_color is None:
+        top_level_line_color = trace_kwargs.get("line_color")
+        if isinstance(top_level_line_color, str):
+            yaxis2_color = top_level_line_color
+    if yaxis2_color is not None:
+        fig.layout.yaxis2.update(color=yaxis2_color)
 
     return fig