Writing a standalone Python script for Modeler

In my last post I gave a brief overview of the new Python-based scripting available in Modeler 16. In this post, I will cover Modeler 16 scripting in a little more detail. This assumes some familiarity with Python such as the Python module mechanism and exception handling.

There are three types of script in Modeler:

• A stream script – this is the most common type of script and controls execution within a single stream
• A standalone or session script that can manage multiple streams
• A supernode script that manages the contents of the nodes within a supernode

You may recall from the previous article that the script for the “druglearn” demonstration stream looks like this:

    diagram = modeler.script.diagram()
    models = []
    diagram.findByType("c50", "Drug").run(models)
    diagram.findByType("neuralnetwork", "Drug").run(models)

In order to be useful, the script has to have a context in which to work. The context is provided by the “modeler.script” module. Unlike other modules, Modeler imports the “modeler.script” module into every Modeler script automatically because without it there is very little a script can do. The first line of the “druglearn” script calls a function called “diagram()” in the “modeler.script” module to access the particular stream/diagram.

The “modeler.script” module defines four functions:

• session(): this returns the session that the script is running in. The session defines the general execution environment such as the locale (language, formatting preferences etc.) and the Modeler Server backend that will actually execute the stream.
• diagram() and stream(): for stream scripts, these return the same thing – the stream that the script is associated with. For supernode scripts, stream() still returns the main stream but diagram() returns the supernode’s internal stream/diagram. For standalone scripts, these both return nothing (the Python None value)
• exit(): this is used to terminate a script if, say, an error has occurred. The exit() function takes a single integer value which can be used to indicate to a caller whether execution completed successfully or because of an error.

Below is an example of a standalone script that simply loads an existing stream into Modeler. You can access the standalone script dialog from the “Standalone Script…” option on the Modeler main window Tools menu, and copy and paste the script into it:

session = modeler.script.session()

# TaskRunner is a utility class for performing operations on files
# that represent Modeler objects such as streams and nodes.
taskrunner = session.getTaskRunner()

# Split long strings over multiple lines with backslash.
# It is recommended to use forward slash in file paths,
# even on Windows.
myStreamPath = "C:/Program Files/IBM/SPSS/Modeler/16/"\
"Demos/streams/druglearn.str"

try:
    stream = taskrunner.openStreamFromFile(myStreamPath, True)
except:
    print "Could not open", myStreamPath
    modeler.script.exit(1)

 
Accessing the session gives us access to functionality we may need. One of the most useful is the TaskRunner class. This provides a number of functions for opening Modeler objects from files and saving them to files:

• Stream createStream(name, autoConnect, autoManage)
• Stream openStreamFromFile(filename, autoManage)
• saveStreamToFile(stream, filename)
• ModelOutput openModelFromFile(filename, autoManage)
• saveModelToFile(modelOutput, filename)
• DocumentOutput openDocumentFromFile(filename, autoManage)
• saveDocumentToFile(documentOutput, filename)

The “autoManage” flags passed in the “open…” functions control whether the resulting stream, model or document appears in the “Streams”, “Models” or “Output” tabs in the Modeler UI. For more information, please consult the scripting reference documentation.

All these methods can throw exceptions if something goes wrong (e.g. the file cannot be found or has the wrong type of content in it). Because of that the call to the TaskRunner “openStreamFromFile()” function is surrounded by a Python “try…except” block so that if something goes wrong, the script can handle the problem in a controlled way. In this case, the script simply prints a message (which in the UI appears in the Standalone Script dialog’s “Debug” tab) and then exits from the script with a code we have chosen to indicate an error.

If you want to know more about Modeler scripting, please take a look at the Modeler Scripting API Reference (PDF).