Developing IGB-fx

Now that IGB 9 is out the door and into the hands of users, the team and I are focusing our full attention on developing our all-new genome browser – IGB-fx.

We’re calling it IGB-fx because it uses JavaFX, the graphics toolkit that is replacing Swing in the world of Java-based user interfaces. But that’s only a small part of what makes it much better. The main innovation is that IGB-fx – built from the ground up – is 100% services based and modular. Yes, we are finally all-in for OSGi. IGB 9 and earlier versions were also services based, but there were too many interconnected classes and packages. Making changes to the code required understanding too much of it, which made adding new features too difficult. Since we are an academic, open source project in a rapidly changing field, we need a code base that exemplifies good engineering practices and is easy to modify. In other words, we need a strong foundation on a large lot with room to expand.

Recently, I wrote a quick start guide to building and running IGB-fx. Here, I’m going to describe the steps in more detail and also explain how to load data into the browser. I’ll also explain how to use our fork-and-branch workflow.

To get started, you need git, Apache maven, karafe, and Java 8. We use git for version control, maven (mvn) to compile IGB-fx, and the karafe OSGi container to run it. IGB-fx needs Java 8 because it uses lots of features new to Java 8, like lambdas.

To develop IGB-fx:

  1. Go to Bitbucket.org and sign up for a free account.
  2. Go to the IGB-fx team repository and fork the repository. Here’s how: On the IGB-fx team repository home page, click the Actions button (three dots, top left) and choose Fork. This makes a new IGB-fx fork belonging to your user id.
  3. Go to the Web page for your new fork on Bitbucket. Copy the git URL in the upper left.
  4. On your local computer, clone the project.
  5. After cloning the project, add the team repository as a new remote repository. You can name it whatever you like, but to be consistent with other projects, name it “upstream” like this:
git remote add upstream https://bitbucket.org/lorainelab/igb-fx

Now, you’re ready to build and run IGB-fx:

  1. Open a terminal window and change into your cloned fork.
  2. Build the project using maven.
  3. Start the karaf shell and use it to run IGB using the provided start-shell.sh script.

Commands to do the above are:

mvn clean install
start-shell.sh

Get some data and load it

If you have a fast internet connection, the fastest way to start viewing data in IGB is to open the human genome. Inside IGB-fx Current Genome tab, species Homo sapiens and genome version H_sapiens_Dec_2013 from the two menus. Gene models will load automatically. To load sequence, click the Load Sequence button. This will trigger downloading of a compressed copy of the human genome sequence. This works best on a faster internet connection.

If your internet connection is slow (10 Mbs or less), open a much smaller genome. The fruit fly or Arabidopsis genomes are about ten times smaller than the human genome, and so that are a good choice.

To get the fruit fly genome sequence and gene models annotations:

  1. Make a folder on your computer where you will keep these files long-term. If you move them, the IGB-fx prototype won’t be able to find them again.
  2. Go to the IGB Quickload site folder for the 2014 fruit fly genome.
  3. Download three files and move them into your local folder. The files are:
    1. compressed sequence file: D_melanogaster_Jul_2014.2bit
    2. compressed, indexed gene model file: D_melanogaster_Jul_2014.bed.gz
    3. index for gene model file: D_melanogaster_Jul_2014.bed.gz.tbi
  4. In IGB-fx, select FileĀ  > Open Custom Genome.
    1. Under Reference, choose the compressed sequence “2bit” file.
    2. Under Genome Version, type “D_melanogaster_July_2014″
    3. Under Species, type “Drosophila melanogster”
  5. Open the annotations file. In IGB-fx, select File > Load File. Select the compressed, indexed gene model file: D_melanogaster_Jul_2014.bed.gz. Note: you may have to uncompress it first.
  6. In IGB-fx, click “Load Data” to load gene models. Click “Load sequence” to load sequence data. To zoom in and see the sequence, click-drag over the number link or drag the slider to the right. Pan from side to side using the panning scrollers at the bottom of the display.

Students and collaborators developing IGB-fx should use the fork-and-branch workflow. This blog post does a great job of explaining it and Atlassian also provides excellent documentation. In a nutshell, when you start work on a new feature or bug fix:

  1. On your local computer, create a new branch.
  2. Make changes. Add and commit changes to your local clone.
  3. Push the changes to your fork on bitbucket.
  4. On the bitbucket page for your fork, create a pull request. The source should be your branch and the target should be the master branch of the team repository. (Recall you added the team repository as a remote called “upstream.”)
  5. Wait for review. Use the review feedback (if any) to correct problems or make improvements. Note that any new changes you push to your fork hosted on bitbucket will automatically get added to your pull request.

Once your pull request gets merged into the master branch, you should update your fork:

  1. In your local clone, switch to the master branch.
  2. Pull master branch changes – including your pull request – from the team repository, nicknamed “upstream”
  3. Merge these changes into your local clone.
  4. Push them to your fork to update it.