Tutorial on editing and testing Platform apps locally
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.
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.
- You must have a CGC account, or another Platform account.
- Install Rabix Composer.
- Set up Rabix Composer
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.
- Create a project called RCtutorial on the CGC.
- 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
This step is performed in Rabix Composer.
- Click +Open a Project.
- In the popup, select the Platform tab.
- Start typing RCtutorial and select it from the dropdown menu.
- Click Done. Notice that RCtutorial containing the tool SAMtools sort now appears under Cancer Genomics Cloud in the Rabix Composer left-hand navigation pane.
- Right-click on SAMtools sort and select Copy to Local.
- Create folder called RCtutorial in your local workspace and save the app there as samtools-sort.cwl.
Step 3: Test SAMtools sort locally
This step tests that the Platform app runs locally.
- Get test files from Public Reference files on the CGC:
- Go to Data > Public Reference files.
- Search for merged-normal.bam.
- Select merged-normal.bam from the result list.
- Click Download and place it in the RCtutorial folder from your local workspace.
- Open Rabix Composer.
- Open your local copy of SAMtools sort.
- Click the Test tab.
- Double click the input_file port.
- In the object inspector on the right, click Browse below the input_file field.
- Navigate and select the downloaded merged-normal.bam file.
- 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.
- Open your local copy of SAMtools sort, samtools-sort.cwl using Rabix Composer
- In the Visual tab, scroll down to the Input ports section.
- Click the sort_by_read_name input port to open the object inspector.
-nfrom 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.
- Save the change by clicking the save icon in the top right.
- 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.
- Go to the App Info tab of your local copy of SAMtools sort.
- 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.
- Click Push to Platform to push your local edited version of SAMtools sort to to the CGC.
- In the popup, enter the following:
- Paste the app ID into the App Name field.
- Select RC tutorial from the Destination project dropdown menu.
- Write Sorting BAM by chromosome as the revision note. This is optional, but good practice to write.
- 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?