[ Previous: Recording provenance ] [ Up: Introductory Tutorials ] [ Next: Leveraging the power of Python modules within Workspace workflows ]

Introduction

Python scripts can be embedded into a Workspace workflow, in this tutorial we will:

Understand how to add a Python script to a workflow
Understand how to pass data from a workflow into Python
Understand how to pass data from an embedded Python script back into a workflow
Understand how to use your local Python installation with Workspace

Overview

Workspace supports the embedding and running of Python scripts within a workflow. Data can be passed from your Workspace workflow into Python and vice versa. The Workspace ships with a Python 3 interpreter and a RunPythonScript operation, combined they allow you to access all the power of Python from within your Workspace workflows. You can add further Python modules using the included pip.

At the time of writing the following data types can be passed from Workspace to Python:

Workspace data type(s)	Maps to a Python...
bool, int, Uint, Double, LongLong, ULongLong, String, Date, DateTime, RegExp	object
QVector<double>, StringList, QVariantList	list
QVariantMap	dictionary
ObjectGroup	object (where each named entry in the ObjectGroup is an attribute on the Python object)
MeshModelInterface	PythonMeshInterface provides an interface with Workspace mesh models.w import workspace new_mesh = workspace.mesh() new_mesh.add_node(x, y, z);

At the time of writing the following data types can be passed from Python to Workspace:

Python data type	Maps to a Workspace...
object containing an integer value	int
object containing an unsigned integer value	unsigned int
object containing a float value	float
object containing a string	QString
list	QVariantList
dictionary	QVariantMap

Hello Workspace-Python

In this brief tutorial we introduce the new RunPythonScript Operation, its inputs and outputs. Just in case you get stuck, a sample workflow has been provided for you.

Find the RunPythonScript Operation in the Operation catalogue and drag it onto the Workspace canvas.
Enter the following text into the Script input:

print("Hello Python")

Inital script entry

Click OK to close the Operation properties dialog.
Right click on the RunPythonScript's dependency output and choose the "Create Workspace output" menu option.
Run the workflow.
Assuming you have the Workspace log window open you should see the text "Hello Python" (excluding quotes) printed to the log window. This was printed to the standard output stream by Python via our embedded RunPythonScript operation and was captured and re-directed to the log window by the Workspace.

Hello Python

Note: Alternatively, rather than directly enter a script using the Script input, you can enter the file path of an existing external Python script file into the Scrip file input.

Run external Python python

Passing data from Workspace into Python

Data can be passed from Workspace into an embedded Python script (and in fact back to Workspace from Python as we will see in the next tutorial). In this tutorial we will create a simple workflow that passes some Workspace data into an embedded Python script, modify it and then pass it back out again.

Click on the Operation indicator to bring up its custom properties dialog.

Custom properties indicator
Add an input to the Operation by clicking the "Add" button and changing the input's name to "inputA" (excluding quotes). Set its Data Type to "QString"
Close the property pages by clicking the "OK" button.
Select the operation again on the Workspace canvas. You should see that the operation property editing pane now displays the newly added input (called inputA) that we just added.
Modify the Python script (via the Script input as before) by removing the existing text and entering the following text: print(inputA)
We need to do one last thing. Next find an Operation in the Operation catalogue called "Variable".
Drag this onto the Workspace canvas.
The Variable Operation's "Operation properties" dialog box will open automatically at the "Data" tab.
Change the Data type to "QString" then click OK to close (and apply) the changes.
With the "Variable" operation selected you should notice in the operation editor that the Inputs are displayed and one such input (in fact its only input) is called "Variable".
Enter the text "Hello again Python" (excluding quotes) into the Variable input.
Finally, drag the Variable Operation's Variable output to the inputA input we created on the RunPythonScript Operation.
The "Persistent namespace" input allows global data to be shared between RunPythonScript operations. For this example, leave it unchecked (off).
Run the workflow.
You should see the following text printed in the Workspace log window: "Hello again Python".

Using a variable as input

Passing data from Python into Workspace

In this tutorial we will load some data from a csv file, modify it via a Python script and then return it back to Workspace. In case you get stuck, a sample workflow has been provided for you.

First locate the doc/Workspace/Examples/datasample.csv file inside your Workspace installation. This file has the following contents:
```
X,Y
1,0
2,0
3,0
4,0
5,0
6,0
7,0
8,0
9,0
10,0
```
Click the New workflow button to clear the canvas.
Next, find and add a CsvReader Operation.
Set the File name input to the location of the datasample.csv file.
The delimiter input on the Operation should be set to a comma.
Set the Column formatting input to "First row contains header names".

CSV Reader inputs

Next, find and locate the GetItemFromObjectDictionary Operation and drag it onto the canvas.
Set its data type to QVector<double> and click OK.
Next, drag the CSV reader's "CSV file data" output to the "Object dictionary" input on the "Get Item From Object Dictionary" operation.
Set the "Item name" input on the "Get Item From Object Dictionary" operation to "X" (excluding quotes).
Next, add the RunPythonScript operation to your workflow.
Add a new input to the Operation called inputA and click OK.
Next, drag the "Item" output from the "Get Item From Object Dictionary" Operation to the inputA input on your RunPythonScript Operation.
We will now, from our script, print out the contents of the inputA variable. To do this add the following script to the script input on your RunPythonScript Operation:
for listItem in inputA:

print(listItem)
Right click on the "Dependencies" output and click the "Create Workspace output".
Now run your workflow and you should see the following output in the Log window:
```
1.0
2.0
3.0
4.0
5.0
6.0
7.0
8.0
9.0
10.0
```

Displaying a column from a CSV file

We will now modify our Python script to do some simple processing on the values, and return them back to Workspace.

Stop the workflow and remove the WorkspaceOutput Operation we created previously.
Click on the Operation indicator to bring up its custom properties dialog.
Add a new output to the Operation called outputA.
Modify the Script Input to:
outputA = inputA[:]

for i in range(len(outputA)):

outputA[i] = outputA[i] * 2

print(outputA[i])

i
double i
Definition: opencljuliaset.cpp:45

Add an output variable and updated script

Once run, our modified data will be available to us in the outputA output of our PythonScriptOperation. You are free to do what you like with this data (send it to a plot for instance) but for the purpose of this Operation we will simply print out one of the values from outputA to the log window.

Find and add the "GetDataSeriesValue" Operation to the canvas.
Drag the outputA Output from your PythonScriptOperation to the Data series input on the GetDataSeriesValue Operation.
Next, add a LogText operation to the canvas and then drag the Value output from the GetDataSeriesValue Operation to the Text to log Input on the LogText Operation.
Now, right click on the dependency output on the LogText Operation and choose the Create Workspace output menu option.
Finally, run the workflow.

Python modifying Workspace data

Using your local Python installation with Workspace

Although Workspace ships with a Python 3 interpreter, it is possible to configure Workspace to use a different Python installation that you already have set up. If you intend to use your own version of Python rather than the one that ships with Workspace ensure it is the same version (Python 3.6.5 64bit) that this release of Workspace was built against and modify workspace_install_directory\installAreas\python.txt to point to this version rather than the one shipped with Workspace.

To use Anaconda as an example:

Install the latest version of Anaconda for your platform
Launch the Anaconda command prompt
Setup an environment that matches Workspace's Python
conda create -n for_workspace python=3.6.5 anaconda
Replace the text in workspace_install_directory\installAreas\python.txt with the python environment path setup by Anaconda eg. 'C:/Users/user/AppData/Local/Continuum/anaconda3/envs/for_workspace'

If Workspace detects more than one install of Python on your system's PATH it will revert back to its local version. To override this behaviour and force Workspace to try to use an external install you can set a WORKSPACE_PYTHONHOME environment variable to your Python path.

Summary

This concludes the tutorial on embedding Python scripts into your workflows.

[ Previous: Visualising data with charts ] [ Up: Introductory Tutorials ] [ Next: Leveraging the power of Python modules within Workspace workflows ]