Tutorial on editing and testing Platform apps locally

Overview

The Rabix toolkit (Composer and Executor) allows you to develop and test CWL apps locally on your desktop before deploying on the cloud. Developing locally enables faster development cycles, because you do not have to wait for a cloud instance to be acquired every time you want to test the workflow. Also, Rabix Executor integration allows you to easily test the app on your local machine and see the terminal output directly within Rabix Composer.

This tutorial uses SAMtools sort from the Cancer Genomics Cloud (CGC) along with relevant lightweight input files for testing. The same steps are applicable to other apps, including tools and workflows you’ve created yourself.

Objectives

This tutorial walks you through editing and testing a Platform app locally and pushing it to the Platform as a new revision of the initial app.

As part of this tutorial, you will:

• Copy a Platform app to your Rabix Composer local workspace.
• Use Rabix Composer to edit the Platform app.
• Use Rabix Executor to test the app locally.
• Push the edited app back to the Platform as a new revision of the initial app.

Prerequisites

• You must have a CGC account, or another Platform account.
• Install Rabix Composer.
• Set up Rabix Composer
  • add a local workspace.
  • connect a Platform account and add at least one Platform project to your workspace.

Step 1: Create a CGC project containing SAMtools sort

This step is performed on the CGC platform. You create a project containing SAMtools sort, a tool available as a public app. This is the tool we’re using throughout this tutorial.

1. Create a project called RCtutorial on the CGC.
2. Copy the SAMtools sort public app to the RCtutorial project you’ve just created.

Step 2: Copy SAMtools sort to your Rabix Composer local workspace

1. In the RCtutorial project on the CGC, click the Apps tab.
2. Click SAMtools sort to open app details.
3. In the top-right corner click the ellipsis icon (. . .) and select Export.
4. Copy the displayed CWL code.
5. In Rabix Composer, click New Command Line Tool on the Home tab. Create a new CommandLineTool dialog opens
6. Select Local Files
7. In the App Name field enter Samtools sort
8. In the CWL version dropdown select sbg:draft-2.
9. Select the location where to save the CWL file on your local machine and confirm the selection. The tool editor opens.
10. In the tool editor, click the Code tab.
11. Paste the code you copied in step 4. The app is now available for local editing.

Step 3: Test SAMtools sort locally

This step tests that the Platform app runs locally.

1. Get test files from Public Reference files on the CGC:
   1. Go to Data > Public Test files.
   2. Search for merged-normal.bam.
   3. Select merged-normal.bam from the result list.
   4. Click Download and place it in the same folder on your local workspace where your app is located.
2. Open Rabix Composer.
3. Open your local copy of SAMtools sort.
4. Click the Test tab.
5. Double click the input_file port.
6. In the object inspector on the right, click Browse below the input_file field.
7. Navigate and select the downloaded merged-normal.bam file.
8. In the top-right corner click Run.

The app will start running through Rabix Executor, and you will see the progress of execution in the Execution pane at the bottom of the screen.

When Rabix Executor finishes running, click the icon on the left side of the Execution pane to go to the output directory containing app outputs and logs.

Step 4: Edit SAMtools sort

This step is performed in Rabix Composer and tests illustrates changing the sorting criterion. The Public Apps version of SAMtools sort orders the output BAM file by read name. In this step we edit samtools-sort.cwl to perform sorting by chromosome.

1. Open your local copy of SAMtools sort, samtools-sort.cwl using Rabix Composer
2. In the Visual tab, scroll down to the Input ports section.
3. Click the sort_by_read_name input port to open the object inspector.
4. Delete -n from the Prefix box in the object inspector. This will abolish sorting by read name, defaulting to chromosomal coordinates. Learn more about customizing SAMtools sort from the SAMtools documentation.
5. Save the change by clicking the save icon in the top right.
6. Test your edited version of SAMtools sort using the same file and steps outlined in Step 3.

Step 5: Push the new version of SAMtools sort to the CGC

After successfully editing and testing samtools-sort.cwl locally, we can push our new version of SAMtools sort to the CGC as a new revision of the initial app. To do this, we must ensure that we push the app using the same app ID. If you push the app using a different ID, it will be saved as a separate app, rather than a new revision of the app.

1. Go to the App Info tab of your local copy of SAMtools sort.
2. Scroll down to ID and copy the highlighted part to clipboard: rfranklin/rctutorial/samtools-sort-1-3/0. This is the ID of your app.
3. Click Push to Platform to push your local edited version of SAMtools sort to to the CGC.
4. In the popup, enter the following:
   1. Paste the app ID into the App Name field.
   2. Select RC tutorial from the Destination project dropdown menu.
   3. Write Sorting BAM by chromosome as the revision note. This is optional, but good practice to write.
5. Click Push and close the app tab.

If you now open your SAMtools sort copy under Cancer Genomics Cloud, you can see the revision number has been updated.

Congratulations, you’ve completed the tutorial! Why not try editing and testing your own apps locally and then push them to the Platform to perform your experiments?