Get Started Building a Simple App Using

The easiest way to get started quickly is build an example app. In this tutorial you can learn how to build a simple bam viewer that can grab regions of alignments from both URLs and Files and visualize the data. See example app in action

Live Demo

Let's Start Building

You can directly Click on the blocks to skip and navigate to step explanation

Step 1 - Create UI For Data Selection

In this step we'll create a rough UI that can take the inputs we need. In later steps, we will hook up this UI to functions that do work.

Step 2 - Create iobio Command

In this step we'll create the iobio commands and grab the data. In later steps, we will hook this data up to a visualization.

Step 3 - Create Visualization

In this step we'll create the visualization for our BAM viewer and visualize some test data.

Step 4 - Hook Up Data to Visualization

Now we can finally hook up the real data to our visualization code and see our bam viewer.

Step 5 - Improve visualization

So we have our basic viewer up and working. We can now have a little fun and alter the chart to do some more use-case specific stuff. In this case we'll be showing strandedness, mate pairs, mismatches, and deletions. Some features are built in to the visualizatin and some are just added on top, using some custom d3 code.

Step 6 - Test the streaming!

All Done! Start Testing

Bam Viewer App

Explore the Github

Step 1 - Create UI For Data Selection


First, clone the repo, and create the file you'll be working with by copying app.skeleton.html. This will give you a bare html page with all the necessary libraries added. From here on out you'll be building the app in the bamViewer.html file.

git clone
cd example-bamViewer/working
cp app.skeleton.html bamViewer.html

Add button

Add input buttons for user to select a region and data (either via a file or a URL).

Hook up modal

Use bootstrap to create a modal for the URL button.

Click the live preview button to see it working

Step 1 Live Preview

Step 2 - Create iobio Command

Add spinner

Add a spinner so that we can see when the app is doing work. Add it inside the container div at the end of the html file.

In the style tag at line 19, add some style to the spinner.

Create script element

Inside the body tag but at the very end of the html file, add a script tag. All of your JavaScript will go in here.

Add webservice as a default

We'll be using samtools to grab regions of a bam. So we'll use the standard samtools webservice located at All webservices follow this naming scheme e.g.,

Get data from URL

Create a function that can grab a region of data from any url pointing to a BAM file.

Get data from FILE

Create a function that can grab a region of data from any url pointing to a BAM file.

Run it

To see it working, open the default URL and click go. After a few seconds open the javascript console and you should see a bunch of SAM alignments. If you see them, then you are successfully streaming data to the web app.

Click the live preview button to see it working

Step 2 Live Preview

Step 3 - Create Visualization

Add div to hold visualization

At line 47 , add a div that we will later render the visualization into. .

Define dimensions of visualization

Add some dimension variables at the beginning of the script tag at line 67

Add visualization at the end of the script tag

We are going to use the alignment visualization from the iobio.viz library. This visualization can take a pileup and has some specific alignment features.

So it doesn't look like much now, but that will change when we hook up the real data, which we'll be doing in the next step. Also a few things to note:The pileup layout here does the heavy lifting for determining an efficient pileup. After the alignments are run through the pileup layout each alignment has an x and y coordinate. This keeps the chart simple and allows it to simply place each alignment based on these coordinates. The pileup returns data in the format of { x:xpos, y:ypos, data:{} ) where the original data is now stored in data. This is done so that nothing in your original data is overwritten. This is why the id accessor function grabs the id by doing

Click the live preview button to see it working

Step 3 Live Preview

Step 4 - Hook Up Data to Visualization

Add SAM/BAM helper parser functions

First we need to add some helper functions to parse the SAM/BAM records coming back. Add these at the end of the script tag. .

Remove temporary viz code

Remove the code in step 3 that we added to test the visualization. Lines 148 - 150.

Hook up URL data to visualization

At line 89 add the variable alns to hold the alignments coming back. Also replace the data event callback with this code. The data event gets called each time a message is delivered over the websocket. These messages aren't guaranteed to be a single record or even whole records, so we need to account for partial records.

Hook up FILE data to visualization

At line 115 replace console.log(alnseq). If you don't plan on testing file data, you can skip this bit.

Click the live preview button to see it working

Step 4 Live Preview

Step 5 - Improve visualization

Use arrows to show strandedness

Showing strandedness is built in to the alignment chart, so we can just add an extra attribute to our chart to get it to work. At line 161 we can add the direction attribute and give some information on how to determine if an alignment is forward or reverse. I've included the whole chart below, but you only have to add the last line. Also make sure to remove the semicolon from the .tooltip line below, since we are adding to our chained functions. .

Show mate pair

Lets say we want to emphasize mate pairs in this visualization. Here we can add some custom d3 code that is not part of the chart to get a magnifying effect. Add this right below where you call the chart, below line 168

Show mismatches and deletions

Finally, lets see if we can show some finer sequence information. We could add an element for each nucleotide, but that would increase our number of DOM objects by around 100X for the default URL BAM sample and even more for other samples. So instead we can be a little clever with color gradients to get the same effect. Here we'll use a color gradient to show mismatches as red and deletions as black. So we'll use the .color chart helper attribute to set the fill color for the alignment polygons. I've only included the last line of the chart for context. So add this new color attribute at [line 163]( right below the directionValue attribute we added above.

Click the live preview button to see it working

Step 5 Live Preview

Step 6 - Test the streaming!

One of the defining characteristics of iobio is its streaming nature. The visualization we've created (and all iobio.viz visualizations) can handle streaming data by default. To see this in action test a bigger region like this 20:4000000-4009000. This looks especially nice using the app.step4.html file, which has lots of colors. .


Explore Github

Important links

iobio website
iobio Apps
Marth Lab