Add hook_up_fig_with_ctk_struct_viewer() to crystal_toolkit/helpers/utils.py (#320)

* add some types to crystal_toolkit/helpers/utils.py

* add hook_up_fig_with_ctk_struct_viewer() to crystal_toolkit/helpers/utils.py

* add myself to list of contributors

* fix typos in PR template

* add minimal example and link to PR with screen recording to doc str

Author: janosh

.github/pull_request_template.md

@@ -17,10 +17,10 @@ contributor/co-author.
 
 Work-in-progress pull requests are encouraged but please [mark your PR as draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft).
 
-Usually the following items should be checked before merging a PR:
+Usually, the following items should be checked before merging a PR:
 
 - [ ] Doc strings have been added in the [Google docstring format](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
-- [ ] Type annotations are *highly* encouraged. Run [`mypy path/to/file.py`](https://github.com/python/mypy) to type check your code. Type checks are run in CI.
+- [ ] Type annotations are *highly* encouraged. Run [`mypy path/to/file.py`](https://github.com/python/mypy) to type-check your code. Type checks are run in CI.
 - [ ] Tests for any new functionality as well as bug fixes, where appropriate.
 - [ ] Create a new [Issue](https://github.com/materialsproject/crystaltoolkit/issues) for any TODO items that will result from merging the PR.
 

README.md

@@ -3,7 +3,7 @@
 ## Interested in contributing?
 
 A current list of new contributor issues can be seen [here](https://github.com/materialsproject/crystaltoolkit/labels/new-contributor).
-If you would like a new contributor issue assigned, get in touch with project maintainers!
+If you would like a new-contributor issue assigned, get in touch with project maintainers!
 
 ## Status
 
@@ -21,7 +21,7 @@ pip install crystal-toolkit
 
 ## Documentation
 
-[Documentation can be found at docs.crystaltoolkit.org](https://docs.crystaltoolkit.org)
+Documentation can be found at [docs.crystaltoolkit.org](https://docs.crystaltoolkit.org).
 
 ## Example Apps
 
@@ -60,13 +60,14 @@ The [Crystal Toolkit Development Team](https://github.com/materialsproject/cryst
 * [Donny Winston](https://github.com/dwinston), assisted by [Tyler Huntington](https://github.com/tylerhuntington), for helping embed Crystal Toolkit in a Django app
 * [Matt McDermott](https://github.com/mattmcdermott) contributed phase diagram, X-ray Diffraction, X-ray Absorption Spectrum components
 * [Jason Munro](https://github.com/munrojm) contributed band structure component
+* [Janosh Riebesell](https://github.com/janosh) contributed Phonon band structure component, [3 example apps](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/matbench_dielectric_structure_on_hover.py), tests
 * [Stephen Weitzner](https://github.com/sweitzner) contributed POV-Ray integration (in progress)
 * [Richard Tran](https://github.com/CifLord) for contributing plotly-powered Wulff shapes to pymatgen, which Crystal Toolkit uses
 * [Guy Moore](https://github.com/guymoore13) for contributing magnetic moment visualization
 * [Steve Zeltmann](https://github.com/sezelt) for contributing electron diffraction
 * [Patrick Huck](https://github.com/tschaume), releases, operations, bugfixes and POC for MP / MPContribs
 
-New contributors are welcome, please see our [Code of Conduct.](code-of-conduct.md) If you are a new contributor please modify this README in your Pull Request to add your name to the list.
+New contributors are welcome, please see our [Code of Conduct](code-of-conduct.md). If you are a new contributor please modify this README in your Pull Request to add your name to the list.
 
 ## Future of This Repository
 
@@ -82,11 +83,9 @@ Thank you to all the authors and maintainers of the libraries Crystal Toolkit
 depends upon, and in particular [pymatgen](http://pymatgen.org) for crystallographic
 analysis and [Dash from Plotly](https://plot.ly/products/dash/) for their web app framework.
 
-Thank you to the [NERSC Spin](https://www.nersc.gov/systems/spin) service for
+Thank you to the [NERSC Spin](https://nersc.gov/systems/spin) service for
 hosting the app and for their technical support.
 
-Cross-browser Testing Platform and Open Source <3 generously provided by [Sauce Labs](https://saucelabs.com)
-
 ## Contact
 
 Please contact @mkhorton with any queries or add an issue on the [GitHub Issues](https://github.com/materialsproject/crystaltoolkit/issues) page.

crystal_toolkit/helpers/utils.py

@@ -4,16 +4,23 @@
 import re
 import urllib.parse
 from fractions import Fraction
-from typing import Any
+from typing import Any, Callable
 from uuid import uuid4
 
+import dash
 import dash_mp_components as mpc
 import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+from dash import Dash, dcc, html
 from dash import dash_table as dt
-from dash import dcc, html
+from dash.dependencies import Input, Output, State
 from flask import has_request_context, request
 from monty.serialization import loadfn
+from numpy.typing import ArrayLike
+from pymatgen.core import Structure
 
+import crystal_toolkit.components as ctc
 import crystal_toolkit.helpers.layouts as ctl
 from crystal_toolkit import MODULE_PATH
 from crystal_toolkit.defaults import _DEFAULTS
@@ -437,8 +444,10 @@ def get_section_heading(title, dois=None, docs_url=None, app_button_id=None):
     return ctl.H4([title, docs_button, app_link])
 
 
-def get_matrix_string(matrix, variable_name=None, decimals=4):
-    """Returns a string for use in mpc.Markdown() to render a matrix or vector.
+def get_matrix_string(
+    matrix: ArrayLike, variable_name: str = None, decimals: int = 4
+) -> str:
+    """Returns a LaTeX-formatted string for use in mpc.Markdown() to render a matrix or vector.
 
     :param matrix: list or numpy array
     :param variable_name: LaTeX-formatted variable name
@@ -455,23 +464,21 @@ def get_matrix_string(matrix, variable_name=None, decimals=4):
 
     footer = "\\end{bmatrix}\n$$"
 
-    matrix_string = ""
-
-    assert hasattr(matrix, "__iter__"), "The matrix provided was not iterable"
+    matrix_str = ""
 
     for row in matrix:
-        row_string = ""
+        row_str = ""
         for idx, value in enumerate(row):
-            row_string += f"{value:.4g}"
+            row_str += f"{value:.4g}"
             if idx != len(row) - 1:
-                row_string += " & "
-        row_string += " \\\\ \n"
-        matrix_string += row_string
+                row_str += " & "
+        row_str += " \\\\ \n"
+        matrix_str += row_str
 
-    return header + matrix_string + footer
+    return header + matrix_str + footer
 
 
-def update_css_class(kwargs, class_name):
+def update_css_class(kwargs: dict[str, Any], class_name: str) -> None:
     """Convenience function to update className while respecting any additional classNames already
     set.
     """
@@ -481,7 +488,7 @@ def update_css_class(kwargs, class_name):
         kwargs["className"] = class_name
 
 
-def is_mpid(value: str):
+def is_mpid(value: str) -> str | bool:
     """Determine if a string is in the MP ID syntax.
 
     Checks if the string starts with 'mp-' or 'mvc-' and is followed by only numbers.
@@ -492,7 +499,7 @@ def is_mpid(value: str):
         return False
 
 
-def pretty_frac_format(x):
+def pretty_frac_format(x: float) -> str:
     """Formats a float to a fraction, if the fraction can be expressed without a large
     denominator.
     """
@@ -506,3 +513,127 @@ def pretty_frac_format(x):
     else:
         x_str = str(fraction)
     return x_str
+
+
+def hook_up_fig_with_ctk_struct_viewer(
+    fig: go.Figure,
+    df: pd.DataFrame,
+    struct_col: str = "structure",
+    validate_id: Callable[[str], bool] = lambda id: True,
+) -> Dash:
+    """Create a Dash app that hooks up a Plotly figure with a Crystal Toolkit structure
+    component. See https://github.com/materialsproject/crystaltoolkit/pull/320 for
+    screen recording of example app.
+
+    Usage example:
+        import random
+
+        import pandas as pd
+        import plotly.express as px
+        from crystal_toolkit.helpers.utils import hook_up_fig_with_ctk_struct_viewer
+        from pymatgen.ext.matproj import MPRester
+
+        # Get random structures from the Materials Project
+        mp_ids = [f"mp-{random.randint(1, 10000)}" for _ in range(100)]
+        structures = MPRester(use_document_model=False).summary.search(material_ids=mp_ids)
+
+        df = pd.DataFrame(structures)
+        id_col = "material_id"
+
+        fig = px.scatter(df, x="nsites", y="volume", hover_name=id_col, template="plotly_white")
+        app = hook_up_fig_with_ctk_struct_viewer(fig, df.set_index(id_col))
+        app.run_server(port=8000)
+
+    Args:
+        fig (Figure): Plotly figure to be hooked up with the structure component. The
+            figure must have hover_name set to the index of the data frame to identify
+            dataframe rows with plot points.
+        df (pd.DataFrame): Data frame from which to pull the structure corresponding to
+            a hovered/clicked point in the plot.
+        struct_col (str, optional): Name of the column in the data frame that contains
+            the structures. Defaults to 'structure'. Can be instances of
+            pymatgen.core.Structure or dicts created with Structure.as_dict().
+        validate_id (Callable[[str], bool], optional): Function that takes a string
+            extracted from the hovertext key of a hoverData event payload and returns
+            True if the string is a valid df row index. Defaults to lambda
+            id: True. Useful for not running the update-structure
+            callback on unexpected data.
+
+    Returns:
+        Dash: The interactive Dash app to be run with app.run_server().
+    """
+    structure_component = ctc.StructureMoleculeComponent(id="structure")
+
+    app = Dash(prevent_initial_callbacks=True, assets_folder=SETTINGS.ASSETS_PATH)
+    graph = dcc.Graph(id="plot", figure=fig, style={"width": "90vh"})
+    hover_click_dd = dcc.Dropdown(
+        id="hover-click-dropdown",
+        options=["hover", "click"],
+        value="click",
+        clearable=False,
+        style=dict(minWidth="5em"),
+    )
+    hover_click_dropdown = html.Div(
+        [
+            html.Label("Update structure on:", style=dict(fontWeight="bold")),
+            hover_click_dd,
+        ],
+        style=dict(
+            display="flex",
+            placeContent="center",
+            placeItems="center",
+            gap="1em",
+            margin="1em",
+        ),
+    )
+    struct_title = html.H2(
+        "Try hovering on a point in the plot to see its corresponding structure",
+        id="struct-title",
+        style=dict(position="absolute", padding="1ex 1em", maxWidth="25em"),
+    )
+    graph_structure_div = html.Div(
+        [graph, html.Div([struct_title, structure_component.layout()])],
+        style=dict(display="flex", gap="2em", margin="2em 0"),
+    )
+    app.layout = html.Div(
+        [hover_click_dropdown, graph_structure_div],
+        style=dict(margin="2em", padding="1em"),
+    )
+    ctc.register_crystal_toolkit(app=app, layout=app.layout)
+
+    @app.callback(
+        Output(structure_component.id(), "data"),
+        Output(struct_title, "children"),
+        Input(graph, "hoverData"),
+        Input(graph, "clickData"),
+        State(hover_click_dd, "value"),
+    )
+    def update_structure(
+        hover_data: dict[str, list[dict[str, Any]]],
+        click_data: dict[str, list[dict[str, Any]]],  # needed only as callback trigger
+        dropdown_value: str,
+    ) -> tuple[Structure, str] | tuple[None, None]:
+        """Update StructureMoleculeComponent with pymatgen structure when user clicks or
+        hovers a plot point.
+        """
+        triggered = dash.callback_context.triggered[0]
+        if dropdown_value == "click" and triggered["prop_id"].endswith(".hoverData"):
+            # do nothing if we're in update-on-click mode but callback was triggered by
+            # hover event
+            raise dash.exceptions.PreventUpdate
+
+        # hover_data and click_data are identical since a hover event always precedes a
+        # click so we always use hover_data
+        material_id = hover_data["points"][0]["hovertext"]
+        if not validate_id(material_id):
+            print(f"bad {material_id=}")
+            raise dash.exceptions.PreventUpdate
+
+        struct = df[struct_col][material_id]
+        if isinstance(struct, dict):
+            struct = Structure.from_dict(struct)
+        struct_title = f"{material_id} ({struct.formula})"
+
+        return struct, struct_title
+
+    return app

docs_rst/introduction.rst

@@ -69,6 +69,7 @@ Contributors
 * `Donny Winston <https://github.com/dwinston>`_, assisted by `Tyler Huntington <https://github.com/tylerhuntington>`_, for helping embed Crystal Toolkit in a Django app
 * `Matt McDermott <https://github.com/mattmcdermott>`_ contributed phase diagram, X-ray Diffraction, X-ray Absorption Spectrum components
 * `Jason Munro <https://github.com/munrojm>`_ contributed band structure component
+* `Janosh Riebesell <https://github.com/janosh>`_ contributed Phonon band structure component, 3 example apps, tests
 * `Stephen Weitzner <https://github.com/sweitzner>`_ contributed POV-Ray integration (in progress)
 * `Richard Tran <https://github.com/CifLord>`_ for contributing plotly-powered Wulff shapes to pymatgen, which Crystal Toolkit uses
 * `Guy Moore <https://github.com/guymoore13>`_ for contributing magnetic moment visualization