added show_workflow utils function and use it in the tutorial

Author: tclose

docs/source/tutorial/6-workflow.ipynb

@@ -29,6 +29,7 @@
    "outputs": [],
    "source": [
     "from pydra.compose import workflow, python\n",
+    "from pydra.utils import show_workflow, print_help\n",
     "\n",
     "\n",
     "# Example python tasks\n",
@@ -59,7 +60,10 @@
     "def BasicWorkflow(a, b):\n",
     "    add = workflow.add(Add(a=a, b=b))\n",
     "    mul = workflow.add(Mul(a=add.out, b=b))\n",
-    "    return mul.out"
+    "    return mul.out\n",
+    "\n",
+    "\n",
+    "show_workflow(BasicWorkflow, figsize=(2, 2.5))"
    ]
   },
   {
@@ -109,7 +113,10 @@
     "        )(in_video=add_watermark.out_video, width=1280, height=720)\n",
     "    ).out_video\n",
     "\n",
-    "    return output_video  # test implicit detection of output name"
+    "    return output_video  # test implicit detection of output name\n",
+    "\n",
+    "\n",
+    "show_workflow(ShellWorkflow, figsize=(2.5, 3))"
    ]
   },
   {
@@ -136,10 +143,13 @@
     "def SplitWorkflow(a: list[int], b: list[float]) -> list[float]:\n",
     "    # Multiply over all combinations of the elements of a and b, then combine the results\n",
     "    # for each a element into a list over each b element\n",
-    "    mul = workflow.add(Mul().split(x=a, y=b).combine(\"x\"))\n",
+    "    mul = workflow.add(Mul().split(a=a, b=b).combine(\"a\"))\n",
     "    # Sume the multiplications across all all b elements for each a element\n",
     "    sum = workflow.add(Sum(x=mul.out))\n",
-    "    return sum.out"
+    "    return sum.out\n",
+    "\n",
+    "\n",
+    "show_workflow(SplitWorkflow, figsize=(2, 2.5))"
    ]
   },
   {
@@ -157,10 +167,13 @@
    "source": [
     "@workflow.define\n",
     "def SplitThenCombineWorkflow(a: list[int], b: list[float], c: float) -> list[float]:\n",
-    "    mul = workflow.add(Mul().split(x=a, y=b))\n",
-    "    add = workflow.add(Add(x=mul.out, y=c).combine(\"Mul.x\"))\n",
+    "    mul = workflow.add(Mul().split(a=a, b=b))\n",
+    "    add = workflow.add(Add(a=mul.out, b=c).combine(\"Mul.a\"))\n",
     "    sum = workflow.add(Sum(x=add.out))\n",
-    "    return sum.out"
+    "    return sum.out\n",
+    "\n",
+    "\n",
+    "show_workflow(SplitThenCombineWorkflow, figsize=(3, 3.5))"
    ]
   },
   {
@@ -214,7 +227,10 @@
     "        )(in_video=handbrake_input, width=1280, height=720)\n",
     "    ).out_video\n",
     "\n",
-    "    return output_video  # test implicit detection of output name"
+    "    return output_video  # test implicit detection of output name\n",
+    "\n",
+    "\n",
+    "show_workflow(ConditionalWorkflow(watermark_dims=(10, 10)), figsize=(2.5, 3))"
    ]
   },
   {
@@ -238,15 +254,18 @@
     "\n",
     "@workflow.define\n",
     "def RecursiveNestedWorkflow(a: float, depth: int) -> float:\n",
-    "    add = workflow.add(Add(x=a, y=1))\n",
+    "    add = workflow.add(Add(a=a, b=1))\n",
     "    decrement_depth = workflow.add(Subtract(x=depth, y=1))\n",
     "    if depth > 0:\n",
     "        out_node = workflow.add(\n",
     "            RecursiveNestedWorkflow(a=add.out, depth=decrement_depth.out)\n",
     "        )\n",
     "    else:\n",
     "        out_node = add\n",
-    "    return out_node.out"
+    "    return out_node.out\n",
+    "\n",
+    "\n",
+    "print_help(RecursiveNestedWorkflow)"
    ]
   },
   {
@@ -327,7 +346,10 @@
     "            Mp4Handbrake(in_video=add_watermark.out_video, width=1280, height=720),\n",
     "        )  # The type of the input video is now correct\n",
     "\n",
-    "    return handbrake.output_video"
+    "    return handbrake.out_video\n",
+    "\n",
+    "\n",
+    "show_workflow(TypeErrorWorkflow, plot_type=\"detailed\")"
    ]
   },
   {
@@ -372,14 +394,17 @@
     "\n",
     "    wf = workflow.this()\n",
     "\n",
-    "    add = wf.add(Add(x=a, y=b), name=\"addition\")\n",
-    "    mul = wf.add(python.define(Mul, outputs={\"out\": float})(x=add.z, y=b))\n",
-    "    divide = wf.add(Divide(x=wf[\"addition\"].lzout.z, y=mul.out), name=\"division\")\n",
+    "    add = wf.add(Add(a=a, b=b), name=\"addition\")\n",
+    "    mul = wf.add(Mul(a=add.out, b=b))\n",
+    "    divide = wf.add(Divide(x=wf[\"addition\"].lzout.out, y=mul.out), name=\"division\")\n",
     "\n",
     "    # Alter one of the inputs to a node after it has been initialised\n",
-    "    wf[\"Mul\"].inputs.y *= 2\n",
+    "    wf[\"Mul\"].inputs.b *= 2\n",
     "\n",
-    "    return mul.out, divide.divided"
+    "    return mul.out, divide.divided\n",
+    "\n",
+    "\n",
+    "show_workflow(DirectAccesWorkflow(b=1), plot_type=\"detailed\")"
    ]
   },
   {
@@ -410,16 +435,19 @@
     "\n",
     "    wf = workflow.this()\n",
     "\n",
-    "    add = wf.add(Add(x=a, y=b), name=\"addition\")\n",
-    "    mul = wf.add(python.define(Mul, outputs={\"out\": float})(x=add.z, y=b))\n",
-    "    divide = wf.add(Divide(x=wf[\"addition\"].lzout.z, y=mul.out), name=\"division\")\n",
+    "    add = wf.add(Add(a=a, b=b), name=\"addition\")\n",
+    "    mul = wf.add(Mul(a=add.out, b=b))\n",
+    "    divide = wf.add(Divide(x=wf[\"addition\"].lzout.out, y=mul.out), name=\"division\")\n",
     "\n",
     "    # Alter one of the inputs to a node after it has been initialised\n",
-    "    wf[\"Mul\"].inputs.y *= 2\n",
+    "    wf[\"Mul\"].inputs.b *= 2\n",
     "\n",
     "    # Set the outputs of the workflow directly\n",
     "    wf.outputs.out1 = mul.out\n",
-    "    wf.outputs.out2 = divide.divided"
+    "    wf.outputs.out2 = divide.divided\n",
+    "\n",
+    "\n",
+    "show_workflow(SetOutputsOfWorkflow(b=3), plot_type=\"detailed\")"
    ]
   },
   {
@@ -514,13 +542,13 @@
     "    return output_conversion.out_file\n",
     "\n",
     "\n",
-    "test_dir = tempfile.mkdtemp()\n",
+    "test_dir = Path(tempfile.mkdtemp())\n",
     "\n",
     "nifti_file = Nifti1.sample(test_dir, seed=0)\n",
     "\n",
     "wf = ToyMedianThreshold(in_image=nifti_file)\n",
     "\n",
-    "outputs = wf()\n",
+    "outputs = wf(cache_dir=test_dir / \"cache\")\n",
     "\n",
     "print(outputs)"
    ]

docs/source/tutorial/7-canonical-form.ipynb

@@ -230,13 +230,16 @@
     "        return mul.out\n",
     "\n",
     "    class Outputs(workflow.Outputs):\n",
-    "        out: float"
+    "        out: float\n",
+    "\n",
+    "\n",
+    "print_help(CanonicalWorkflowTask)"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "wf12",
+   "display_name": "wf13",
    "language": "python",
    "name": "python3"
   },
@@ -250,7 +253,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.5"
+   "version": "3.13.1"
   }
  },
  "nbformat": 4,

pydra/utils/__init__.py

@@ -2,6 +2,7 @@
     task_fields,
     fields_dict,
     plot_workflow,
+    show_workflow,
     task_help,
     print_help,
 )
@@ -11,6 +12,7 @@
     "__version__",
     "task_fields",
     "plot_workflow",
+    "show_workflow",
     "task_help",
     "print_help",
     "fields_dict",

pydra/utils/general.py

@@ -7,6 +7,7 @@
 import re
 import attrs
 import ast
+import tempfile
 import importlib
 import types
 import sysconfig
@@ -204,15 +205,20 @@ def plot_workflow(
     plot_type: str = "simple",
     export: ty.Sequence[str] | None = None,
     name: str | None = None,
-    output_dir: Path | None = None,
-    lazy: ty.Sequence[str] | ty.Set[str] = (),
-):
+    lazy: ty.Sequence[str] | ty.Set[str] | None = None,
+) -> Path | tuple[Path, list[Path]]:
     """creating a graph - dotfile and optionally exporting to other formats"""
     from pydra.engine.workflow import Workflow
 
+    if inspect.isclass(workflow_task):
+        workflow_task = workflow_task()
+
     # Create output directory
     out_dir.mkdir(parents=True, exist_ok=True)
 
+    if lazy is None:
+        lazy = [n for n, v in attrs_values(workflow_task).items() if v is attrs.NOTHING]
+
     # Construct the workflow object with all of the fields lazy
     wf = Workflow.construct(workflow_task, lazy=lazy)
 
@@ -245,6 +251,61 @@ def plot_workflow(
         return dotfile, formatted_dot
 
 
+def show_workflow(
+    workflow_task: "workflow.Task",
+    plot_type: str = "simple",
+    lazy: ty.Sequence[str] | ty.Set[str] | None = None,
+    use_lib: str | None = None,
+    figsize: tuple[int, int] | None = None,
+    **kwargs,
+) -> None:
+    """creating a graph and showing it"""
+    out_dir = Path(tempfile.mkdtemp())
+    png_graph = plot_workflow(
+        workflow_task,
+        out_dir=out_dir,
+        plot_type=plot_type,
+        export="png",
+        lazy=lazy,
+    )[1][0]
+
+    if use_lib in ("matplotlib", None):
+        try:
+            import matplotlib.pyplot as plt
+            from matplotlib.image import imread
+        except ImportError:
+            if use_lib == "matplotlib":
+                raise ImportError(
+                    "Please install either matplotlib to display the workflow image."
+                )
+        else:
+            use_lib = "matplotlib"
+
+            # Read the image
+            img = imread(png_graph)
+
+            if figsize is not None:
+                plt.figure(figsize=figsize)
+            # Display the image
+            plt.imshow(img, **kwargs)
+            plt.axis("off")
+            plt.show()
+
+    if use_lib in ("PIL", None):
+        try:
+            from PIL import Image
+        except ImportError:
+            msg = " or matplotlib" if use_lib is None else ""
+            raise ImportError(
+                f"Please install either Pillow{msg} to display the workflow image."
+            )
+        # Open the PNG image
+        img = Image.open(png_graph)
+
+        # Display the image
+        img.show(**kwargs)
+
+
 def attrs_fields(task, exclude_names=()) -> list[attrs.Attribute]:
     """Get the fields of a task, excluding some names."""
     return [field for field in task.__attrs_attrs__ if field.name not in exclude_names]

pyproject.toml

@@ -37,7 +37,7 @@ classifiers = [
 dynamic = ["version"]
 
 [project.optional-dependencies]
-dev = ["black", "pre-commit", "pydra[test]"]
+dev = ["black", "pre-commit", "pydra[test]", "matplotlib"]
 doc = [
     "fileformats-extras >= v0.15.0a6",
     "fileformats-medimage >= v0.10.0a2",