API Reference¶

Initialize a new Computation.

:param default_executor: An executor :type default_executor: concurrent.futures.Executor, default ThreadPoolExecutor(max_workers=1)

Subscribe to batched computation changes.

Subscribers are notified in registration order, synchronously, on the thread that completes the outermost public mutation. A subscriber that raises is logged and skipped; it never interrupts the mutation or the other subscribers. A subscriber that itself mutates the computation causes a further event to be published once the current round finishes, up to a bounded number of cascades.

A callback with an object behind it --- anything carrying a __self__, whether written in Python or in C --- is held weakly, so subscribing obj.handler or events.append does not keep the owner alive; callers must retain it themselves. Everything else --- plain functions, lambdas, callable objects, :func:functools.partial --- is held strongly until unsubscribed, because callers commonly pass a throwaway closure that nothing else references.

The exception is an owner that supports no weak references at all, such as :class:list, :class:dict and :class:bytearray. There some_list.append falls back to a strong reference, which is a limitation of the type rather than a choice, and errs towards a subscription that keeps delivering over one that silently stops.

Subscriptions are not copied by :meth:copy and are not serialized.

:param callback: Function accepting a :class:ComputationEvent. :return: An idempotent, no-argument unsubscribe function.

Create an attribute view for a specific node path.

Adds or updates a node in a computation.

:param name: Name of the node to add. This may be any hashable object. :param func: Function to use to calculate the node if the node is a calculation node. By default, the input nodes to the function will be implied from the names of the function parameters. For example, a parameter called a would be taken from the node called a. This can be modified with the kwds parameter. :type func: Function, default None :param args: Specifies a list of nodes that will be used to populate arguments of the function positionally for a calculation node. e.g. If args is ['a', 'b', 'c'] then the function would be called with three parameters, taken from the nodes 'a', 'b' and 'c' respectively. :type args: List, default None :param kwds: Specifies a mapping from parameter name to the node that should be used to populate that parameter when calling the function for a calculation node. e.g. If args is {'x': 'a', 'y': 'b'} then the function would be called with parameters named 'x' and 'y', and their values would be taken from nodes 'a' and 'b' respectively. Each entry in the dictionary can be read as "take parameter [key] from node [value]". :type kwds: Dictionary, default None :param value: If given, the value is inserted into the node, and the node state set to UPTODATE. :type value: default None :param converter: Callable applied to any value on its way into the node. The node stores what the converter returns, both for values supplied by value, insert and insert_many, and for values the node calculates with func. A converter that raises leaves the node in state ERROR without storing the value, which is how a validator is written: check the value and return it unchanged when it is acceptable. The exception propagates to the caller when the value was supplied, but not when it was calculated, where the failure is reported as node state instead. A converter is saved by reference, like a node's function, so it must be importable: a module-level function or builtin round-trips, while a lambda raises SerializationError. :type converter: Callable, default None :param serialize: Whether the node should be serialized. Some objects cannot be serialized, in which case, set serialize to False :type serialize: boolean, default True :param inspect: Whether to use introspection to determine the arguments of the function, which can be slow. If this is not set, kwds and args must be set for the function to obtain parameters. :type inspect: boolean, default True :param group: Subgraph to render node in :type group: default None :param tags: Set of tags to apply to node :type tags: Iterable :param styles: Style to apply to node :type styles: String, default None :param executor: Name of executor to run node on :type executor: string :param store: Name of the blob store this node's value should be saved to, for values that belong somewhere other than the saved file --- a bucket, a database. The store itself is supplied at save and load time as stores={name: ...}, so the graph names a destination without holding a bucket or a credential. A profile override for the same node wins over this, which is what lets one computation be saved to that store in production and to a plain container in a test. :type store: string, default None

Set tags on a node or nodes. Ignored if tags are already set.

:param name: Node or nodes to set tag for :param tag: Tag to set

Clear tag on a node or nodes. Ignored if tags are not set.

:param name: Node or nodes to clear tags for :param tag: Tag to clear

Set styles on a node or nodes.

:param name: Node or nodes to set style for :param style: Style to set

Clear style on a node or nodes.

:param name: Node or nodes to clear styles for

Get metadata for a node.

Delete a node from a computation.

When nodes are explicitly deleted with delete_node, but are still depended on by other nodes, then they will be set to PLACEHOLDER status. In this case, if the nodes that depend on a PLACEHOLDER node are deleted, then the PLACEHOLDER node will also be deleted.

:param name: Name of the node to delete. If the node does not exist, a NonExistentNodeException will be raised.

Rename a node in a computation.

:param old_name: Node to rename, or a dictionary of nodes to rename, with existing names as keys, and new names as values :param new_name: New name for node.

Changes all nodes that use old_name as an input to use new_name instead.

Note that if old_name is an input to new_name, then that will not be changed, to try to avoid introducing circular dependencies, but other circular dependencies will not be checked.

If new_name does not exist, then it will be created as a PLACEHOLDER node.

:param old_name: :param new_name: :return:

Insert a value into a node of a computation.

Following insertation, the node will have state UPTODATE, and all its descendents will be COMPUTABLE or STALE.

If an attempt is made to insert a value into a node that does not exist, a NonExistentNodeException will be raised.

:param name: Name of the node to add. :param value: The value to be inserted into the node. :param force: Whether to force recalculation of descendents if node value and state would not be changed

Insert values into many nodes of a computation simultaneously.

Following insertation, the nodes will have state UPTODATE, and all their descendents will be COMPUTABLE or STALE. In the case of inserting many nodes, some of which are descendents of others, this ensures that the inserted nodes have correct status, rather than being set as STALE when their ancestors are inserted.

If an attempt is made to insert a value into a node that does not exist, a NonExistentNodeException will be raised, and none of the nodes will be inserted.

:param name_value_pairs: Each tuple should be a pair (name, value), where name is the name of the node to insert the value into. :type name_value_pairs: List of tuples

Insert values into another Computation object into this Computation object.

:param other: The computation object to take values from :type Computation: :param nodes: Only populate the nodes with the names provided in this list. By default, all nodes from the other Computation object that have corresponding nodes in this Computation object will be inserted :type nodes: List, default None

Set the state of a node and all its dependencies to STALE.

:param name: Name of the node to set as STALE.

Set the state of a node to PINNED.

:param name: Name of the node to set as PINNED. :param value: Value to pin to the node, if provided. :type value: default None

Unpin a node (state of node and all descendents will be set to STALE).

:param name: Name of the node to set as PINNED.

Inspect the entire graph for structural and readiness problems.

Validation does not execute functions or mutate the computation.

Describe the work needed to compute one or more targets.

Passing None plans the whole graph. Planning does not execute functions or mutate the computation.

:param targets: Target node, list of target nodes, or None for all nodes.

Get the arguments and keyword arguments for a node's function definition.

Compute a node or block and all necessary predecessors.

Following the computation, if successful, the target node, and all necessary ancestors that were not already UPTODATE will have been calculated and set to UPTODATE. Any node that did not need to be calculated will not have been recalculated.

If any nodes raises an exception, then the state of that node will be set to ERROR, and its value set to an object containing the exception object, as well as a traceback. This will not halt the computation, which will proceed as far as it can, until no more nodes that would be required to calculate the target are COMPUTABLE.

A block name computes every node below that path. Multiple node and block names may be supplied in a list or generator.

:param name: Name of the node or block to compute :param raise_exceptions: Whether to pass exceptions raised by node computations back to the caller :type raise_exceptions: Boolean, default False

Compute all nodes of a computation that can be computed.

Nodes that are already UPTODATE will not be recalculated. Following the computation, if successful, all nodes will have state UPTODATE, except UNINITIALIZED input nodes and PLACEHOLDER nodes.

If any nodes raises an exception, then the state of that node will be set to ERROR, and its value set to an object containing the exception object, as well as a traceback. This will not halt the computation, which will proceed as far as it can, until no more nodes are COMPUTABLE.

:param raise_exceptions: Whether to pass exceptions raised by node computations back to the caller :type raise_exceptions: Boolean, default False

Get a list of nodes in this computation.

:return: List of nodes.

Get a list of nodes in this computation.

:return: List of nodes.

Check if a node with the given name exists in the computation.

Check if a hierarchical path exists in the computation tree.

Get a list of descendent blocks and nodes.

Returns blocks and nodes that are descendents of the input node, e.g. for node 'foo', might return ['foo/bar', 'foo/baz'].

:param name: Name of node to get descendents for :return: List of descendent node names

Get the state of a node.

This can also be accessed using the attribute-style accessor s if name is a valid Python attribute name::

>>> comp = Computation()
>>> comp.add_node('foo', value=1)
>>> comp.state('foo')
<States.UPTODATE: 4>
>>> comp.s.foo
<States.UPTODATE: 4>

:param name: Name or names of the node to get state for :type name: Name or Names

Get the current value of a node.

This can also be accessed using the attribute-style accessor v if name is a valid Python attribute name::

>>> comp = Computation()
>>> comp.add_node('foo', value=1)
>>> comp.value('foo')
1
>>> comp.v.foo
1

:param name: Name or names of the node to get the value of :type name: Name or Names

Get the current value of a node.

This can also be accessed using the attribute-style accessor v if name is a valid Python attribute name::

>>> comp = Computation()
>>> comp.add_node('foo', value=1)
>>> comp.add_node('bar', lambda foo: foo + 1)
>>> comp.compute_and_get_value('bar')
2
>>> comp.x.bar
2

:param name: Name or names of the node to get the value of :type name: Name

Get the tags associated with a node.

>>> comp = Computation()
>>> comp.add_node('a', tags=['foo', 'bar'])
>>> sorted(comp.t.a)
['__serialize__', 'bar', 'foo']

:param name: Name or names of the node to get the tags of :return:

Get the names of nodes with a particular tag or tags.

:param tag: Tag or tags for which to retrieve nodes :return: Names of the nodes with those tags

Get the tags associated with a node.

>>> comp = Computation()
>>> comp.add_node('a', style='dot')
>>> comp.style.a
'dot'

:param name: Name or names of the node to get the tags of :return:

Get the state and current value of a node.

:param name: Name of the node to get the state and value of

Get the timing information for a node.

:param name: Name or names of the node to get the timing information of :return:

Get a dataframe containing the states and value of all nodes of computation.

::

>>> import loman
>>> comp = loman.Computation()
>>> comp.add_node('foo', value=1)
>>> comp.add_node('bar', value=2)
>>> comp.to_df()  # doctest: +NORMALIZE_WHITESPACE
               state  value
foo  States.UPTODATE      1
bar  States.UPTODATE      2

Get a dictionary containing the values of all nodes of a computation.

::

>>> import loman
>>> comp = loman.Computation()
>>> comp.add_node('foo', value=1)
>>> comp.add_node('bar', value=2)
>>> comp.to_dict()  # doctest: +ELLIPSIS
{NodeKey('foo'): 1, NodeKey('bar'): 2}

Get a list of the inputs for a node or set of nodes.

:param name: Name or names of nodes to get inputs for :return: If name is scalar, return a list of upstream nodes used as input. If name is a list, return a list of list of inputs.

Get all ancestor nodes of the specified nodes.

Get a list of the original non-computed inputs for a node or set of nodes.

:param names: Name or names of nodes to get inputs for :return: Return a list of original non-computed inputs that are ancestors of the input nodes

Get a list of the outputs for a node or set of nodes.

:param name: Name or names of nodes to get outputs for :return: If name is scalar, return a list of downstream nodes used as output. If name is a list, return a list of list of outputs.

Get all descendent nodes of the specified nodes.

Get final output nodes (nodes with no descendants) from the specified nodes.

Get the source code for a node.

Print the source code for a computation node.

Restrict a computation to the ancestors of a set of output nodes.

Excludes ancestors of a set of input nodes.

If the set of input_nodes that is specified is not sufficient for the set of output_nodes then additional nodes that are ancestors of the output_nodes will be included, but the input nodes specified will be input nodes of the modified Computation.

:param output_nodes: :param input_nodes: :return: None - modifies existing computation in place

Prepare computation for serialization by removing non-serializable nodes.

Restore computation from serialized state.

Serialize a computation to a file or file-like object.

.. deprecated:: Superseded by :meth:write_dill, and by :meth:save in turn. Kept because removing it would break callers without warning; it will go in a release that says so.

.. warning:: Not safe to call concurrently. It removes __getstate__ and __setstate__ from the class for the duration of the write, which is process-wide, so another thread pickling a Computation at the same moment gets the wrong representation. :meth:write_dill has no such problem, and :meth:save supersedes both.

:param file_: If string, writes to a file :type file_: File-like object, or string

Serialize a computation to a file or file-like object.

.. deprecated:: Use :meth:write_json instead. dill-based serialization will be removed in a future release.

:param file_: If string, writes to a file :type file_: File-like object, or string

Deserialize a computation from a file or file-like object.

.. deprecated:: Use :meth:read_json instead. dill-based serialization will be removed in a future release.

.. warning:: This method uses dill.load() which can execute arbitrary code. Only load files from trusted sources. Never load data from untrusted or unauthenticated sources as it may lead to arbitrary code execution.

:param file_: If string, writes to a file :type file_: File-like object, or string

Save this computation to path.

The default is a .loman file: one zip holding a manifest.json describing the graph, plus a blobs/ directory holding large values as binary. The manifest still records every value's shape, dtype and index type, so the file can be inspected without decoding any of the data.

::

comp.save('run.loman')                       # efficient, zipped
comp.save('run.loman', profile='readable')   # inline JSON, zipped
comp.save('run.json')                        # single JSON document
comp.save('run_dir', container='dir')        # same layout, unzipped

profile and container are independent. The profile decides whether a value's bytes are written inline or out of line; the container decides where they land. The one combination that cannot work is the efficient profile in the json container, which raises.

Prefer container='dir' when saving repeatedly --- updating one value in a zip rewrites the whole archive, at a cost that grows with its size, while a directory rewrites only the file that changed.

:param path: Destination path. A .json suffix selects the single document container; anything else defaults to a .loman zip. :param profile: "readable", "efficient" (the default), or a :class:~loman.serialization.profile.SerializationProfile. :param container: "zip", "dir" or "json". Inferred from path when omitted. :param stores: Named :class:~loman.serialization.blobs.BlobStore instances for values that belong somewhere other than the saved file --- a bucket, a database. A node is routed to one by add_node(store=...) or a profile override. The same names must be supplied to :meth:load. :param serializer: Optional custom serializer, for user-defined types.

Load a computation saved by :meth:save, in any container.

The container is detected from the file itself, so a .loman archive, a directory and a plain JSON document all load through this one call --- including documents written by earlier format versions.

.. warning:: Loading restores node functions, which means importing the modules the file names, or unpickling a dill blob out of it. Both run code chosen by the file. Only load files you trust, or pass allow_code=False.

:param path: Path to a .loman file, a container directory, or a JSON document. :param serializer: Optional custom serializer, matching the one used to save. :param allow_code: When false, callables are not resolved; values, structure, states and tags still load. :param stores: Named stores for values held outside the file. A saved file records a store's name but never its configuration, so it never contains a bucket or a credential --- and cannot resolve external values without the matching store being supplied here. :rtype: Computation

Serialize a computation to a JSON file or file-like object.

Custom types can be supported by passing a custom serializer — either a :class:~loman.serialization.computation.ComputationSerializer instance with extra transformers registered, or a subclass that overrides the transformer factory.

:param file_: Destination file path (str) or text-mode file-like object. :param serializer: Optional custom serializer. If None the default :class:~loman.serialization.computation.ComputationSerializer is used.

Deserialize a computation from a JSON file or file-like object.

.. warning:: Loading a computation restores its node functions, which means importing the modules the file names, or unpickling a dill blob out of it. Both run code chosen by the file. Only load files from sources you trust, or pass allow_code=False.

:param file_: Source file path (str) or text-mode file-like object. :param serializer: Optional custom serializer. If None the default :class:~loman.serialization.computation.ComputationSerializer is used. :param allow_code: When false, encoded callables are skipped rather than resolved, so no module named by the file is imported and no dill blob is unpickled. Values, structure, states and tags still load; every node's function and converter comes back as None, so the graph can be inspected but not recalculated. :rtype: Computation

Create a copy of a computation.

The copy is shallow. Any values in the new Computation's DAG will be the same object as this Computation's DAG. As new objects will be created by any further computations, this should not be an issue.

:rtype: Computation

Automatically add nodes to extract each element of a named tuple type.

It is often convenient for a calculation to return multiple values, and it is polite to do this a namedtuple rather than a regular tuple, so that later users have same name to identify elements of the tuple. It can also help make a computation clearer if a downstream computation depends on one element of such a tuple, rather than the entire tuple. This does not affect the computation per se, but it does make the intention clearer.

To avoid having to create many boiler-plate node definitions to expand namedtuples, the add_named_tuple_expansion method automatically creates new nodes for each element of a tuple. The convention is that an element called 'element', in a node called 'node' will be expanded into a new node called 'node.element', and that this will be applied for each element.

Example::

>>> from collections import namedtuple
>>> Coordinate = namedtuple('Coordinate', ['x', 'y'])
>>> comp = Computation()
>>> comp.add_node('c', value=Coordinate(1, 2))
>>> comp.add_named_tuple_expansion('c', Coordinate)
>>> comp.compute_all()
>>> comp.value('c.x')
1
>>> comp.value('c.y')
2

:param name: Node to cera :param namedtuple_type: Expected type of the node :type namedtuple_type: namedtuple class

Apply a graph to each element of iterable.

In turn, each element in the input_node of this graph will be inserted in turn into the subgraph's subgraph_input_node, then the subgraph's subgraph_output_node calculated. The resultant list, with an element or each element in input_node, will be inserted into result_node of this graph. In this way add_map_node is similar to map in functional programming.

:param result_node: The node to place a list of results in this graph :param input_node: The node to get a list input values from this graph :param subgraph: The graph to use to perform calculation for each element :param subgraph_input_node: The node in subgraph to insert each element in turn :param subgraph_output_node: The node in subgraph to read the result for each element

Prepend a prefix path to a node path.

Add a computation block as a subgraph to this computation.

keep_values defaults to True, so values already held by block are copied along with its structure: a block added this way is often a sub-model that has already been populated or calibrated, and would not be computable without them. The repeated-block utilities in :mod:loman.util default to False instead, because they stamp out many copies of one template. See :class:loman.util.RepeatedBlocks.

:param base_path: Parent path to add the block's nodes below :param block: Computation to copy into this computation :param keep_values: Whether to copy the block's current values :param links: Mapping from the block's relative input names to outer nodes :param metadata: Metadata to attach to the block path

Create a link between two nodes in the computation graph.

Draw a computation's current state using the GraphViz utility.

:param root: Optional PathType. Sub-block to draw :param cmap: Default: None :param colors: 'state' - colors indicate state. 'timing' - colors indicate execution time. Default: 'state'. :param shapes: None - ovals. 'type' - shapes indicate type. Default: None. :param graph_attr: Mapping of (attribute, value) pairs for the graph. For example graph_attr={'size': '"10,8"'} can control the size of the output graph :param node_attr: Mapping of (attribute, value) pairs set for all nodes. :param edge_attr: Mapping of (attribute, value) pairs set for all edges. :param collapse_all: Whether to collapse all blocks that aren't explicitly expanded.

Create an interactive notebook widget for this computation.

Requires the ui extra: pip install 'loman[ui]'. It is imported lazily, so ordinary use of Loman does not load AnyWidget or its notebook dependencies.

Arguments other than editable mirror :meth:draw, so the two are learnable together. The widget subscribes to this computation and follows it; comp.draw() and _repr_svg_ stay static pictures.

Note that colors="state" repaints in place, while any other colouring re-runs Graphviz on every change. See :class:~loman.ui.ComputationWidget for the details.

:param editable: Allow scalar input editing and computation controls. Expanding and collapsing blocks stays available either way. :param buildable: Allow the graph itself to be built in the widget: adding, redefining, renaming and deleting nodes. Off by default, and needs editable too, because defining a calculation node compiles and runs an expression typed in the browser inside this kernel. :param namespace: Globals a node built in the widget is compiled against, so its expression can use the notebook's own imports. Pass globals(). The default is an empty namespace, in which only builtins are in scope. :param fit_on_render: Scale the graph to fit the pane on every render, rather than opening at natural size. Useful when the shape of a large graph matters more than its labels. :param max_rendered_nodes: Refuse to open a block that would put more than this many nodes on screen. Does not cap the initial view. :param rankdir: Initial Graphviz layout direction, LR (default) or TB, toggled live from the toolbar. :return: A live widget subscribed to this computation.

Create and display a visualization of the computation graph.

Print tracebacks for every node with state "ERROR" in a Computation.

Create a computation from a class with decorated methods.

Injects dependencies into the nodes of the current computation where nodes are in a placeholder state.

(or all possible nodes when the 'force' parameter is set to True), using values provided in the 'dependencies' dictionary.

Each key in the 'dependencies' dictionary corresponds to a node identifier, and the associated value is the dependency object to inject. If the value is a callable, it will be added as a calc node.

:param dependencies: A dictionary where each key-value pair consists of a node identifier and its corresponding dependency object or a callable that returns the dependency object. :param force: A boolean flag that, when set to True, forces the replacement of existing node values with the ones provided in 'dependencies', regardless of their current state. Defaults to False. :return: None

Record the original exception's identity alongside its message.

Show the original exception's type so it is not mistaken for this one.

Initialize MapError with message and partial results.

Return string representation using path notation.

Remove a root prefix from this node key if it matches.

Join this node key with other names to create a new node key.

Join this node key with raw parts to create a new node key.

Join this node key with other to create a new node key.

Check if this node key is a descendant of another node key.

Prepend another node key to this one.

Return string representation for debugging.

Check equality with another NodeKey.

Get the root node key.

Find the common parent of two node keys.

Get all ancestor node keys from root to parent.

Return current, runnable, and blocked nodes as an execution table.

Return validation findings as one row per issue.

Initialise with an optional custom transformer.

Register a transformer or type with this serializer's transformer.

Accepts anything :meth:~loman.serialization.transformer.Transformer.register accepts: a :class:~loman.serialization.transformer.CustomTransformer instance, a :class:~loman.serialization.transformer.Transformable subclass, an attrs class, or a dataclass.

The same serializer instance must be used for both writing and reading, since the registration lives on the instance::

s = ComputationSerializer()
s.register(my_transformer)
comp.write_json('comp.json', serializer=s)
comp2 = Computation.read_json('comp.json', serializer=s)

Write comp to path.

:param path: Destination. A .json suffix implies the single-document container; anything else defaults to a .loman zip. :param profile: "readable", "efficient", or a :class:~loman.serialization.profile.SerializationProfile. Defaults to efficient, except in the json container where only readable is possible. :param container: "zip", "dir" or "json". Inferred from path when omitted. :param stores: Named :class:~loman.serialization.blobs.BlobStore instances that nodes may be routed to. A node names a store through add_node(store=...) or a profile override.

Read a computation from path, whatever container it uses.

:param stores: Named stores for blobs held outside the container. A saved file records a store's name but never its configuration, so a file with external blobs cannot resolve them unaided.

Serialize comp to fp (a text-mode file-like object).

Serialize comp and return a JSON string.

Always the readable single-document form: a string has nowhere to put out-of-line bytes.

Deserialize a Computation from fp (a text-mode file-like object).

:param allow_code: When false, node functions and converters are not restored. See :meth:loads.

Deserialize a Computation from a JSON string.

:param allow_code: When false, encoded callables are skipped rather than resolved, and every node's function and converter comes back as None. Restoring a callable means importing the module the file names, or unpickling a dill blob out of it --- both of which run code the file chose. Values, structure, states and tags still load, which is enough to inspect a graph from an untrusted source. Defaults to true, preserving existing behaviour.

Return whether a value of nbytes should be written out of line.

A transformer that cannot estimate its size passes None and is taken at its word that the value is worth storing out of line.

Return the override settings that apply to node.

Later matches win, so a more specific selector listed after a general one takes precedence --- the order the overrides were written in.

Resolve a relative name that must be a node inside every block.

The name may come from the template, or from a node an earlier feature already planned, so one feature can build on another's output. Features are planned in the order they are declared.

Resolve a relative name that must be an input node inside every block.

A node the template declares must be an input: replacing a calculation would silently discard it. A node an earlier feature planned is accepted as-is, since the template has nothing to say about it. A name the template never mentions is rejected, because it is usually a typo that would otherwise add a dead node to every block — pass create=True to allow it deliberately.

Bind a callback to the class a computation factory was defined from.

Returns anything that is not callable unchanged, so a plain node name passes through.

Describe the nodes to create, without changing anything.

Plan one result node gathering the same relative node from every block.

Plan one target node per key, linked or transformed from its source.

Plan one value node per key, holding that key.

Plan one shared outer node, linked into every block.

Plan an input node holding a fixed value.

Plan a node that takes its value from another node unchanged.

Plan a calculation node.

Create this node in a computation.

Call the wrapped function with the mapping's values, in order.

Initialize the graph view after dataclass construction.

Extract a subgraph with node transformations for visualization.

Refresh the visualization by rebuilding the graph structure.

Generate SVG representation of the visualization.

Open the visualization in a PDF viewer.