feat: visualize transform chains (#298)

jokasimr · jl-wynen · web-flow · commit 1ca907d98df2 · 2026-03-02T09:21:51.000+01:00
* feat: visualize transform chains

* fix: add cycle detection in .compute

* feat: add axis and magnitude

* fix

* fix: make circular graph not raise error and missing keys not warn

* Update src/scippnexus/nxtransformations.py

Co-authored-by: Jan-Lukas Wynen &lt;j-l.wynen@hotmail.de&gt;

* fix: refactor try catch more local

* deps

* fix: display data of data arrays

* fix: add offset vector to visualization

---------

Co-authored-by: Jan-Lukas Wynen &lt;j-l.wynen@hotmail.de&gt;
diff --git a/pyproject.toml b/pyproject.toml
@@ -39,6 +39,7 @@ dynamic = ["version"]
 
 [project.optional-dependencies]
 test = [
+    "graphviz",
     "pytest>=8.0",
 ]
 
diff --git a/requirements/basetest.in b/requirements/basetest.in
@@ -7,4 +7,5 @@
 # will not be touched by ``make_base.py``
 # --- END OF CUSTOM SECTION ---
 # The following was generated by 'tox -e deps', DO NOT EDIT MANUALLY!
+graphviz
 pytest>=8.0
diff --git a/requirements/basetest.txt b/requirements/basetest.txt
@@ -1,10 +1,12 @@
-# SHA1:a183f2aaeff6c4f418995809266f8825553a276e
+# SHA1:cd2186ab799909dcd3c4409d56716cd09984942e
 #
 # This file was generated by pip-compile-multi.
 # To update, run:
 #
 #    requirements upgrade
 #
+graphviz==0.21
+    # via -r basetest.in
 iniconfig==2.3.0
     # via pytest
 packaging==26.0
diff --git a/requirements/ci.txt b/requirements/ci.txt
@@ -5,7 +5,7 @@
 #
 #    requirements upgrade
 #
-cachetools==7.0.0
+cachetools==7.0.1
     # via tox
 certifi==2026.1.4
     # via requests
@@ -17,7 +17,7 @@ colorama==0.4.6
     # via tox
 distlib==0.4.0
     # via virtualenv
-filelock==3.20.3
+filelock==3.21.2
     # via
     #   tox
     #   virtualenv
@@ -32,7 +32,7 @@ packaging==26.0
     #   -r ci.in
     #   pyproject-api
     #   tox
-platformdirs==4.5.1
+platformdirs==4.7.0
     # via
     #   tox
     #   virtualenv
@@ -44,7 +44,7 @@ requests==2.32.5
     # via -r ci.in
 smmap==5.0.2
     # via gitdb
-tox==4.34.1
+tox==4.35.0
     # via -r ci.in
 urllib3==2.6.3
     # via requests
diff --git a/requirements/dev.txt b/requirements/dev.txt
@@ -69,7 +69,7 @@ jupyter-server==2.17.0
     #   notebook-shim
 jupyter-server-terminals==0.5.4
     # via jupyter-server
-jupyterlab==4.5.3
+jupyterlab==4.5.4
     # via -r dev.in
 jupyterlab-server==2.28.0
     # via jupyterlab
@@ -81,7 +81,7 @@ overrides==7.7.0
     # via jupyter-server
 pip-compile-multi==3.2.2
     # via -r dev.in
-pip-tools==7.5.2
+pip-tools==7.5.3
     # via pip-compile-multi
 plumbum==1.10.0
     # via copier
diff --git a/requirements/docs.txt b/requirements/docs.txt
@@ -12,8 +12,6 @@ alabaster==1.0.0
     # via sphinx
 annotated-types==0.7.0
     # via pydantic
-appnope==0.1.4
-    # via ipykernel
 asttokens==3.0.1
     # via stack-data
 attrs==25.4.0
@@ -64,7 +62,7 @@ idna==3.11
     # via requests
 imagesize==1.4.1
     # via sphinx
-ipykernel==7.1.0
+ipykernel==7.2.0
     # via -r docs.in
 ipython==9.10.0
     # via
@@ -148,13 +146,13 @@ packaging==26.0
     #   sphinx
 pandocfilters==1.5.1
     # via nbconvert
-parso==0.8.5
+parso==0.8.6
     # via jedi
 pexpect==4.9.0
     # via ipython
-pillow==12.1.0
+pillow==12.1.1
     # via matplotlib
-platformdirs==4.5.1
+platformdirs==4.7.0
     # via
     #   jupyter-core
     #   pooch
@@ -286,7 +284,7 @@ typing-inspection==0.4.2
     #   pydantic-settings
 urllib3==2.6.3
     # via requests
-wcwidth==0.5.3
+wcwidth==0.6.0
     # via prompt-toolkit
 webencodings==0.5.1
     # via
diff --git a/requirements/mypy.txt b/requirements/mypy.txt
@@ -6,7 +6,7 @@
 #    requirements upgrade
 #
 -r test.txt
-librt==0.7.8
+librt==0.8.0
     # via mypy
 mypy==1.19.1
     # via -r mypy.in
diff --git a/requirements/nightly.in b/requirements/nightly.in
@@ -3,6 +3,7 @@
 # The following was generated by 'tox -e deps', DO NOT EDIT MANUALLY!
 scipy>=1.10.0
 h5py>=3.12
+graphviz
 pytest>=8.0
 scipp
 --index-url=https://pypi.anaconda.org/scipp-nightly-wheels/simple/
diff --git a/requirements/nightly.txt b/requirements/nightly.txt
@@ -1,4 +1,4 @@
-# SHA1:b30ab65358588446f6086cfdb6e24c31a02a7b4a
+# SHA1:d31924dbe321c793dc4f8eb52fc8a939d3e513ab
 #
 # This file was generated by pip-compile-multi.
 # To update, run:
@@ -8,6 +8,8 @@
 --index-url https://pypi.anaconda.org/scipp-nightly-wheels/simple/
 --extra-index-url https://pypi.org/simple
 
+graphviz==0.21
+    # via -r nightly.in
 h5py==3.15.1
     # via -r nightly.in
 iniconfig==2.3.0
diff --git a/requirements/static.txt b/requirements/static.txt
@@ -9,13 +9,13 @@ cfgv==3.5.0
     # via pre-commit
 distlib==0.4.0
     # via virtualenv
-filelock==3.20.3
+filelock==3.21.2
     # via virtualenv
 identify==2.6.16
     # via pre-commit
 nodeenv==1.10.0
     # via pre-commit
-platformdirs==4.5.1
+platformdirs==4.7.0
     # via virtualenv
 pre-commit==4.5.1
     # via -r static.in
diff --git a/src/scippnexus/nxtransformations.py b/src/scippnexus/nxtransformations.py
@@ -260,11 +260,105 @@ class TransformationChain(DependsOn):
 
     transformations: sc.DataGroup = field(default_factory=sc.DataGroup)
 
+    def visualize(self, *, rankdir: str = 'LR'):
+        """
+        Visualizes the ``depends_on`` chain as a Graphviz Digraph.
+
+        Requires the optional `graphviz` Python package.
+        """
+        try:
+            from graphviz import Digraph
+        except Exception as e:  # pragma: no cover - optional dependency
+            raise ImportError(
+                "The 'graphviz' package is required to visualize transformation chains."
+            ) from e
+
+        dot = Digraph()
+        dot.attr(rankdir=rankdir)
+
+        def _fmt(x: sc.DataArray | sc.Variable) -> str:
+            x = x.data if isinstance(x, sc.DataArray) else x
+            return f'{x:c}'
+
+        def _fmt_vec3(x: sc.Variable) -> str:
+            vals = x.value.tolist()
+            return f'({vals[0]:.3g}, {vals[1]:.3g}, {vals[2]:.3g}) {x.unit}'
+
+        depends_on = self
+        prev = None
+        visited = []
+        while True:
+            path = depends_on.absolute_path()
+            if path is None:
+                # End of chain
+                terminal = '.'
+                dot.node(terminal, label=terminal, shape='doublecircle')
+                if prev is not None:
+                    dot.edge(prev, terminal, label='depends_on')
+                break
+            if path in visited:
+                # Loop detected
+                if prev is not None:
+                    dot.edge(prev, path, label='depends_on')
+                break
+            visited.append(path)
+            try:
+                transform = self.transformations[path]
+            except KeyError:
+                dot.node(
+                    path,
+                    label=f'{path}\\n[missing]',
+                    shape='box',
+                    color='red',
+                    fontcolor='red',
+                    style='rounded,dashed',
+                )
+                if prev is not None:
+                    dot.edge(prev, path, label='depends_on', color='red')
+                break
+            label = path
+            ttype = getattr(transform, 'transformation_type', None)
+            attrs = {}
+            if ttype in ('translation', 'rotation'):
+                label = f'{label}\\n[{ttype}]'
+                vector = getattr(transform, 'vector', None)
+                if vector is not None:
+                    label = f'{label}\\nvector={_fmt_vec3(vector)}'
+                value = getattr(transform, 'value', None)
+                if value is not None:
+                    if value.shape == ():
+                        label = f'{label}\\nvalue={_fmt(value)}'
+                    else:
+                        label = (
+                            f'{label}\\nvalue ∈ '
+                            f'[{_fmt(sc.nanmin(value))}, {_fmt(sc.nanmax(value))}]'
+                        )
+                offset = getattr(transform, 'offset', None)
+                if offset is not None:
+                    label = f'{label}\\noffset={_fmt_vec3(offset)}'
+                # Encode transform type in node shape/style for quick scanning
+                if ttype == 'translation':
+                    attrs.update({'shape': 'box'})
+                else:
+                    attrs.update({'shape': 'ellipse'})
+            dot.node(path, label=label, **attrs)
+            if prev is not None:
+                dot.edge(prev, path, label='depends_on')
+            prev = path
+            depends_on = transform.depends_on
+        return dot
+
     def compute(self) -> sc.Variable | sc.DataArray:
         depends_on = self
+        visited = []
         try:
             chain = []
             while (path := depends_on.absolute_path()) is not None:
+                if path in visited:
+                    raise ValueError(
+                        f'Circular depends_on chain detected: {[*visited, path]}'
+                    )
+                visited.append(path)
                 chain.append(self.transformations[path])
                 depends_on = chain[-1].depends_on
             transform = combine_transformations([t.build() for t in chain])
diff --git a/tests/nxtransformations_test.py b/tests/nxtransformations_test.py

Original file line number	Diff line number	Diff line change
`@@ -39,6 +39,7 @@ dynamic = ["version"]`
`39`	`39`
`40`	`40`	`[project.optional-dependencies]`
`41`	`41`	`test = [`
	`42`	`+ "graphviz",`
`42`	`43`	`"pytest>=8.0",`
`43`	`44`	`]`
`44`	`45`
Original file line number	Diff line number	Diff line change
`@@ -1,10 +1,12 @@`
`1`		`-# SHA1:a183f2aaeff6c4f418995809266f8825553a276e`
	`1`	`+# SHA1:cd2186ab799909dcd3c4409d56716cd09984942e`
`2`	`2`	`#`
`3`	`3`	`# This file was generated by pip-compile-multi.`
`4`	`4`	`# To update, run:`
`5`	`5`	`#`
`6`	`6`	`# requirements upgrade`
`7`	`7`	`#`
	`8`	`+graphviz==0.21`
	`9`	`+ # via -r basetest.in`
`8`	`10`	`iniconfig==2.3.0`
`9`	`11`	`# via pytest`
`10`	`12`	`packaging==26.0`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`	`# requirements upgrade`
`7`	`7`	`#`
`8`	`8`	`-r test.txt`
`9`		`-librt==0.7.8`
	`9`	`+librt==0.8.0`
`10`	`10`	`# via mypy`
`11`	`11`	`mypy==1.19.1`
`12`	`12`	`# via -r mypy.in`