🔧Example: Boltz-2 Tool

This tutorial will show you how to convert a workflow that runs inside a Workspace into a shareable Ontologic Tool. An Onto Tool can be run from a simple UI interface with input parameters.

This example builds on the Example: Boltz-2 Workspace tutorial, creating an Onto Tool that runs a binding affinity prediction. Please complete that tutorial before proceeding.

1. Set up the Tool's environment in a Workspace

Following the tutorial, create a Workspace and set it up to run Boltz-2. If you set up your Workspace previously, you should be able to access your snapshotted environment by navigating to the Workspaces page and clicking the Start button on the workspace.

Once your Workspace starts up, press Open to access your development environment.

2. Determine the workflow you want to capture in a Tool

Once the Workspace is open and you are looking at the VSCode IDE, you can test out the command we'll be turning into a Tool. To run it, open a terminal window (shortcut: ctrl+`) and run the following command.

boltz predict affinity.yaml --num_workers 8 --output_format pdb --out_dir ./outputs

If you followed the previous tutorial closely, it should run correctly and save results to a folder called "outputs."

Next, we're going to move the input YAML file into your projectData folder, which will make it available outside the Workspace to use as an input when we run a Tool. You can run the following command to copy it, assuming it lives in your Workspace working directory.

cp affinity.yaml projectData/affinity.yaml

If you navigate to the Project Data page, you should now see the YAML file in your project directory.

3. Stop and Snapshot your Workspace

Once you are satisfied that the prediction command works, you can move on to "Casting," the process of making an Onto Tool.

Since we are done using our Workspace to develop code, we can now stop the Workspace, and Snapshot any changes if there are any. 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. You can click Save to create an immutable Workspace Snapshot that your Onto Tool will be based on. However, if you don't care to save any of the changes you made to your Workspace since you last Snapshotted it, you can click Discard. Discarding unnecessary changes can be a good way to keep your Workspaces from getting cluttered, but be careful as discarded changes are unrecoverable.

4. Create a new 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 let's go with Boltz-2 for simplicity.

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.

boltz predict affinity.yaml \
  --num_workers 8 \
  --output_format pdb \
  --out_dir ./outputs

Your Casting tab should now look like this:

5. Configure parameters

Your Tool is almost ready to run! In fact, it would run now, but only using the hard-coded parameters specified in the command. Now we have to set up the parameters that will be displayed as user input fields in the final Tool. Start by highlighting the most important parameter: the input YAML file containing the sequence and ligand used in the prediction. Then, right-click it, and select Replace with Parameter.

Enter the parameter name, description, and data type, as in the following. When you are done, click Done Editing.

Repeat the same procedure for the num_workers parameter and output_format. You can read the documentation for these two parameters in the official Boltz-2 documentation. Note that the num_workers default is 0, which helps to prevent memory errors.

input_yaml
Description: YAML file with sequence and ligand for prediction
Data Type: File

num_workers
Data type: integer 
Description: The number of dataloader workers to use for prediction. 
Default: 0

output_format
Data type: string
Description: The output format to use for the predictions.
Default: pdb

6. Configure default hardware requirements

One final step before your Tool is ready to go: setting hardware requirements. As you might recall, the Boltz-2 model requires a GPU to run, which is why we configured the Boltz-2 Workspace to run with a GPU previously. Onto Tools can have their hardware settings configured separately, which you can do by expanding the Advanced Settings. You can reuse the same settings we had for the Boltz-2 Workspace.

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.

7. 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, and select the affinity.yaml file that you previously moved into your Project Data as an input.

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 a number of output files. There are two ways to view it them. First, let's just switch over from the Activity to the Output tab.

And here are our output files! This should include a .pdb file showing the predicted protein structure and bound ligand. From here you can view or download your results files. To download one, click on the three dots icon. To view it, click on the file name.

Congratulations! Your Boltz-2 workflow is now able to be run as a tool that accepts user input. In this case, you might generate new YAML files for different amino acid sequences or ligands to test for affinity binding, either from a Workspace or another Tool. Importantly, end users do not have to interact with code in order to run your analyses.