Add widget inputs support (#11)

- Add support for handling widget inputs
  - auto-generated UI based on widget inputs
  - support for server side validation and error display
- Add COM distance and Radii of Gyration analysis widgets
- Add support for widget lifecycle methods
  - post_connect, post_disconnect, post_pause, pre_resume
  - on_input_change
- Limit emits from server to client session only when applicable
- Tests for all new backend and frontend functionality
- Verify the built wheel by running `mdadash -h` in CI

Author: PardhavMaradani

.github/workflows/deploy.yaml

@@ -48,6 +48,13 @@ jobs:
           echo "twine check $WHL"
           twine check $WHL
 
+      - name: Install from wheel and verify
+        run: |
+          WHL=$(ls -t1 dist/mdadash-*.whl | head -n 1)
+          python -m pip uninstall -y mdadash || true
+          python -m pip install $WHL
+          mdadash -h
+
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:

.github/workflows/gh-ci.yaml

@@ -150,14 +150,25 @@ jobs:
 
       - name: Build package
         run: |
-          python -m pipx run build --sdist
+          python -m pipx run build
 
       - name: Check package build
         run: |
-          DISTRIBUTION=$(ls -t1 dist/mdadash-*.tar.gz | head -n 1)
-          test -n "${DISTRIBUTION}" || { echo "no distribution dist/mdadash-*.tar.gz found"; exit 1; }
-          echo "twine check $DISTRIBUTION"
-          twine check $DISTRIBUTION
+          SDIST=$(ls -t1 dist/mdadash-*.tar.gz | head -n 1)
+          test -n "${SDIST}" || { echo "no source distribution dist/mdadash-*.tar.gz found"; exit 1; }
+          echo "twine check $SDIST"
+          twine check $SDIST
+          WHL=$(ls -t1 dist/mdadash-*.whl | head -n 1)
+          test -n "${WHL}" || { echo "no whl dist/mdadash-*.whl found"; exit 1; }
+          echo "twine check $WHL"
+          twine check $WHL
+
+      - name: Install from wheel and verify
+        run: |
+          WHL=$(ls -t1 dist/mdadash-*.whl | head -n 1)
+          python -m pip uninstall -y mdadash || true
+          python -m pip install $WHL
+          mdadash -h
 
   backend_lint_check:
     name: Backend lint check

.pylintrc

@@ -446,7 +446,10 @@ disable=raw-checker-failed,
         missing-class-docstring,
         missing-function-docstring,
         fixme,
-        too-few-public-methods
+        too-few-public-methods,
+        protected-access,
+        too-many-instance-attributes,
+        similarities,
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option

CHANGELOG.md

@@ -32,6 +32,7 @@ The rules for this file:
 - Added basic widget execution framework and energy widgets (PR #8)
 - Reduce package size by moving away from mdi/font to mdi/js (PR #9)
 - Added support to display imdclient session info (PR #10)
+- Added widget inputs support (PR #11)
 
 ### Fixed
 

DEVELOPMENT.md

@@ -176,7 +176,7 @@ rm -rf mdadash.egg-info dist && python -m build
 To verify the created wheel in an isolated environment:
 
 ```sh
-uv run --refresh --with path.to.whl mdadash <options>
+uv run --no-project --refresh --with path.to.whl mdadash <options>
 ```
 
 To check the created distribution:

mdadash/backend/analyses/__init__.py

@@ -2,8 +2,10 @@
 Module that has all the analyses widgets
 """
 
-from . import energies
+from . import com_distance, energies, rog
 
 __all__ = [
     "energies",
+    "com_distance",
+    "rog",
 ]

mdadash/backend/analyses/com_distance.py

@@ -0,0 +1,162 @@
+"""
+Distance between two center-of-masses
+"""
+
+from collections import deque
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from mdadash.backend.widgets.base import WidgetBase
+
+
+class COMDistance(WidgetBase):
+    """COM Distance
+
+    Distance between two center-of-masses (COMs)
+
+    """
+
+    name = "COMDistance"
+    description = "Distance between two COMs"
+
+    _inputs = [
+        {
+            "attribute": "selection1",
+            "name": "Selection 1",
+            "description": "First MDAnalysis selection phrase",
+            "type": "str",
+            "validations": ["required"],
+        },
+        {
+            "attribute": "selection2",
+            "name": "Selection 2",
+            "description": "Second MDAnalysis selection phrase",
+            "type": "str",
+            "validations": ["required"],
+        },
+        {
+            "attribute": "periodic",
+            "name": "Periodic",
+            "description": "Select with periodic boundary conditions",
+            "type": "switch",
+        },
+        {
+            "attribute": "updating",
+            "name": "Updating",
+            "description": "Update selection during each timestep",
+            "type": "switch",
+        },
+        {
+            "attribute": "custom_title",
+            "name": "Custom title",
+            "description": "Custom title for the plot",
+            "type": "str",
+        },
+        {
+            "attribute": "maxlen",
+            "name": "Max values",
+            "description": "Max values to show in plot",
+            "type": "int",
+        },
+        {
+            "attribute": "max_distance",
+            "name": "Max distance",
+            "description": "Max distance for alert check",
+            "type": "int",
+        },
+        {
+            "attribute": "max_distance_alert",
+            "name": "Alert if distance > 'Max distance'",
+            "type": "switch",
+        },
+        {
+            "attribute": "x_type",
+            "name": "X-axis",
+            "type": "toggle",
+            "options": [
+                {"name": "Step", "value": "step"},
+                {"name": "Time", "value": "time"},
+            ],
+        },
+    ]
+
+    def __init__(self):
+        super().__init__()
+        self.maxlen = 100
+        self.steps = deque(maxlen=self.maxlen)
+        self.times = deque(maxlen=self.maxlen)
+        self.y_values = deque(maxlen=self.maxlen)
+        self.selection1 = "protein"
+        self.selection2 = "resid 1"
+        self.periodic = True
+        self.updating = False
+        self.ag1 = None
+        self.ag2 = None
+        self.title = "Distance between COMs"
+        self.custom_title = None
+        self.max_distance = 5
+        self.max_distance_alert = False
+        self.x_type = "step"
+        self.x_values = self.steps
+        self.x_label = "Step"
+
+    def _update_selections(self, s1=False, s2=False):
+        """Update atom groups when selection phrases change"""
+        if s1:
+            self.ag1 = self.u.select_atoms(
+                self.selection1, periodic=self.periodic, updating=self.updating
+            )
+        if s2:
+            self.ag2 = self.u.select_atoms(
+                self.selection2, periodic=self.periodic, updating=self.updating
+            )
+        self.title = f"{self.selection1} <-> {self.selection2}"
+
+    def _set_x_values(self):
+        """Set the values for the x-axis"""
+        if self.x_type == "step":
+            self.x_label = "Step"
+            self.x_values = self.steps
+        else:
+            self.x_label = "Time (ps)"
+            self.x_values = self.times
+
+    def post_connect(self):
+        """post_connect handler"""
+        self._update_selections(s1=True, s2=True)
+
+    def on_input_change(self, attribute, _old_value, new_value):
+        """on_input_change handler"""
+        reset_plot = False
+        if attribute == "maxlen":
+            reset_plot = True
+        elif attribute == "x_type":
+            self._set_x_values()
+        elif attribute == "selection1":
+            self._update_selections(s1=True)
+            reset_plot = True
+        elif attribute == "selection2":
+            self._update_selections(s2=True)
+            reset_plot = True
+        elif attribute in ("periodic", "updating"):
+            self._update_selections(s1=True, s2=True)
+        if reset_plot:
+            self.steps = deque(maxlen=self.maxlen)
+            self.times = deque(maxlen=self.maxlen)
+            self.y_values = deque(maxlen=self.maxlen)
+            self._set_x_values()
+
+    def run(self):
+        """run handler"""
+        com1 = self.ag1.center_of_mass()
+        com2 = self.ag2.center_of_mass()
+        self.y_values.append(np.linalg.norm(com1 - com2))
+        self.steps.append(self.u.trajectory.ts.data["step"])
+        self.times.append(self.u.trajectory.ts.data["time"])
+        plt.plot(self.x_values, self.y_values)
+        plt.ylabel("Distance (Å)")
+        plt.xlabel(self.x_label)
+        plt.title(self.custom_title if self.custom_title else self.title)
+        plt.grid(True)
+        plt.show()

mdadash/backend/analyses/energies.py

@@ -5,7 +5,6 @@
 from collections import deque
 
 import matplotlib.pyplot as plt
-import MDAnalysis as mda
 
 from mdadash.backend.widgets.base import WidgetBase
 
@@ -17,21 +16,73 @@ class EnergyWidgetBase:
     data_key = ""
     y_label = "Energy ( kJ / mol )"
 
-    def __init__(self):
-        self._steps = deque(maxlen=100)
-        self._values = deque(maxlen=100)
+    _inputs = [
+        {
+            "attribute": "maxlen",
+            "name": "Max values",
+            "description": "Max values to show in plot",
+            "type": "int",
+        },
+        {
+            "attribute": "title",
+            "name": "Title",
+            "description": "Title for the plot",
+            "type": "str",
+        },
+        {
+            "attribute": "x_type",
+            "name": "X-axis",
+            "type": "toggle",
+            "options": [
+                {"name": "Step", "value": "step"},
+                {"name": "Time", "value": "time"},
+            ],
+        },
+    ]
 
-    def run(self, u: mda.Universe):
-        ts = u.trajectory.ts
+    def __init__(self):
+        super().__init__()
+        self.title = self.name
+        self.maxlen = 100
+        self.steps = deque(maxlen=self.maxlen)
+        self.times = deque(maxlen=self.maxlen)
+        self.y_values = deque(maxlen=self.maxlen)
+        self.x_type = "step"
+        self.x_values = self.steps
+        self.x_label = "Step"
+
+    def _set_x_values(self):
+        """Set the values for the x-axis"""
+        if self.x_type == "step":
+            self.x_label = "Step"
+            self.x_values = self.steps
+        else:
+            self.x_label = "Time (ps)"
+            self.x_values = self.times
+
+    def on_input_change(self, attribute, _old_value, new_value):
+        """on_input_change handler"""
+        if attribute == "maxlen":
+            self.steps = deque(maxlen=new_value)
+            self.times = deque(maxlen=new_value)
+            self.y_values = deque(maxlen=new_value)
+            self._set_x_values()
+        elif attribute == "x_type":
+            self._set_x_values()
+
+    def run(self):
+        """run handler"""
+        ts = getattr(self, "u").trajectory.ts
         if self.data_key not in ts.data:
             return  # pragma no cover
-        self._values.append(ts.data[self.data_key])
-        self._steps.append(ts.data["step"])
+        self.steps.append(ts.data["step"])
+        self.times.append(ts.data["time"])
+        self.y_values.append(ts.data[self.data_key])
         # create plot
-        plt.plot(self._steps, self._values)
+        plt.plot(self.x_values, self.y_values)
         plt.ylabel(self.y_label)
-        plt.xlabel("Step")
-        plt.title(self.name, y=1.05)
+        plt.xlabel(self.x_label)
+        plt.title(self.title, y=1.05)
         plt.grid(True)
         plt.show()