-
Notifications
You must be signed in to change notification settings - Fork 73
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.
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
- Install Rabix Executor and pre-requisites.
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.
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.
This step is performed using Rabix Executor and 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 Dowload and place it in the RCtutorial folder from your local workspace.
- Open a terminal window in the folder where you downloaded Rabix Executor
- Run Rabix Executor to test samtools-sort.cwl locally using the command:
./rabix <path-to-tool>/samtools-sort.cwl -- --input_file <path-to-file>/merged-normal.bam
When Rabix Executor finishes running, the following is printed to the terminal screen, containing information about the task and the outputs:
[INFO] Job root has complete
{
"sorted_file" : {
"checksum" : "sha1$525bef11c7994cb640c9acde87ba64d7925fcbb9",
"class" : "File",
"contents" : null,
"dirname" : null,
"location" : "/Users/rfranklin/rabix-cli-1.0.1/samtools-sort-2017-09-11-153804.138/root/merged-normal.sorted.bam",
"metadata" : { },
"name" : "merged-normal.sorted.bam",
"path" : "/Users/rfranklin/rabix-cli-1.0.1/samtools-sort-2017-09-11-153804.138/root/merged-normal.sorted.bam",
"secondaryFiles" : [ ],
"size" : 135974512
}
}
The path to the output of your test is provided in the path
field. You change where the location of test outputs by modifying the Rabix Executor config file.
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.
- 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. - 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.
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 Publish 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?