🐍Create an Ontologic Tool

This tutorial will show you how to convert a Jupyter notebook running in a Workspace into a shareable Ontologic Tool. An Onto Tool can be run from a simple UI interface with input parameters.

This example uses a simple Python script called "Plotologic" that plots a line with a given slope, intercept, and title. Full code for the example Tool can be found on GitHub here.

1. Create a Jupyter notebook in a Workspace

Open or create a Workspace where you would like to develop your Ontologic Tool. To follow this tutorial, please use a Workspace with the Conda base image, which has Python 3 installed.

Once you have a Workspace running, open it and launch your development environment.

Next, add a new file and name it plotologic.ipynb to create a Jupyter notebook for our Onto Tool development.

Next we will set up our Tool's parameters. In this case, we know them in advance because our tool is simple to run!

Add a code cell and paste the following code snippet. These variables will be used as parameters in a later step to allow for user input when running the Tool.

slope = 2
intercept = 0
title = 'Plotologic'

Next we will run this cell to let the development environment prompt us to install the extensions we need. Click the triangle run icon by the parameters cell we just created, and install the two recommended VSCode extensions for Jupyter and NumPy.

2. Tag your configurable parameters

Once the extensions are installed, click the three dots icon for your parameters cell and select Mark Cell as Parameters. This will tag all parameters in this cell for later use as user inputs in your Onto Tool.

3. Add the rest of your code and run it

In a new cell, paste the following:

import numpy as np 
import matplotlib.pyplot as plt

print('Setting up data for plotting...')

x = np.linspace(-10,10)
y = slope * x + intercept

print('Making plot...')

plt.figure()
plt.plot(x,y, 'H', c='purple')
plt.title(title)

print('All done!')

Before running this cell, we need to install our imports, NumPy and Matplotlib. (If you try to run it without, it will complain that these are not installed.)

To install both these dependencies, open a terminal window (shortcut: ctrl+`) and run:

pip install numpy matplotlib

Once these are done installing, click the run all button.

The notebook should now run with no errors, and you should be able to see your plot displayed below your code!

4. Stop and Snapshot your Workspace

Congratulations, you are now done developing the code for your Tool, and you can move on to "Casting," which will convert your Jupyter Notebook into a reusable Onto Tool which takes user inputs.

Since we are done using our Workspace to develop code, we can now stop and Snapshot the Workspace. To do this, go to the Workspace list page and click the Stop button.

This will display a popup asking you if you would like to stop your Workspace and save your changes by creating a Workspace Snapshot. Please click Save to create an immutable Workspace Snapshot that your Onto Tool will be based on.

3. Set up your Onto Tool

Navigate to the Tools page, and click the Create Tool button in the upper right hand corner of the screen. This will give you a dialog where you can name your new Tool.

You can name your Tool whatever you want, but for now let's call it Plotologic, after the name of the Python Notebook the tool is using.

From here, we can also choose which Workspace Snapshot the Onto Tool will use. Let's choose the one we saved a few minutes ago from the Workspace we just closed.

Once you click Create, you will be taken to your Tool's homepage. From here, navigate to the Casting tab.

In the Casting tab, replace the default Tool script (lower left corner) with the below code snippet.

papermill /home/ontologic/plotologic.ipynb output.ipynb \
  -p slope Slope \
  -p intercept Intercept \
  -p title Title
  
jupyter nbconvert --stdin --to html --output outputs/result < output.ipynb

5. Configure Parameters

Just one final step, then your Tool will be ready to run! Now we have to set up the parameters that will be displayed as user input fields in the final Tool. We're going to go through each parameter from your parameters cell in the Jupyter notebook, define it in the Tool script, then mark it as a user input field with a name, description, and data type.

We'll do this for Slope, Intercept, and Title.

Select the capitalized parameter in your Tool script (for example, Slope), and right-click it. Then select Replace with Parameter.

Enter the parameter name, description, data type, and default value. When you are done, click Done Editing.

Slope
slope
Integer
2

Repeat for the remaining two parameters, with these values.

Intercept
Data type: Integer 
Description: “intercept” 
default: 0

Title
Data type: string
Description: title
Default: Title

Once you've done that, you are ready to save and run your Tool for the first time! Click the Save icon at the bottom of the screen to make sure your Tool is saved.

6. Run your Onto Tool

Time to test out your new tool!

You can either click the Run button in the upper right corner of the Casting tab, or navigate to the Tools page and find your new Tool in the list.

Either way, that will take you to the Tool setup page. Here we can see the parameters that we just assigned on the Casting tab. The defaults you set should be populated, and you can change any of these variables before a run. For now, let's leave them on the defaults to test our Tool.

Go ahead and click Run Tool.

When you click Run Tool, it will take you to the Activity Tab of the Tool run, where you can see log messages being printed.

Once you have a successful Tool run, you'll want to look at the output. Our Tool generates an output file named results.html There are two ways to view it. First, let's just switch over from the Activity to the Output tab.

And here's our results.html file! From here you can view or download your results file. To download it, click on the three dots icon. To view it, click on the file name.

Congratulations! Your notebook is now able to be run as a tool that accepts user input, and users do not have to interact with code in order to run your analyses.

Troubleshooting

If you don't see console error messages under the cell, or if the plot renders badly, open the VSCode command palette with ctrl + shift + p and type "Reload window" to reset VSCode.

All tools need to specify outputs into a folder called outputs, and a run will fail if nothing is specified. Use the following example for a simple output in bash, where {{yourInput}} is a user-definable parameter:

echo {{yourInput}} > outputs/result.txt