Available methods for scripting

Synthetic Data Generator has a number of different methods available for scripting.

You can use these methods to create and modify nodes, link nodes, edit flows, and get node information.

Creating nodes
Linking and unlinking nodes
Setting properties
Importing, replacing, and deleting nodes
Locating nodes
Getting information about nodes

Methods for creating nodes

Adding nodes to existing flows typically involves the following tasks:

Creating the new nodes.
Linking the nodes to existing nodes in the flow.

The methods that are available provide a number of ways to create nodes through scripting.

Table 1. Methods for creating nodes
Method	Return type	Description
`s.create(nodeType, name)`	Node	Creates a node of the specified type and adds it to the specified flow.
`s.createAt(nodeType, name, x, y)`	Node	Creates a node of the specified type and adds it to the specified flow at the specified location. If either x < 0 or y < 0, the location is not set.
`s.createModelApplier(modelOutput, name)`	Node	Creates a model applier node that's derived from the supplied model output object.

Scripting example

You can use the following script to create a mimc node in a flow:

stream = sdg.script.stream()
# Create a new Type node
node = stream.create("mimic", "Mimic1")

Linking and unlinking nodes

After you add a new node to a flow, you must connect it to a sequence of nodes before it can be used. A number of methods are available for linking and unlinking nodes.

Table 2. Methods for linking and unlinking nodes
Method	Return type	Description
`s.link(source, target)`	Not applicable	Creates a new link between the source and the target nodes.
`s.link(source, targets)`	Not applicable	Creates new links between the source node and each target node in the supplied list.
`s.linkBetween(inserted, source, target)`	Not applicable	Connects a node between two other node instances (the source and target nodes) and sets the position of the inserted node to be between them. Any direct link between the source and target nodes is removed first.
`s.linkPath(path)`	Not applicable	Creates a new path between node instances. The first node is linked to the second, the second is linked to the third, and so on.
`s.unlink(source, target)`	Not applicable	Removes any direct link between the source and the target nodes.
`s.unlink(source, targets)`	Not applicable	Removes any direct links between the source node and each object in the targets list.
`s.unlinkPath(path)`	Not applicable	Removes any path that exists between node instances.
`s.disconnect(node)`	Not applicable	Removes any links between the supplied node and any other nodes in the specified flow.
`s.isValidLink(source, target)`	boolean	Returns `True` if it would be valid to create a link between the specified source and target nodes. This method checks that both objects belong to the specified flow, that the source node can supply a link and the target node can receive a link, and that creating such a link will not cause a circularity in the flow.

Scripting example

The example script that follows performs these five tasks:

Creates an Import node, an Anonymize node, and a Mimic node.
Connects the nodes together.
Runs the Mimic node.

stream = sdg.script.stream()
sourcenode = stream.findByID("idGXVBG5FBZH")
anonymizenode = stream.createAt("anonymize", "Anonymize", 192, 64)
mimicnode = stream.createAt("mimic", "Mimic", 288, 64)
stream.link(sourcenode, anonymizenode)
stream.link(anonymizenode, mimicnode)
anonymizenode.setKeyedPropertyValue("include", "Drug", False)
results = []
mimicnode.run(results)

Methods for setting properties

Nodes, flows, models, and outputs all have properties that can be accessed and, in most cases, set. Properties are typically used to modify the behavior or appearance of the object. The methods that are available for accessing and setting object properties are summarized in the following table.

Table 3. Methods for accessing and setting object properties
Method	Return type	Description
`p.getPropertyValue(propertyName)`	Object	Returns the value of the named property or `None` if no such property exists.
`p.setPropertyValue(propertyName, value)`	Not applicable	Sets the value of the named property.
`p.setPropertyValues(properties)`	Not applicable	Sets the values of the named properties. Each entry in the properties map consists of a key that represents the property name and the value that should be assigned to that property.
`p.getKeyedPropertyValue(propertyName, keyName)`	Object	Returns the value of the named property and associated key or `None` if no such property or key exists.
`p.setKeyedPropertyValue(propertyName, keyName, value)`	Not applicable	Sets the value of the named property and key.

Scripting example

The following script sets the value of a Mimic node for a flow:

stream = sdg.script.stream()
node = stream.findByType("mimc", None)
node.setPropertyValue("name_extension", "new_mimic")

Methods for locating nodes

You can use locating an existing node. These methods are summarized in the following table.

Table 4. Methods for locating an existing node
Method	Return type	Description
`s.findAll(type, label)`	Collection	Returns a list of all nodes with the specified type and label. Either the type or label can be `None`, in which case the other parameter is used.
`s.findAll(filter, recursive)`	Collection	Returns a collection of all nodes that are accepted by the specified filter. If the recursive flag is `True`.
`s.findByID(id)`	Node	Returns the node with the supplied ID or `None` if no such node exists. The search is limited to the current flow.
`s.findByType(type, label)`	Node	Returns the node with the supplied type, label, or both. Either the type or name can be `None`, in which case the other parameter is used. If multiple nodes result in a match, then an arbitrary one is chosen and returned. If no nodes result in a match, then the return value is `None`.
`s.findDownstream(fromNodes)`	Collection	Searches from the supplied list of nodes and returns the set of nodes downstream of the supplied nodes. The returned list includes the originally supplied nodes.
`s.findUpstream(fromNodes)`	Collection	Searches from the supplied list of nodes and returns the set of nodes upstream of the supplied nodes. The returned list includes the originally supplied nodes.
`s.findProcessorForID(id, recursive)`	Node	Returns the node with the supplied ID or `None` if no such node exists. If the recursive flag is `true`, then any composite nodes within this diagram are also searched.

Scripting examples

As an example, if a flow contains a single Evaluate node that the script needs to access, the Evaluate node can be found by using the following script:

stream = sdg.script.stream()
node = stream.findByType("evaluate", None)
...

Alternatively, you can use the ID of a node. For example:

stream = sdg.script.stream()
node = stream.findByID("id49CVL4GHVV8")  # the Evaluate node ID
node.setPropertyValue("mode", "Multiple")
node.setPropertyValue("name_extension", "evaluate")

To add the ID for any node in a flow to a script, click the Scripting icon on the toolbar, then select the desired node in your flow and click Insert selected node ID.

Methods for importing, replacing, and deleting nodes

It's sometimes necessary to replace and delete nodes from a flow. You can use the following methods to import, replace, and delete nodes.

Table 5. Methods for importing, replacing, and deleting nodes
Method	Return type	Description
`s.replace(originalNode, replacementNode, discardOriginal)`	Not applicable	Replaces the specified node from the specified flow. Both the original node and replacement node must be owned by the specified flow.
`s.insert(source, nodes, newIDs)`	List	Inserts copies of the nodes in the supplied list. It's assumed that all nodes in the supplied list are contained within the specified flow. The `newIDs` flag indicates whether new IDs should be generated for each node, or whether the existing ID should be copied and used. The method returns the list of newly inserted nodes, where the order of the nodes is undefined.
`s.delete(node)`	Not applicable	Deletes the specified node from the specified flow. The node must be owned by the specified flow.
`s.deleteAll(nodes)`	Not applicable	Deletes all the specified nodes from the specified flow. All nodes in the collection must belong to the specified flow.
`s.clear()`	Not applicable	Deletes all nodes from the specified flow.

Getting information about nodes

You can find information about nodes in a number of differenr ways. You can use the following methods to obtain the ID, name, and label of a node.

Table 6. Methods to obtain the ID, name, and label of a node
Method	Return type	Description
`n.getLabel()`	string	Returns the display label of the specified node. The label is the value of the property `custom_name` only if that property is a non-empty string and the `use_custom_name` property is not set; otherwise, the label is the value of `getName()`.
`n.setLabel(label)`	Not applicable	Sets the display label of the specified node. If the new label is a non-empty string it is assigned to the property `custom_name`, and `False` is assigned to the property `use_custom_name` so that the specified label takes precedence; otherwise, an empty string is assigned to the property `custom_name` and `True` is assigned to the property `use_custom_name`.
`n.getName()`	string	Returns the name of the specified node.
`n.getID()`	string	Returns the ID of the specified node. A new ID is created each time a new node is created. The ID is persisted with the node when it's saved as part of a flow so that when the flow is opened, the node IDs are preserved. However, if a saved node is inserted into a flow, the inserted node is considered to be a new object and will be allocated a new ID.

Methods that can be used to obtain other information about a node are summarized in the following table.

Table 7. Methods for obtaining information about a node
Method	Return type	Description
`n.getTypeName()`	string	Returns the scripting name of this node. This is the same name that could be used to create a new instance of this node.
`n.isInitial()`	Boolean	Returns `True` if this is an initial node (one that occurs at the start of a flow).
`n.isInline()`	Boolean	Returns `True` if this is an in-line node (one that occurs mid-flow).
`n.isTerminal()`	Boolean	Returns `True` if this is a terminal node (one that occurs at the end of a flow).
`n.getXPosition()`	int	Returns the x position offset of the node in the flow.
`n.getYPosition()`	int	Returns the y position offset of the node in the flow.
`n.setXYPosition(x, y)`	Not applicable	Sets the position of the node in the flow.
`n.setPositionBetween(source, target)`	Not applicable	Sets the position of the node in the flow so that it's positioned between the supplied nodes.
`n.isCacheEnabled()`	Boolean	Returns `True` if the cache is enabled; returns `False` otherwise.
`n.setCacheEnabled(val)`	Not applicable	Enables or disables the cache for this object. If the cache is full and the caching becomes disabled, the cache is flushed.
`n.isCacheFull()`	Boolean	Returns `True` if the cache is full; returns `False` otherwise.
`n.flushCache()`	Not applicable	Flushes the cache of this node. Has no affect if the cache is not enabled or is not full.