🧙♂️Tutorial: add a tool
Last updated
Last updated
Build a simple tool, accessible on Tools page, that plots a line when given inputs for slope, intercept, and plot title:
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 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:
We have also specified license information for Plotologic on GitHub. Copy the following link into the optional License URL text box:
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:
Check your inputs and click "Next Step".
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".
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:
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:
Click "Next Step" to move on to calling your tool.
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:
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".
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".
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".
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.
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:
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:
Click the "Output" tab. Check that the specified output file, "output.png" appears in the file list.
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".
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.
Click the Plotologic tool. This will open the configuration interface that is now available to set parameters and run your 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:
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.
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:
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 contact@ontologic.ly
Happy building!
