Skip to content

Tutorial on editing and testing platform apps locally

Jump to bottom
Andrea Szöllössi edited this page Sep 15, 2017 · 2 revisions

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.

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

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

This step is performed in Rabix Composer.

  1. Click +Open a Project.
  2. In the popup, select the Platform tab.
  3. Start typing RCtutorial and select it from the dropdown menu.
  4. Click Done. Notice that RCtutorial containing the tool SAMtools sort now appears under Cancer Genomics Cloud in the Rabix Composer left-hand navigation pane.
  5. Right-click on SAMtools sort and select Copy to Local.
  6. 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 is performed using Rabix Executor and tests that the Platform app runs locally.

  1. Get test files from Public Reference files on the CGC:
    1. Go to Data > Public Reference files.
    2. Search for merged-normal.bam.
    3. Select merged-normal.bam from the result list.
    4. Click Dowload and place it in the RCtutorial folder from your local workspace.
  2. Open a terminal window in the folder where you downloaded Rabix Executor
  3. 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.

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 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?

Clone this wiki locally