Add pandas table representation for Protocols (#360)

peterhollender · google-labs-jules[bot] · arhowe00 · web-flow · commit 4913215a64b0 · 2025-07-28T15:21:45.000-04:00
* feat: Add to_table method to Protocol class This commit introduces a `to_table` method to the `Protocol` class, which returns a Pandas DataFrame summarizing the protocol's parameters. This is useful for displaying protocol information in a structured format. - Added `to_table` method to `Protocol` class. - Added `get_table` methods to `FocalPattern`, `SimSetup`, `DelayMethod`, `ApodizationMethod`, and `SegmentationMethod` classes and their subclasses. - Added tests for the new `to_table` method. - Added an example of the table output to the `to_table` method's docstring. * touch up to_table * add param constrains and target constraints for #360 * switch `get_table` to `to_table` #360 There was a mix of `get_table` and `to_table` already driving `protocol.to_table`. Since the `get_table` methods were all lower-level, I've switched everything to be `to_table`. * Update unit test #360 * Revert some seg_method tests #360 * Adjust import order * Fix `to_table` example output The example output table was not accurate * Fix ref_material not being referenced * Fix Uniform display typo #361 --------- Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com> Co-authored-by: Andrew Howe <arhowe00@gmail.com>
diff --git a/src/openlifu/bf/apod_methods/apodmethod.py b/src/openlifu/bf/apod_methods/apodmethod.py
@@ -5,6 +5,7 @@
 from typing import Any
 
 import numpy as np
+import pandas as pd
 import xarray as xa
 
 from openlifu.bf import apod_methods
@@ -30,3 +31,12 @@ def from_dict(d):
         module_dict = apod_methods.__dict__
         class_constructor = module_dict[short_classname]
         return class_constructor(**d)
+
+    @abstractmethod
+    def to_table(self) -> pd.DataFrame:
+        """
+        Get a table of the apodization method parameters
+
+        :returns: Pandas DataFrame of the apodization method parameters
+        """
+        pass
diff --git a/src/openlifu/bf/apod_methods/maxangle.py b/src/openlifu/bf/apod_methods/maxangle.py
@@ -4,6 +4,7 @@
 from typing import Annotated
 
 import numpy as np
+import pandas as pd
 import xarray as xa
 
 from openlifu.bf.apod_methods import ApodizationMethod
@@ -36,3 +37,13 @@ def calc_apodization(self, arr: Transducer, target: Point, params: xa.Dataset, t
         apod = np.zeros(arr.numelements())
         apod[angles <= self.max_angle] = 1
         return apod
+
+    def to_table(self) -> pd.DataFrame:
+        """
+        Get a table of the apodization method parameters
+
+        :returns: Pandas DataFrame of the apodization method parameters
+        """
+        records = [{"Name": "Type", "Value": "Max Angle", "Unit": ""},
+                   {"Name": "Max Angle", "Value": self.max_angle, "Unit": self.units}]
+        return pd.DataFrame.from_records(records)
diff --git a/src/openlifu/bf/apod_methods/piecewiselinear.py b/src/openlifu/bf/apod_methods/piecewiselinear.py
@@ -4,6 +4,7 @@
 from typing import Annotated
 
 import numpy as np
+import pandas as pd
 import xarray as xa
 
 from openlifu.bf.apod_methods import ApodizationMethod
@@ -46,3 +47,16 @@ def calc_apodization(self, arr: Transducer, target: Point, params: xa.Dataset, t
         f = ((self.zero_angle - angles) / (self.zero_angle - self.rolloff_angle))
         apod = np.maximum(0, np.minimum(1, f))
         return apod
+
+    def to_table(self) -> pd.DataFrame:
+        """
+        Get a table of the apodization method parameters
+
+        :returns: Pandas DataFrame of the apodization method parameters
+        """
+        records = [
+            {"Name": "Type", "Value": "Piecewise-Linear", "Unit": ""},
+            {"Name": "Zero Angle", "Value": self.zero_angle, "Unit": self.units},
+            {"Name": "Rolloff Angle", "Value": self.rolloff_angle, "Unit": self.units},
+        ]
+        return pd.DataFrame.from_records(records)
diff --git a/src/openlifu/bf/apod_methods/uniform.py b/src/openlifu/bf/apod_methods/uniform.py
@@ -4,6 +4,7 @@
 from typing import Annotated
 
 import numpy as np
+import pandas as pd
 import xarray as xa
 
 from openlifu.bf.apod_methods import ApodizationMethod
@@ -19,3 +20,13 @@ class Uniform(ApodizationMethod):
 
     def calc_apodization(self, arr: Transducer, target: Point, params: xa.Dataset, transform:np.ndarray | None=None):
         return np.full(arr.numelements(), self.value)
+
+    def to_table(self):
+        """
+        Get a table of the apodization method parameters
+
+        :returns: Pandas DataFrame of the apodization method parameters
+        """
+        records = [{"Name": "Type", "Value": "Uniform", "Unit": ""},
+                   {"Name": "Value", "Value": self.value, "Unit": ""}]
+        return pd.DataFrame.from_records(records)
diff --git a/src/openlifu/bf/delay_methods/delaymethod.py b/src/openlifu/bf/delay_methods/delaymethod.py
@@ -4,6 +4,7 @@
 from dataclasses import dataclass
 
 import numpy as np
+import pandas as pd
 import xarray as xa
 
 from openlifu.bf import delay_methods
@@ -29,3 +30,12 @@ def from_dict(d):
         module_dict = delay_methods.__dict__
         class_constructor = module_dict[short_classname]
         return class_constructor(**d)
+
+    @abstractmethod
+    def to_table(self) -> pd.DataFrame:
+        """
+        Get a table of the delay method parameters
+
+        :returns: Pandas DataFrame of the delay method parameters
+        """
+        pass
diff --git a/src/openlifu/bf/delay_methods/direct.py b/src/openlifu/bf/delay_methods/direct.py
@@ -4,6 +4,7 @@
 from typing import Annotated
 
 import numpy as np
+import pandas as pd
 import xarray as xa
 
 from openlifu.bf.delay_methods import DelayMethod
@@ -35,3 +36,13 @@ def calc_delays(self, arr: Transducer, target: Point, params: xa.Dataset | None=
         tof = dists / c
         delays = max(tof) - tof
         return delays
+
+    def to_table(self) -> pd.DataFrame:
+        """
+        Get a table of the delay method parameters
+
+        :returns: Pandas DataFrame of the delay method parameters
+        """
+        records = [{"Name": "Type", "Value": "Direct", "Unit": ""},
+                   {"Name": "Default Sound Speed", "Value": self.c0, "Unit": "m/s"}]
+        return pd.DataFrame.from_records(records)
diff --git a/src/openlifu/bf/focal_patterns/focal_pattern.py b/src/openlifu/bf/focal_patterns/focal_pattern.py
@@ -4,6 +4,8 @@
 from dataclasses import dataclass
 from typing import Annotated
 
+import pandas as pd
+
 from openlifu.bf import focal_patterns
 from openlifu.geo import Point
 from openlifu.util.annotations import OpenLIFUFieldData
@@ -72,3 +74,12 @@ def from_dict(d):
         module_dict = focal_patterns.__dict__
         class_constructor = module_dict[short_classname]
         return class_constructor(**d)
+
+    @abstractmethod
+    def to_table(self) -> pd.DataFrame:
+        """
+        Get a table of the focal pattern parameters
+
+        :returns: Pandas DataFrame of the focal pattern parameters
+        """
+        pass
diff --git a/src/openlifu/bf/focal_patterns/single.py b/src/openlifu/bf/focal_patterns/single.py
@@ -2,6 +2,8 @@
 
 from dataclasses import dataclass
 
+import pandas as pd
+
 from openlifu.bf.focal_patterns import FocalPattern
 from openlifu.geo import Point
 
@@ -29,3 +31,13 @@ def num_foci(self):
         :returns: Number of foci (1)
         """
         return 1
+
+    def to_table(self) -> pd.DataFrame:
+        """
+        Get a table of the focal pattern parameters
+
+        :returns: Pandas DataFrame of the focal pattern parameters
+        """
+        records = [{"Name": "Type", "Value": "Single Point", "Unit": ""},
+                   {"Name": "Target Pressure", "Value": self.target_pressure, "Unit": self.units}]
+        return pd.DataFrame.from_records(records)
diff --git a/src/openlifu/bf/focal_patterns/wheel.py b/src/openlifu/bf/focal_patterns/wheel.py
@@ -4,6 +4,7 @@
 from typing import Annotated
 
 import numpy as np
+import pandas as pd
 
 from openlifu.bf.focal_patterns import FocalPattern
 from openlifu.geo import Point
@@ -70,3 +71,18 @@ def num_foci(self) -> int:
         :returns: Number of foci
         """
         return int(self.center) + self.num_spokes
+
+    def to_table(self) -> pd.DataFrame:
+        """
+        Get a table of the focal pattern parameters
+
+        :returns: Pandas DataFrame of the focal pattern parameters
+        """
+        records = [
+            {"Name": "Type", "Value": "Wheel", "Unit": ""},
+            {"Name": "Target Pressure", "Value": self.target_pressure, "Unit": self.units},
+            {"Name": "Center", "Value": self.center, "Unit": ""},
+            {"Name": "Number of Spokes", "Value": self.num_spokes, "Unit": ""},
+            {"Name": "Spoke Radius", "Value": self.spoke_radius, "Unit": self.distance_units},
+        ]
+        return pd.DataFrame.from_records(records)
diff --git a/src/openlifu/bf/pulse.py b/src/openlifu/bf/pulse.py
@@ -51,7 +51,7 @@ def calc_time(self, dt: float):
         """
         return np.arange(0, self.duration, dt)
 
-    def get_table(self):
+    def to_table(self) -> pd.DataFrame:
         """
         Get a table of the pulse parameters
 
diff --git a/src/openlifu/bf/sequence.py b/src/openlifu/bf/sequence.py
@@ -39,7 +39,7 @@ def __post_init__(self):
         if self.pulse_train_count <= 0:
             raise ValueError("Pulse train count must be positive")
 
-    def get_table(self) -> pd.DataFrame:
+    def to_table(self) -> pd.DataFrame:
         """
         Get a table of the sequence parameters
 
diff --git a/src/openlifu/plan/param_constraint.py b/src/openlifu/plan/param_constraint.py
@@ -3,6 +3,8 @@
 from dataclasses import dataclass
 from typing import Annotated, Literal, Tuple
 
+import pandas as pd
+
 from openlifu.util.annotations import OpenLIFUFieldData
 from openlifu.util.dict_conversion import DictMixin
 
@@ -78,3 +80,16 @@ def get_status(self, value: float) -> str:
 
     def get_status_symbol(self, value: float) -> str:
         return PARAM_STATUS_SYMBOLS[self.get_status(value)]
+
+    def to_table(self) -> pd.DataFrame:
+        """Convert the parameter constraint to a table format."""
+        records = []
+        if self.operator in ['<', '<=', '>', '>='] or self.operator in ['within', 'inside', 'outside', 'outside_inclusive']:
+            value_template = f"value {self.operator} {{value}}"
+        else:
+            raise ValueError(f"Unsupported operator: {self.operator}")
+        if self.warning_value is not None:
+            records.append({"Name": "Warn if not", "Value": value_template.format(value=self.warning_value), "Unit": ""})
+        if self.error_value is not None:
+            records.append({"Name": "Error if not", "Value": value_template.format(value=self.error_value), "Unit": ""})
+        return pd.DataFrame.from_records(records)
diff --git a/src/openlifu/plan/protocol.py b/src/openlifu/plan/protocol.py
@@ -11,6 +11,7 @@
 from typing import Annotated, Any, Dict, List, Tuple
 
 import numpy as np
+import pandas as pd
 import xarray as xa
 
 from openlifu import bf, geo, seg, sim, xdc
@@ -160,6 +161,48 @@ def to_file(self, filename: str):
         with open(filename, 'w') as file:
             file.write(self.to_json(compact=False))
 
+    def to_table(self) -> pd.DataFrame:
+        """
+        Return a table of the most important protocol parameters
+
+        Example output:
+            ```
+            Category      Name            Value Unit
+            0              ID             example_protocol
+            1            Name             Example protocol
+            2           Description  Example protocol created 30-Jan-2024 09:16:02
+            3       Pulse       Frequency               500000.0   Hz
+            4       Pulse       Amplitude              1.0   AU
+            5       Pulse        Duration          0.00002    s
+            6    Sequence  Pulse Interval              0.1    s
+            ```
+        """
+        records = [
+            {"Category":"", "Name": "ID", "Value": self.id, "Unit": ""},
+            {"Category":"", "Name": "Name", "Value": self.name, "Unit": ""},
+            {"Category":"", "Name": "Description", "Value": self.description, "Unit": ""},
+        ]
+        table = pd.DataFrame.from_records(records)
+
+        def _append_subtable(category_name, sub_df):
+            sub_df.insert(0, 'Category', category_name)
+            return pd.concat([table, sub_df], ignore_index=True)
+
+        table = _append_subtable("Pulse", self.pulse.to_table())
+        table = _append_subtable("Sequence", self.sequence.to_table())
+        table = _append_subtable("Focal Pattern", self.focal_pattern.to_table())
+        table = _append_subtable("Delay Method", self.delay_method.to_table())
+        table = _append_subtable("Apodization Method", self.apod_method.to_table())
+        table = _append_subtable("Segmentation Method", self.seg_method.to_table())
+        table = _append_subtable("Simulation Setup", self.sim_setup.to_table())
+        for tc in self.target_constraints:
+            table = _append_subtable("Target Constraints", tc.to_table())
+        for param_id, param_constraint in self.param_constraints.items():
+            tp = param_constraint.to_table()
+            tp["Value"] = tp["Value"].str.replace("value", param_id)
+            table = _append_subtable("Parameter Constraints", tp)
+        return table
+
 
     def check_target(self, target: Point):
         """
diff --git a/src/openlifu/plan/target_constraints.py b/src/openlifu/plan/target_constraints.py
@@ -4,6 +4,8 @@
 from dataclasses import dataclass
 from typing import Annotated
 
+import pandas as pd
+
 from openlifu.util.annotations import OpenLIFUFieldData
 from openlifu.util.dict_conversion import DictMixin
 from openlifu.util.units import getunittype
@@ -56,3 +58,14 @@ def check_bounds(self, pos: float):
         if (pos < self.min) or (pos > self.max):
             logging.error(msg=f"The position {pos} at dimension {self.name} is not within bounds [{self.min}, {self.max}]!")
             raise ValueError(f"The position {pos} at dimension {self.name} is not within bounds [{self.min}, {self.max}]!")
+
+    def to_table(self) -> pd.DataFrame:
+        """
+        Get a table of the target constraints parameters.
+
+        :returns: Pandas DataFrame of the target constraints parameters
+        """
+        records = [
+            {"Name": self.name, "Value": f"({self.min},{self.max})", "Unit": self.units},
+        ]
+        return pd.DataFrame.from_records(records)
diff --git a/src/openlifu/seg/seg_method.py b/src/openlifu/seg/seg_method.py
@@ -6,6 +6,7 @@
 from typing import Annotated, Any
 
 import numpy as np
+import pandas as pd
 import xarray as xa
 
 from openlifu.seg.material import MATERIALS, PARAM_INFO, Material
@@ -99,3 +100,12 @@ def _ref_segment(self, coords: xa.Coordinates):
         sz = list(coords.sizes.values())
         seg = xa.DataArray(np.full(sz, m_idx, dtype=int), coords=coords)
         return seg
+
+    @abstractmethod
+    def to_table(self) -> pd.DataFrame:
+        """
+        Get a table of the segmentation method parameters
+
+        :returns: Pandas DataFrame of the segmentation method parameters
+        """
+        pass
diff --git a/src/openlifu/seg/seg_methods/uniform.py b/src/openlifu/seg/seg_methods/uniform.py
diff --git a/src/openlifu/sim/sim_setup.py b/src/openlifu/sim/sim_setup.py
diff --git a/tests/test_protocol.py b/tests/test_protocol.py
