when passed a series, plot_histogram now use series name as x-axis title

fix add_ecdf_line for go.Bar() and throw clear error message when passing unsupported plotly traces (only Histogram, Scatter, and Bar are supported)
fix matplotlib text assertion in test_add_best_fit_line, needed to use AnchoredText instead of Annotation

Author: janosh

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ default_install_hook_types: [pre-commit, commit-msg]
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.4.8
+    rev: v0.4.9
     hooks:
       - id: ruff
         args: [--fix]
@@ -73,7 +73,7 @@ repos:
         exclude: ^(site/src/figs/.+\.svelte|data/wbm/20.+\..+|site/src/(routes|figs).+\.(yaml|json)|changelog.md)$
 
   - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v9.4.0
+    rev: v9.5.0
     hooks:
       - id: eslint
         types: [file]
@@ -87,6 +87,6 @@ repos:
           - typescript-eslint
 
   - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.366
+    rev: v1.1.367
     hooks:
       - id: pyright

pymatviz/enums.py

@@ -121,6 +121,12 @@ class Key(LabelEnum):
     element = "element", "Element"
     energy = "energy", f"Energy {eV}"
     energy_per_atom = "energy_per_atom", f"Energy {eV_per_atom}"
+    # PBE, PBEsol, PBE+U, r2SCAN, etc.
+    dft_functional = "dft_functional", "DFT Functional"
+    uncorrected_energy_per_atom = (
+        "uncorrected_energy_per_atom",
+        f"Uncorrected Energy {eV_per_atom}",
+    )
     cohesive_energy_per_atom = (
         "cohesive_energy_per_atom",
         f"Cohesive Energy {eV_per_atom}",
@@ -131,18 +137,22 @@ class Key(LabelEnum):
     formula = "formula", "Formula"
     formula_pretty = "formula_pretty", "Pretty Formula"
     heat_val = "heat_val", "Heatmap Value"  # used by PTableProjector for ptable data
+    id = "id", "ID"
     init_struct = "initial_structure", "Initial Structure"
     magmoms = "magmoms", "Magnetic Moments"
     mat_id = "material_id", "Material ID"
     n_sites = "n_sites", "Number of Sites"
     oxi_state_guesses = "oxidation_state_guesses", "Oxidation State Guesses"
     spacegroup = "spacegroup", "Spacegroup Number"
     spacegroup_symbol = "spacegroup_symbol", "Spacegroup Symbol"
+    step = "step", "Step"
     stress = "stress", "Stress"
     structure = "structure", "Structure"
+    task = "task", "Task"
     task_id = "task_id", "Task ID"  # unique identifier for a compute task
     task_type = "task_type", "Task Type"
     volume = "volume", "Volume (ų)"
+    vol_per_atom = "volume_per_atom", f"Volume per Atom {cubic_angstrom}"
     wyckoff = "wyckoff", "Aflow-style Wyckoff Label"  # crystallographic site symmetry
     phonon_bandstructure = "phonon_bandstructure", "Phonon Band Structure"
     phonon_dos = "phonon_dos", "Phonon Density of States"

pymatviz/histograms.py

@@ -397,12 +397,22 @@ def plot_histogram(
         fig = plt.figure(**fig_kwargs)
         plt.bar(bin_edges[:-1], hist_vals, **kwargs)
         plt.yscale("log" if log_y else "linear")
+
+        if isinstance(values, pd.Series):
+            plt.xlabel(values.name)
+        plt.ylabel("Density" if density else "Count")
+
     elif backend == PLOTLY_BACKEND:
         fig = go.Figure(**fig_kwargs)
+        kwargs = {"showlegend": False, **kwargs}
         fig.add_bar(x=bin_edges, y=hist_vals, **kwargs)
         _bin_width = (bin_edges[1] - bin_edges[0]) * bin_width
         fig.update_traces(width=_bin_width, marker_line_width=0)
         fig.update_yaxes(type="log" if log_y else "linear")
+
+        if isinstance(values, pd.Series):
+            fig.layout.xaxis.title = values.name
+        fig.layout.yaxis.title = "Density" if density else "Count"
     else:
         raise ValueError(f"Unsupported {backend=}. Must be one of {get_args(Backend)}")
 

pymatviz/powerups.py

@@ -33,6 +33,7 @@
     from matplotlib.offsetbox import AnchoredText
     from matplotlib.text import Annotation
     from numpy.typing import ArrayLike
+    from plotly.basedatatypes import BaseTraceType
 
 
 def with_marginal_hist(
@@ -342,7 +343,13 @@ def add_best_fit_line(
         raise TypeError(f"{fig=} must be instance of {type_names}")
 
     backend = PLOTLY_BACKEND if isinstance(fig, go.Figure) else MPL_BACKEND
-    kwargs.setdefault("color", "blue")
+    # default to navy color but let annotate_params override
+    kwargs.setdefault(
+        "color",
+        annotate_params.get("color", "navy")
+        if isinstance(annotate_params, dict)
+        else "navy",
+    )
 
     if 0 in {len(xs), len(ys)}:
         if isinstance(fig, go.Figure):
@@ -431,12 +438,30 @@ def add_ecdf_line(
         type_names = " | ".join(f"{t.__module__}.{t.__qualname__}" for t in valid_types)
         raise TypeError(f"{fig=} must be instance of {type_names}")
 
-    ecdf = px.ecdf(values if len(values) else fig.data[trace_idx].x).data[0]
+    if values == ():
+        target_trace: BaseTraceType = fig.data[trace_idx]
+        if isinstance(target_trace, (go.Histogram, go.Scatter)):
+            values = target_trace.x
+        elif isinstance(target_trace, go.Bar):
+            xs, ys = target_trace.x, target_trace.y
+            values = np.repeat(xs[:-1], ys)
+
+        else:
+            cls = type(target_trace)
+            qual_name = cls.__module__ + "." + cls.__qualname__
+            raise ValueError(
+                f"Cannot auto-determine x-values for ECDF from {qual_name}, "
+                "pass values explicitly. Currently only Histogram, Scatter, Box, "
+                "and Violin traces are supported and may well need more testing. "
+                "Please report issues at https://github.com/janosh/pymatviz/issues."
+            )
+
+    ecdf_trace = px.ecdf(values).data[0]
 
     # if fig has facets, add ECDF to all subplots
     add_trace_defaults = {} if fig._grid_ref is None else dict(row="all", col="all")  # noqa: SLF001
 
-    fig.add_trace(ecdf, **add_trace_defaults | kwargs)
+    fig.add_trace(ecdf_trace, **add_trace_defaults | kwargs)
     # move ECDF line to secondary y-axis
     # set color to darkened version of primary y-axis color
     trace_defaults = dict(yaxis="y2", name="Cumulative", line=dict(color="gray"))
@@ -454,6 +479,7 @@ def add_ecdf_line(
         color=color,
         linecolor=color,
     )
+    # make secondary ECDF y-axis inherit primary y-axis styles
     fig.layout.yaxis2 = yaxis_defaults | getattr(fig.layout, "yaxis2", {})
 
     return fig

pyproject.toml

@@ -26,7 +26,7 @@ urls = { Homepage = "https://github.com/janosh/pymatviz" }
 requires-python = ">=3.9"
 dependencies = [
     "matplotlib>=3.6.2",
-    "numpy>=1.21.0",
+    "numpy>=1.21.0,<2",
     "pandas>=2.0.0",
     "plotly",
     "pymatgen",

readme.md

@@ -129,7 +129,7 @@ See [`pymatviz/histograms.py`](pymatviz/histograms.py).
 |                               ![spg-num-hist-matplotlib]                               |                                   ![spg-symbol-hist-matplotlib]                                    |
 |   [`spacegroup_hist([65, 134, 225, ...], backend="plotly")`](pymatviz/histograms.py)   |   [`spacegroup_hist(["C2/m", "P-43m", "Fm-3m", ...], backend="plotly")`](pymatviz/histograms.py)   |
 |                                 ![spg-num-hist-plotly]                                 |                                     ![spg-symbol-hist-plotly]                                      |
-| [`elements_hist(compositions, log=True, bar_values='count')`](pymatviz/histograms.py)  |          [`plot_histogram(df_expt_gap["gap expt"], log_y=True)`](pymatviz/histograms.py)           |
+| [`elements_hist(compositions, log=True, bar_values='count')`](pymatviz/histograms.py)  |          [`plot_histogram(df_matbench["gap expt"], log_y=True)`](pymatviz/histograms.py)           |
 |                                    ![elements-hist]                                    |                                     ![matbench-expt-gap-hist]                                      |
 
 [spg-symbol-hist-plotly]: https://github.com/janosh/pymatviz/raw/main/assets/spg-symbol-hist-plotly.svg

tests/test_histograms.py

@@ -3,15 +3,17 @@
 from typing import TYPE_CHECKING, Literal
 
 import matplotlib.pyplot as plt
+import pandas as pd
 import plotly.graph_objects as go
 import pytest
 
 from pymatviz import elements_hist, plot_histogram, spacegroup_hist
 from pymatviz.utils import MPL_BACKEND, PLOTLY_BACKEND, VALID_BACKENDS
-from tests.conftest import y_pred, y_true
+from tests.conftest import df_regr, y_pred, y_true
 
 
 if TYPE_CHECKING:
+    import numpy as np
     from pymatgen.core import Structure
 
     from pymatviz.utils import Backend
@@ -92,8 +94,11 @@ def test_hist_elemental_prevalence(glass_formulas: list[str]) -> None:
 @pytest.mark.parametrize("log_y", [True, False])
 @pytest.mark.parametrize("backend", VALID_BACKENDS)
 @pytest.mark.parametrize("bins", [20, 100])
-def test_plot_histogram(log_y: bool, backend: Backend, bins: int) -> None:
-    fig = plot_histogram(y_true, backend=backend, log_y=log_y, bins=bins)
+@pytest.mark.parametrize("values", [y_true, df_regr.y_true])
+def test_plot_histogram(
+    values: np.ndarray | pd.Series, log_y: bool, backend: Backend, bins: int
+) -> None:
+    fig = plot_histogram(values, backend=backend, log_y=log_y, bins=bins)
     if backend == MPL_BACKEND:
         assert isinstance(fig, plt.Figure)
         y_min, y_max = fig.axes[0].get_ylim()
@@ -105,6 +110,10 @@ def test_plot_histogram(log_y: bool, backend: Backend, bins: int) -> None:
         }[(log_y, bins)]
         assert y_min == pytest.approx(y_min_exp)
         assert y_max == pytest.approx(y_max_exp)
+
+        if isinstance(values, pd.Series):
+            assert fig.axes[0].get_xlabel() == values.name
+        assert fig.axes[0].get_ylabel() == "Count"
     else:
         assert isinstance(fig, go.Figure)
         dev_fig = fig.full_figure_for_development()
@@ -117,3 +126,7 @@ def test_plot_histogram(log_y: bool, backend: Backend, bins: int) -> None:
         }[(log_y, bins)]
         assert y_min == pytest.approx(y_min_exp)
         assert y_max == pytest.approx(y_max_exp)
+
+        if isinstance(values, pd.Series):
+            assert fig.layout.xaxis.title.text == values.name
+        assert fig.layout.yaxis.title.text == "Count"

tests/test_powerups.py

@@ -6,9 +6,10 @@
 from unittest.mock import patch
 
 import matplotlib.pyplot as plt
+import plotly.express as px
 import plotly.graph_objects as go
 import pytest
-from matplotlib.text import Annotation
+from matplotlib.offsetbox import AnchoredText
 
 from pymatviz.powerups import (
     add_best_fit_line,
@@ -276,25 +277,38 @@ def test_add_ecdf_line(
 
     trace_kwargs = trace_kwargs or {}
 
-    ecdf = fig.data[-1]  # retrieve ecdf line
+    ecdf_trace = fig.data[-1]  # retrieve ecdf line
     expected_name = trace_kwargs.get("name", "Cumulative")
     expected_color = trace_kwargs.get("line_color", "gray")
-    assert ecdf.name == expected_name
-    assert ecdf.line.color == expected_color
-    assert ecdf.yaxis == "y2"
+    assert ecdf_trace.name == expected_name
+    assert ecdf_trace.line.color == expected_color
+    assert ecdf_trace.yaxis == "y2"
     assert fig.layout.yaxis2.range == (0, 1)
     assert fig.layout.yaxis2.title.text == expected_name
     assert fig.layout.yaxis2.color == expected_color
 
 
 def test_add_ecdf_line_raises() -> None:
+    # check TypeError when passing invalid fig
     for fig in (None, "foo", 42.0):
         with pytest.raises(
             TypeError,
             match=f"{fig=} must be instance of plotly.graph_objs._figure.Figure",
         ):
             add_ecdf_line(fig)
 
+    # check ValueError when x-values cannot be auto-determined
+    fig_violin = px.violin(x=[1, 2, 3], y=[4, 5, 6])
+    violin_trace = type(fig_violin.data[0])
+    qual_name = f"{violin_trace.__module__}.{violin_trace.__qualname__}"
+    with pytest.raises(
+        ValueError, match=f"Cannot auto-determine x-values for ECDF from {qual_name}"
+    ):
+        add_ecdf_line(fig_violin)
+
+    # check ValueError disappears when passing x-values explicitly
+    add_ecdf_line(fig_violin, values=[1, 2, 3])
+
 
 def test_with_marginal_hist() -> None:
     fig, ax = plt.subplots()
@@ -315,31 +329,40 @@ def test_add_best_fit_line(
     matplotlib_scatter: plt.Figure,
     annotate_params: bool | dict[str, Any],
 ) -> None:
+    # test plotly
     fig_plotly = add_best_fit_line(plotly_scatter, annotate_params=annotate_params)
     assert isinstance(fig_plotly, go.Figure)
-    assert fig_plotly.layout.shapes[-1].type == "line"
+    best_fit_line = fig_plotly.layout.shapes[-1]  # retrieve best fit line
+    assert best_fit_line.type == "line"
+    expected_color = (
+        annotate_params.get("color") if isinstance(annotate_params, dict) else "navy"
+    )
+    assert best_fit_line.line.color == expected_color
 
     if annotate_params:
         assert fig_plotly.layout.annotations[-1].text.startswith("LS fit: ")
+        assert fig_plotly.layout.annotations[-1].font.color == expected_color
     else:
         assert len(fig_plotly.layout.annotations) == 0
 
+    # test matplotlib
     fig_mpl = add_best_fit_line(matplotlib_scatter, annotate_params=annotate_params)
     assert isinstance(fig_mpl, plt.Figure)
     with pytest.raises(IndexError):
         fig_mpl.axes[1]
     ax = fig_mpl.axes[0]
     assert ax.lines[-1].get_linestyle() == "--"
+    assert ax.lines[-1].get_color() == expected_color
 
-    anno = next(  # TODO figure out why this always gives None
-        (child for child in ax.get_children() if isinstance(child, Annotation)),
+    anno: AnchoredText = next(  # TODO figure out why this always gives None
+        (child for child in ax.get_children() if isinstance(child, AnchoredText)),
         None,
     )
 
-    # if annotate_params:
-    #     assert anno.get_text().startswith("LS fit: ")
-    # else:
-    assert anno is None
+    if annotate_params:
+        assert anno.txt.get_text().startswith("LS fit: ")
+    else:
+        assert anno is None
 
 
 def test_add_best_fit_line_invalid_fig() -> None: