Add interactive plots with Plotly

changelog.txt

@@ -15,6 +15,7 @@ Added
 
 - Improve security on multi-user systems. Dashboard now generates a login token when started. Users
   must login with the token to view project and job data in the dashboard.
+- PlotViewer module for showing interactive plots in the dashboard (#162, #163).
 
 Changed
 +++++++

doc/api.rst

@@ -41,6 +41,7 @@ Dashboard Modules
     modules.FlowStatus
     modules.ImageViewer
     modules.Notes
+    modules.PlotViewer
     modules.Schema
     modules.StatepointList
     modules.TextDisplay

examples/plots-matplotlib/README.md

@@ -0,0 +1,3 @@
+# Matplotlib Plots Example
+
+To run this example, call `python init.py` and then `python dashboard.py run`.

examples/plots-plotly/.gitignore

@@ -0,0 +1,3 @@
+signac.rc
+signac_project_document.json
+workspace/

examples/plots/README.md → examples/plots-plotly/README.md

@@ -1,3 +1,3 @@
-# Plots Example
+# Plotly Plots Example
 
 To run this example, call `python init.py` and then `python dashboard.py run`.

examples/plots-plotly/dashboard.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# Copyright (c) 2019 The Regents of the University of Michigan
+# All rights reserved.
+# This software is licensed under the BSD 3-Clause License.
+from scipy.signal import coherence
+
+from signac_dashboard import Dashboard
+from signac_dashboard.modules import PlotViewer, StatepointList, TextDisplay
+
+
+class PlotDashboard(Dashboard):
+    def job_sorter(self, job):
+        return job.sp.get("coherence_time", -1)
+
+    def job_title(self, job):
+        return f"Coherence time: {job.sp.coherence_time}"
+
+
+def correlation_text(job):
+    return "Correlation coefficient: {:.5f}".format(job.doc["correlation"])
+
+
+def plotly_args(job):
+    # Visualization adapted from:
+    # https://matplotlib.org/gallery/lines_bars_and_markers/cohere.html
+
+    # It's necessary to cast to list because the list elements of the job
+    # document are BufferedJSONAttrList, which is not serializable
+    signals_traces = [
+        {
+            "x": list(job.doc["t"]),
+            "y": list(job.doc["s1"]),
+            "name": "s1",
+        },
+        {
+            "x": list(job.doc["t"]),
+            "y": list(job.doc["s2"]),
+            "name": "s2",
+        },
+    ]
+    signals_layout = {
+        "xaxis": {
+            "title": "time",
+            "range": [0, 2],
+        },
+        "height": 200,
+        "margin": dict(t=30, b=40, l=40, r=0),
+    }
+
+    dt = job.doc["t"][1] - job.doc["t"][0]
+    coherence_x, coherence_y = coherence(
+        job.doc["s1"], job.doc["s2"], nfft=256, fs=1.0 / dt
+    )
+    coherence_traces = [
+        {
+            "x": coherence_x.tolist(),
+            "y": coherence_y.tolist(),
+        }
+    ]
+    coherence_layout = {
+        "title": f"Coherence time = {job.sp.coherence_time}",
+        "xaxis": {"title": "frequency"},
+        "yaxis": {"title": "coherence", "range": [0, 1]},
+        "height": 200,
+        "margin": dict(t=30, b=40, l=40, r=0),
+    }
+    return [
+        ("Signals", signals_traces, signals_layout),
+        ("Coherence", coherence_traces, coherence_layout),
+    ]
+
+
+if __name__ == "__main__":
+    modules = []
+    modules.append(StatepointList())
+    modules.append(PlotViewer(plotly_args=plotly_args))
+    modules.append(TextDisplay(name="Correlation", message=correlation_text))
+    PlotDashboard(modules=modules).main()

examples/plots-plotly/init.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+# Copyright (c) 2019 The Regents of the University of Michigan
+# All rights reserved.
+# This software is licensed under the BSD 3-Clause License.
+import numpy as np
+import signac
+
+project = signac.init_project("plots")
+
+
+def plot_coherence(job):
+    # Data generation adapted from:
+    # https://matplotlib.org/gallery/lines_bars_and_markers/cohere.html
+
+    print(f"Generating signals for coherence time {job.sp.coherence_time}, job {job}")
+    # Fixing random state for reproducibility
+    np.random.seed(job.sp.seed)
+
+    dt = 0.01
+    t = np.arange(0, 30, dt)
+    nse1 = np.random.randn(len(t))  # white noise 1
+    nse2 = np.random.randn(len(t))  # white noise 2
+
+    # Two signals with a coherent part and a random part
+    s1 = np.sin(2 * np.pi * job.sp.coherence_time * t) + nse1
+    s2 = np.sin(2 * np.pi * job.sp.coherence_time * t) + nse2
+
+    # Save the signal data
+    job.doc["t"] = t.tolist()
+    job.doc["s1"] = s1.tolist()
+    job.doc["s2"] = s2.tolist()
+
+    # Save correlation coefficient
+    job.doc["correlation"] = np.corrcoef(s1, s2)[0, 1]
+
+
+for i in range(30):
+    job = project.open_job({"coherence_time": i, "seed": 42})
+    job.init()
+    plot_coherence(job)

signac_dashboard/modules/__init__.py

@@ -4,6 +4,7 @@
 from .flow_status import FlowStatus
 from .image_viewer import ImageViewer
 from .notes import Notes
+from .plot_viewer import PlotViewer
 from .schema import Schema
 from .statepoint_list import StatepointList
 from .text_display import TextDisplay
@@ -16,6 +17,7 @@
     "FlowStatus",
     "ImageViewer",
     "Notes",
+    "PlotViewer",
     "Schema",
     "StatepointList",
     "TextDisplay",

signac_dashboard/modules/plot_viewer.py

@@ -0,0 +1,112 @@
+# Copyright (c) 2022 The Regents of the University of Michigan
+# All rights reserved.
+# This software is licensed under the BSD 3-Clause License.
+from typing import Callable, Dict, Iterable, List, Tuple, Union
+
+import flask_login
+from flask import abort, render_template
+from jinja2.exceptions import TemplateNotFound
+from signac import Project
+from signac.contrib.job import Job
+
+from signac_dashboard.dashboard import Dashboard
+from signac_dashboard.module import Module
+
+
+class PlotViewer(Module):
+    """Displays a plot associated with the job.
+
+    The PlotViewer module can display an interactive plot by using the
+    Plotly JavaScript library. For information on the different accepted
+    parameters for the data and layout, refer to the `Plotly JS documentation
+    <https://plotly.com/javascript/>`_.
+
+    Example:
+
+    .. code-block:: python
+
+        from signac_dashboard.modules import PlotViewer
+
+        def plotly_args_function(project):
+            return [
+                ("Card title",  # if empty, the "name" parameter will be used
+                 # each element on the data list is a different trace
+                 [{
+                    "x": [1, 2, 3, 4, 5],  # x coordinates of the trace
+                    "y": [1, 2, 4, 8, 16]  # y coordinates of the trace
+                 }],
+                 {"margin": {"t": 0}}  # layout specification for the whole plot
+                )
+            ]
+
+        plot_module = PlotViewer(plotly_args=plotly_args_function, context="ProjectContext")
+
+    :param name: Default name for the card. Ignored if the :code:`plotly_args`
+        callable provides one for each card.
+    :type name: str
+    :param plotly_args: A callable that accepts a job (in the :code:`'JobContext'`)
+        or a project (in the :code:`'ProjectContext'`) and returns an iterable. Each
+        element will constitute a new card and will be composed of a tuple of three
+        elements: the card title, the plotly data and the plotly layout specification.
+    :type plotly_args: callable
+    :param context: Supports :code:`'JobContext'` and :code:`'ProjectContext'`.
+    :type context: str
+    """
+
+    _supported_contexts = {"JobContext", "ProjectContext"}
+
+    def __init__(
+        self,
+        name="Plot Viewer",
+        plotly_args: Callable[
+            [Union[Job, Project]], Iterable[Tuple[str, List[Dict], Dict]]
+        ] = lambda _: [],
+        context="JobContext",
+        template="cards/plot_viewer.html",
+        **kwargs,
+    ):
+
+        super().__init__(
+            name=name,
+            context=context,
+            template=template,
+            **kwargs,
+        )
+        self.plotly_args = plotly_args
+
+    def get_cards(self, job_or_project):
+        return [
+            {
+                "name": title if title else self.name,
+                "content": render_template(
+                    self.template,
+                    jobid=job_or_project.id,
+                    plotly_data=data,
+                    plotly_layout=layout,
+                ),
+            }
+            for title, data, layout in self.plotly_args(job_or_project)
+        ]
+
+    def register(self, dashboard: Dashboard):
+        # Register routes
+        @dashboard.app.route("/module/plot_viewer/<path:filename>")
+        @flask_login.login_required
+        def plot_viewer_asset(filename):
+            try:
+                return render_template(f"plot_viewer/{filename}")
+            except TemplateNotFound:
+                abort(404, "The file requested does not exist.")
+
+        # Register assets
+        assets = ["js/plot_viewer.js"]
+        for assetfile in assets:
+            dashboard.register_module_asset(
+                {
+                    "url": f"/module/plot_viewer/{assetfile}",
+                }
+            )
+
+        cdn_assets = ["https://cdn.plot.ly/plotly-2.16.1.min.js"]
+        for asseturl in cdn_assets:
+            dashboard.register_module_asset({"url": asseturl})

signac_dashboard/templates/cards/plot_viewer.html

@@ -0,0 +1,4 @@
+<div class="plot_viewer"
+  data-plotly-data='{{ plotly_data | tojson }}'
+  data-plotly-layout='{{ plotly_layout | tojson }}'>
+</div>

signac_dashboard/templates/plot_viewer/js/plot_viewer.js

@@ -0,0 +1,12 @@
+function draw_plot(element) {
+    data = JSON.parse(element.getAttribute("data-plotly-data"));
+    layout = JSON.parse(element.getAttribute("data-plotly-layout"));
+
+    Plotly.newPlot(element, data, layout);
+}
+
+$(document).on('turbolinks:load', function() {
+    $('.plot_viewer').each((index, element) => {
+        draw_plot(element);
+    });
+})