🧙‍♂️Tutorial: add a tool

In this tutorial you will...

• Build a simple tool, accessible on Tools page, that plots a line when given inputs for slope, intercept, and plot title:

The expected output from the tutorial example tool run with default parameters.

Getting started

Once you're signed in to run.ontologic.ly, navigate to the Tools page.

In the upper right hand corner of the Tools page, click the "+ New tool" button.

The button in the upper right hand corner opens the tool packager.

The example code we use in this tutorial is a Python script we call "Plotologic". Plotologic takes inputs of a slope, y intercept, and plot title, and produces a PNG of a plotted line as output. Code and more information are available publicly on GitHub.

First we'll enter some basic information for the Plotologic example tool.

Enter "Plotologic" in the Tool Name text box. Enter "Plots a line from inputs of slope and intercept" as the optional one-line description of function. These values will appear in your list of tools on the Tools page.

The Plotologic GitHub repository contains a README file where we've entered some documentation for our tool. Copy the following link into the optional Documentation URL text box:

https://github.com/ontologicly/example-tool-repo

We have also specified license information for Plotologic on GitHub. Copy the following link into the optional License URL text box:

https://github.com/ontologicly/example-tool-repo/blob/main/LICENSE

The website https://choosealicense.com/ is a good resource for learning more about licensing your code.

You can also upload an image (JPG, BMP, or PNG) as an icon for your tool, though the packager will provide a default icon. This will also appear in the Tools page with your final published tool, alongside its name and short description.

Once you've entered all of the basic information, your Tool Info step should look like this:

This is basic information that will help you and other users quickly find and appropriately use your tool.

Check your inputs and click "Next Step".

Setting up your environment

In the next steps, we establish the main computing environment for your tool and import any necessary packages.

The Plotologic example tool is written in Python, so select "Python 3.9" from the Environment dropdown. Click "Next Step".

This is the language for the main codebase of your tool.

Next, you will provide the Tool Code and Dependencies for your tool. Select "Git Repository" from the Tool Code dropdown as the source. Copy the GitHub repository URL below, and paste into the URL text box:

https://github.com/ontologicly/example-tool-repo.git

As outlined in the Plotologic documentation, this tool requires two python libraries as dependencies, numpy and matplotlib.

Click "Add Package Manager" and select the "pip" option from the dropdown. To add these libraries to your environment, type "numpy" and hit the spacebar. Then type "matplotlib" and hit the spacebar.

The completed result should look like the picture below:

This is what your finished environment should look like for our example tool.

Click "Next Step" to move on to calling your tool.

Invoke your tool and set parameters

Plotologic, our example tool, is written in Python. In the Tool Script & Parameters step, select "python" from the Source Language dropdown.

Next, copy and paste the code below into the code text box to invoke the example tool:

from plotologic import makeplot
import matplotlib.pyplot as plt

makeplot(slope, intercept, title)

plt.savefig('outputs/output.png')

The parameters we want to expose in the GUI for users are the line slope, intercept, and plot title. These are all passed as inputs to the "makeplot" function in our tool invocation code above.

We'll define parameters one at a time. To define your first parameter, highlight "slope" in the Tool Script and Parameters text box, and right click on the highlighted text. Click "+ Replace with Parameter".

The "+ Replace with Parameter" button appears when you right click on highlighted text in the Tool Script & Parameters text box.

You can now edit the slope parameter information. The values you enter will help future users configure runs of your tools.

We capitalized "Slope" in the Parameter Name and entered "Sets the slope of the plotted line" for the Description.

Set the data type for the slope to "decimal".

For the Input Details, enter a Default Value of 1.

Check that your Slope parameter settings look like the image below, and click "Done Editing".

Suggested configuration of the "Slope" parameter.

Repeat this process for the intercept and title parameters:

For the intercept, use "Sets the y intercept of the plotted line" as the Description. Set the Data Type to "decimal" and Default Value to 0.

Make sure to click "Done Editing" when you've finished selecting settings for each parameter.

For the title, use "Sets the title of the plot" as the Description. Select "string" from the Data Type dropdown. Set the Default Value to "My Plot", and click "Done Editing".

It's best practice to set Default Values for any parameter that, if missing, would cause a run of your tool to fail.

Check that the script to invoke your tool (the text in the code text box) saves any outputs you'd like to see in a folder named "outputs". This folder will exist in your tool's environment by default, you just need to ensure that any outputs you'd like to access later will be saved there. This is already done for you in the Plotologic code you copied for this tutorial.

Check that the Tool Script & Parameters page looks like the image below, and click "Next Step".

All parameters entered as suggested for the Plotologic example.

Building and publishing the tool

Next, the platform will try to build your environment complete with your base computing language, dependencies, and parameter settings. Hit "Build Tool" and wait for the platform to succeed or fail.

This is what it looks like when your environment was built successfully!

If your build failed, return to the Environment Details and Tool Code & Dependencies steps. Check that the main computing environment and dependencies were selected and spelled correctly using the appropriate package manager, then click "Try Again".

Once the Finalize & Build Tool step shows Status "COMPLETE", click "Next Step".

If you go back to make any changes in the environment, code, dependencies, or parameters steps, make sure to return to the Finalize & Build Tool step and re-build your tool. This saves your changes before moving on to testing with example data or publishing.

You will next test your tool on example data. Check that the slope, intercept, and title parameter input boxes appear containing the default values you set in the Tool Script & Parameters step, as shown below:

This is a preview of the configuration page for your near-finalized Plotologic tool.

Click "Run Tool" and wait for the Status to read "COMPLETE".

If your run failed, return to the Tool Script & Parameters step. Double check the settings for each of the three Plotologic parameters against the directions. Make sure to repeat the Finalize & Build Tool step, then try the Test on Example Data step again.

Click the "Activity" tab. In the source code for the main function of our tool, we included a few print statements. Check that the statements "Making plot..." and "All done!" appear in the activity logs as below:

Print statements normally used to troubleshoot your code are visible in the activity logs of tool runs.

Click the "Output" tab. Check that the specified output file, "output.png" appears in the file list.

This is the only expected output file from the provided example tool invocation script.

Once you have successfully run your tool on the default parameters and confirmed the expected outcomes in the Activity and Output tabs, click "Publish Tool".

Final Checks

Your new "Plotologic" tool should now appear at the top of the list of available tools. If you don't see your Plotologic tool, try refreshing the Tools page.

You can access Plotologic just like any other tool on the platform.

Click the Plotologic tool. This will open the configuration interface that is now available to set parameters and run your tool:

This is the final user interface for your Plotologic tool!

Check once again that your that the slope, intercept, and title parameter input boxes appear containing the default values you set. Click "Launch" to run your tool from the main user interface you've created. This will automatically take you to the Run Details page for the current run of the Plotologic tool:

The yellow progress indicator shows that the tool is running with the displayed configuration of parameters.

Once the progress indicator dot turns green and shows status "COMPLETE", Click the "Logs" tab. As you did in the Tool Packager testing process, check that the print statements "Making plot..." and "All done!" appear in the activity logs.

Logs are useful for troubleshooting runs of more complicated tools.

Click the "Results" tab. Check that the specified output file, "output.png" appears in the file list. Click "Download" and open the file to check the results look as expected, below:

The expected plot from default inputs: slope = 1, intercept = 0, title = "My Plot". Hexagons are the bestagons.

And congratulations, you've created your first simple tool on the Ontologic platform! You can now experiment with making variations on this example tool or adding tools based on your own code.

If you run into any issues or want new functionality to help you build tools for work or personal projects, never hesitate to reach out directly to us at [e-mail]

Happy building!