pliers.graph.Graph

class pliers.graph.Graph(nodes=None, spec=None)

Bases: object

Graph-like structure that represents an entire pliers workflow.

Parameters

• nodes (list, dict) – Optional nodes to add to the Graph at construction. If a dict, must have a ‘roots’ key. If a list, each element must be in one of the forms accepted by add_nodes().

• spec (str) – An optional path to a .json file containing the graph specification.

__init__(nodes=None, spec=None)

add_chain(nodes, parent=None)

An alias for add_nodes with the mode preset to ‘vertical’.

add_children(nodes, parent=None)

An alias for add_nodes with the mode preset to ‘horizontal’.

add_node(transformer, name=None, children=None, parent=None, parameters={}, return_node=False)

Adds a node to the current graph.

Parameters

• transformer (str, Transformer) – The pliers Transformer to use at the to-be-added node. Either a case-insensitive string giving the name of a Transformer class, or an initialized Transformer instance.

• name (str) – Optional name to give this Node.

• children (list) – Optional list of child nodes (i.e., nodes to pass the to-be-added node’s Transformer output to).

• parent (Node) – Optional node from which the to-be-added Node receives its input.

• parameters (dict) – Optional keyword arguments to pass onto the Transformer initialized at this Node if a string is passed to the ‘transformer’ argument. Ignored if an already-initialized Transformer is passed.

• return_node (bool) – If True, returns the initialized Node instance.

Returns

The initialized Node instance if return_node is True,

None otherwise.

add_nodes(nodes, parent=None, mode='horizontal')

Adds one or more nodes to the current graph.

Parameters

• nodes (list) –

  A list of nodes to add. Each element must be one of the following:

  • A dict containing keyword args to pass onto to the Node init.

  • An iterable containing 1 - 3 elements. The first element is mandatory, and specifies the Transformer at that node. The second element (optional) is an iterable of child nodes (specified in the same format). The third element (optional) is a string giving the (unique) name of the node.

  • A Node instance.

  • A Transformer instance.

• parent (Node) – Optional parent node (i.e., the node containing the pliers Transformer from which the to-be-created nodes receive their inputs).

• mode (str) –

  Indicates the direction with which to add the new nodes * horizontal: the nodes should each be added as a child of the

  ’parent’ argument (or a Graph root by default).

  • vertical: the nodes should each be added in sequence with the first node being the child of the ‘parnet’ argument (a Graph root by default) and each subsequent node being the child of the previous node in the list.

draw(filename, color=True)

Render a plot of the graph via pygraphviz.

Parameters

• filename (str) – Path to save the generated image to.

• color (bool) – If True, will color graph nodes based on their type, otherwise will draw a black-and-white graph.

run(stim, merge=True, **merge_kwargs)

Executes the graph by calling all Transformers in sequence.

Parameters

• stim (str, Stim, list) – One or more valid inputs to any Transformer’s ‘transform’ call.

• merge (bool) – If True, all results are merged into a single pandas DataFrame before being returned. If False, a list of ExtractorResult objects is returned (one per Extractor/Stim combination).

• merge_kwargs – Optional keyword arguments to pass onto the merge_results() call.

run_node(node, stim)

Executes the Transformer at a specific node.

Parameters

• node (str, Node) – If a string, the name of the Node in the current Graph. Otherwise the Node instance to execute.

• stim (str, stim, list) – Any valid input to the Transformer stored at the target node.

save(filename)

Writes the JSON representation of this graph to the provided filename, such that the graph can be easily reconstructed using Graph(spec=filename).

Parameters

filename (str) – Path at which to write out the json file.

to_json()

Returns the JSON representation of this graph.

transform(stim, merge=True, **merge_kwargs)

Executes the graph by calling all Transformers in sequence.

Parameters

• stim (str, Stim, list) – One or more valid inputs to any Transformer’s ‘transform’ call.

• merge (bool) – If True, all results are merged into a single pandas DataFrame before being returned. If False, a list of ExtractorResult objects is returned (one per Extractor/Stim combination).

• merge_kwargs – Optional keyword arguments to pass onto the merge_results() call.