🐍Create a notebook-based tool

1. Create a Jupyter notebook

From the Tools page, click the "+ New Tool" button with a Conda environment.

On the "Develop" tab, click "Launch IDE" to start up the environment, and click "Open" to open VSCode in a new tab.

In VSCode, create a notebook by making a new file that ends in .ipynb.

Add a code cell and paste the following. These variables will be used in a later step to allow for user input.

slope = 2
intercept = 0
title = 'Hello, world!'

Run the cell, let VSCode install Jupyter and Python extensions.

2. Tag your configurable parameters

Once the extensions are installed, hover over the cell to the "..." icon.

Add a cell tag called parameters to this cell.

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!')

Now try running these cells. It should complain about numpy not being installed. Open a terminal (shortcut: ctrl+`) and run:

pip install numpy matplotlib

Once these are done installing, the notebook should run with no errors.

From the Tool Details tab, click the "Stop" button to shut down the IDE. Wait for it to complete. The shutdown step takes about 90 seconds.

3. Write the script

In the Script & Parameters section, paste the following:

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

Replace all the capitalized parameters with parameters in the GUI by highlighting and right-clicking to show the "+ Replace with Parameter" button.

Make sure to specify the correct data type for each variable. Parameters that can receive user input will be highlighted purple.

Save these changes so that the script can be run from the Tools page with user input.

4. Run the notebook as a tool

Go back to the tools page and click "Run" on the new tool.

Configure the parameters as desired and start the run by clicking the "Run Tool" button. It should complete successfully in about 30 seconds.

The tool will generate a result titled result.html. From the Output tab, you can preview and download and the file created by your notebook.

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