sobol_graph module¶

A network of uncertain variables representing their Sobol’ indices.

class gemseo_umdo.visualizations.sobol_graph.SobolGraph(first_order_indices, total_order_indices, second_order_indices, threshold=0.1, maximum_thickness=10.0)[source]¶

Bases: GraphView

A network of uncertain variables representing their Sobol’ indices.

A node represents an uncertain variable whose name is written inside, followed by its first-order and total-order Sobol’ indices.

The thickness of a node is proportional to the total-order Sobol’ index of the variable while the thickness of an edge is proportional to the second-order Sobol’ index of the corresponding pair of variables.

Args:

Note

All parameters are optional and can be changed under their corresponding attribute name after instance creation.

Initialize self. See help(type(self)) for accurate signature.

Parameters:

first_order_indices (Mapping[str, float]) – The first-order Sobol’ indices of the scalar inputs, shaped as {name: index}.
total_order_indices (Mapping[str, float]) – The total-order Sobol’ indices of the scalar inputs, shaped as {name: index}.
second_order_indices (Mapping[tuple[str, str], float]) – The second-order Sobol’ indices of the scalar inputs, shaped as {(name, other_name): index}.
threshold (float) –
The sensitivity threshold above which a second-order index is significant and the corresponding edge plotted.

By default it is set to 0.1.
maximum_thickness (float) –
The maximum thickness of a line.

By default it is set to 10.0.

class DefaultEdgeAttributeValues(color='black', fontcolor='black', penwidth='1.0')¶

Bases: object

The default values of the attributes of an edge.

Parameters:

color (str) –

By default it is set to “black”.
fontcolor (str) –

By default it is set to “black”.
penwidth (str) –

By default it is set to “1.0”.

color: str = 'black'¶: The default foreground color.

fontcolor: str = 'black'¶: The default font color.

penwidth: str = '1.0'¶: The default line thickness color.

class DefaultNodeAttributeValues(color='black', fillcolor='white', fontcolor='black', penwidth='1.0', style='filled')¶

Bases: object

The default values of the attributes of a node.

Parameters:

color (str) –

By default it is set to “black”.
fillcolor (str) –

By default it is set to “white”.
fontcolor (str) –

By default it is set to “black”.
penwidth (str) –

By default it is set to “1.0”.
style (str) –

By default it is set to “filled”.

color: str = 'black'¶: The default foreground color.

fillcolor: str = 'white'¶: The default background color.

fontcolor: str = 'black'¶: The default font color.

penwidth: str = '1.0'¶: The default line thickness color.

style: str = 'filled'¶: The default shape.

attr(kw=None, _attributes=None, **attrs)¶

Add a general or graph/node/edge attribute statement.

Parameters:

kw (str | None) – Attributes target (None or 'graph', 'node', 'edge').
attrs – Attributes to be set (must be strings, may be empty).

Return type:

None

See the usage examples in the User Guide.

clear(keep_attrs=False)¶

Reset content to an empty body, clear graph/node/egde_attr mappings.

Parameters:

keep_attrs (bool) –

preserve graph/node/egde_attr mappings

By default it is set to False.

Return type:

None

copy()¶

Return a copied instance of the object.

Returns:: An independent copy of the current object.

edge(tail_name, head_name, label=None, _attributes=None, **attrs)¶

Create an edge between two nodes.

Parameters:

tail_name (str) – Start node identifier (format: node[:port[:compass]]).
head_name (str) – End node identifier (format: node[:port[:compass]]).
label (str | None) – Caption to be displayed near the edge.
_attributes – The description is missing.
**attrs (str) – The description is missing.

Return type:

None

Note

The tail_name and head_name strings are separated by (optional) colon(s) into node name, port name, and compass (e.g. sw). See details in the User Guide.

edges(tail_head_iter)¶

Create a bunch of edges.

Parameters:: tail_head_iter – Iterable of (tail_name, head_name) pairs (format:node[:port[:compass]]).
Return type:: None

Note

The tail_name and head_name strings are separated by (optional) colon(s) into node name, port name, and compass (e.g. sw). See details in the User Guide.

classmethod from_analysis(analysis, output_name, output_component=0)[source]¶

Create the Sobol’ graph from a Sobol’ analysis.

Parameters:

analysis (SobolAnalysis) – A Sobol’ analysis.
output_name (str) – The name of the output.
output_component (int) –
The component of the output.

By default it is set to 0.

Returns:

The Sobol’ graph associated with this Sobol’ analysis.

Return type:

SobolGraph

hide_node(name)¶

Hide a node.

Parameters:: name (str) – The name of the node.
Return type:: None

node(name, label=None, _attributes=None, **attrs)¶

Create a node.

Parameters:

name (str) – Unique identifier for the node inside the source.
label (str | None) – Caption to be displayed (defaults to the node name).
_attributes – The description is missing.
**attrs (str) – The description is missing.

Return type:

None

pipe(format=None, renderer=None, formatter=None, neato_no_op=None, quiet=False, *, engine=None, encoding=None)¶

Return the source piped through the Graphviz layout command.

Parameters:

format (str | None) – The output format used for rendering ('pdf', 'png', etc.).
renderer (str | None) – The output renderer used for rendering ('cairo', 'gd', …).
formatter (str | None) – The output formatter used for rendering ('cairo', 'gd', …).
neato_no_op (bool | int | None) – Neato layout engine no-op flag.
quiet (bool) –
Suppress stderr output from the layout subprocess.

By default it is set to False.
engine (str | None) – Layout engine for rendering ('dot', 'neato', …).
encoding (str | None) – Encoding for decoding the stdout.

Returns:

Bytes or if encoding is given decoded string: (stdout of the layout command).

Raises:

ValueError – If engine, format, renderer, or formatter are unknown.
graphviz.RequiredArgumentError – If formatter is given but renderer is None.
graphviz.ExecutableNotFound – If the Graphviz dot executable is not found.
graphviz.CalledProcessError – If the returncode (exit status) of the rendering dot subprocess is non-zero.

Return type:

bytes | str

Example

>>> doctest_mark_exe()
>>> import graphviz
>>> source = 'graph { spam }'
>>> graphviz.Source(source, format='svg').pipe()[:14]
b'<?xml version='
>>> graphviz.Source(source, format='svg').pipe(encoding='ascii')[:14]
'<?xml version='
>>> graphviz.Source(source, format='svg').pipe(encoding='utf-8')[:14]
'<?xml version='

render(filename=None, directory=None, view=False, cleanup=False, format=None, renderer=None, formatter=None, neato_no_op=None, quiet=False, quiet_view=False, *, outfile=None, engine=None, raise_if_result_exists=False, overwrite_source=False)¶

Save the source to file and render with the Graphviz engine.

Parameters:

filename (PathLike | str | None) – Filename for saving the source (defaults to name + '.gv').s
directory (PathLike | str | None) – (Sub)directory for source saving and rendering.
view (bool) –
Open the rendered result with the default application.

By default it is set to False.
cleanup (bool) –
Delete the source file after successful rendering.

By default it is set to False.
format (str | None) – The output format used for rendering ('pdf', 'png', etc.).
renderer (str | None) – The output renderer used for rendering ('cairo', 'gd', …).
formatter (str | None) – The output formatter used for rendering ('cairo', 'gd', …).
neato_no_op (bool | int | None) – Neato layout engine no-op flag.
quiet (bool) –
Suppress stderr output from the layout subprocess.

By default it is set to False.
quiet_view (bool) –
Suppress stderr output from the viewer process (implies view=True, ineffective on Windows platform).

By default it is set to False.
outfile (PathLike | str | None) – Path for the rendered output file.
engine (str | None) – Layout engine for rendering ('dot', 'neato', …).
raise_if_result_exits – Raise graphviz.FileExistsError if the result file exists.
overwrite_source (bool) –
Allow dot to write to the file it reads from. Incompatible with raise_if_result_exists.

By default it is set to False.
raise_if_result_exists (bool) –

By default it is set to False.

Returns:

The (possibly relative) path of the rendered file.

Raises:

ValueError – If engine, format, renderer, or formatter are unknown.
graphviz.RequiredArgumentError – If formatter is given but renderer is None.
ValueError – If outfile is the same file as the source file unless overwite_source=True.
graphviz.ExecutableNotFound – If the Graphviz dot executable is not found.
graphviz.CalledProcessError – If the returncode (exit status) of the rendering dot subprocess is non-zero.
RuntimeError – If viewer opening is requested but not supported.

Return type:

str

Example

>>> doctest_mark_exe()
>>> import graphviz
>>> dot = graphviz.Graph(name='spam', directory='doctest-output')
>>> dot.render(format='png').replace('\\', '/')
'doctest-output/spam.gv.png'
>>> dot.render(outfile='spam.svg').replace('\\', '/')
'doctest-output/spam.svg'

Note

The layout command is started from the directory of filepath, so that references to external files (e.g. [image=images/camelot.png]) can be given as paths relative to the DOT source file.

save(filename=None, directory=None, *, skip_existing=False)¶

Save the DOT source to file. Ensure the file ends with a newline.

Parameters:

filename (PathLike | str | None) – Filename for saving the source (defaults to name + '.gv')
directory (PathLike | str | None) – (Sub)directory for source saving and rendering.
skip_existing (bool | None) –
Skip write if file exists (default: False).

By default it is set to False.

Returns:

The (possibly relative) path of the saved source file.

Return type:

str

subgraph(graph=None, name=None, comment=None, graph_attr=None, node_attr=None, edge_attr=None, body=None)¶

Add the current content of the given sole graph argument: as subgraph or return a context manager returning a new graph instance created with the given (name, comment, etc.) arguments whose content is added as subgraph when leaving the context manager’s with-block.

Parameters:

graph – An instance of the same kind (Graph, Digraph) as the current graph (sole argument in non-with-block use).
name (str | None) – Subgraph name (with-block use).
comment (str | None) – Subgraph comment (with-block use).
graph_attr – Subgraph-level attribute-value mapping (with-block use).
node_attr – Node-level attribute-value mapping (with-block use).
edge_attr – Edge-level attribute-value mapping (with-block use).
body – Verbatim lines to add to the subgraph body (with-block use).

See the usage examples in the User Guide.

When used as a context manager, the returned new graph instance uses strict=None and the parent graph’s values for directory, format, engine, and encoding by default.

Note

If the name of the subgraph begins with 'cluster' (all lowercase) the layout engine will treat it as a special cluster subgraph.

unflatten(stagger=None, fanout=False, chain=None)¶

Return a new Source instance with the source: piped through the Graphviz unflatten preprocessor.

Parameters:

stagger (int | None) – Stagger the minimum length of leaf edges between 1 and this small integer.
fanout (bool) –
Fanout nodes with indegree = outdegree = 1 when staggering (requires stagger).

By default it is set to False.
chain (int | None) – Form disconnected nodes into chains of up to this many nodes.

Returns:

Prepocessed DOT source code (improved layout aspect ratio).

Raises:

graphviz.RequiredArgumentError – If fanout is given but stagger is None.
graphviz.ExecutableNotFound – If the Graphviz unflatten executable is not found.
graphviz.CalledProcessError – If the returncode (exit status) of the unflattening ‘unflatten’ subprocess is non-zero.

Return type:

Source