Juicebox Documentation

Software for visualizing data from Hi-C and other proximity mapping experiments

Start exploring Juicebox using the video and information below!

Quick Start Video

Quick Start Guide

Once you've successfully launched Juicebox, click File→Open to load a new Hi-C map. All of the Hi-C maps from our Cell paper are available. Click GM12878, in situ MboI, combined (4.9B) to open our largest map: the combined primary and replicate GM12878 library.


Juicebox will load the map and show all chromosomes.



Click on chromosome 17. This can be done either by selecting 17 x 17 below the Chromosome section on the toolbar and hitting the refresh button, or by clicking on chromosome 17 itself. Using the selector below Normalization, change the normalization to Balanced. Slide the resolution slider to 5 KB.



Use your mouse to pan until your range is roughly 64,500 kb to 69,000 kb. Alternatively, in the Go panel, type 17:64500000-69000000 in both boxes and hit the refresh button.

Now click Annotations in the menu bar and go to Load Basic Annotations. Select the Dataset Specific 2-D Features for this map.



You will see a series of yellow boxes and cyan points loaded. The cyan points denote the exact peaks; therefore, we predict that they will be relatively small.



These are the contact domains and peaks that we found when analyzing this map. Now let's see what other annotations look like here. Go to the Annotations menu and click Load Basic Annotations again. Click on GM12878 and select the H3K36me3 track and the CTCF track.



You can line up what you see in the heat map with the tracks. Right click on the heat map and select Enable straight edge. Then move around on the map to see the features lined up with the tracks.

There are many more functions to explore in Juicebox -- enjoy!

Start exploring Juicebox using the tutorial below!

Getting Oriented



  1. Main menu. From the File menu, you can open maps, load control maps, see dataset metrics, and export an image. From the Annotations menu, you can load one dimensional and two dimensional features and see them alongside the Hi-C map. From the Bookmarks menu, you can save your location to load it again later.
  2. Toolbar. Select chromosomes, switch between Observed, Observed/Expected, Control, and other views, adjust normalization, change the resolution, fine-tune the color range, or go to a specific location in the map.
  3. Heat map. This is where the heat maps load. You can pan by grabbing the map with the mouse and moving; double-clicking zooms in. You can also zoom in by holding down ALT key and drawing a box around a region of interest.
  4. Mini Map. You can see where you are within a chromosome at any time from the mini map. You can move the transparent square in the mini map to quickly change the main map.
  5. Information pane. When the mouse moves over the heat map, the text in the pane is updated with information about the specific Hi-C pixel. When features are loaded on the map, detailed information about them appears here.

Loading Maps

  • From the File menu, clicking Open or Open Control will bring up a list of all of the Hi-C maps from our Cell paper.
          
    Click on the folders to find maps within that cell type. Double-clicking on the name of a map will load it. Alternatively, you can either click the button Open MAPQ > 0, or select the arrow next to the button and you'll see the option to Open MAPQ > 30. You can select multiple maps to load by holding down the Ctrl key or Apple key, or by holding down the Shift key and selecting a series. The maps will be summed together when loaded.
  • Load a control map after opening a map if you wish to see one map divided by another; more on this in the Exploring the Data section.
  • When choosing to load a HiC file under the Open File menu, you will notice a text box in the bottom right corner of the Open window. This is a case-sensitive search filter that allows you to search for HIC files by name or number. If a file contains the string that you search, a file path will be opened and the matching text will be highlighted in red. You are also able to search for multiple files by separating your searches with commas. If there is a match for the other files that you search for, the text will be highlighted in other colors.
    pic of search/multi search
  • The Open Recent menu will be populated with the maps you've opened most recently.
  • Once you've loaded a map, Show Dataset Metrics displays statistics about the map. The About Library tab contains information about how the experiment was conducted. The Statistics tab contains quality control statistics you can use to judge the quality of the library (see our Supplemental Materials for more).

    The next tabs are different graphs with other ways to visualize the statistics. The Pair Type graph has each pair type versus how far apart they are. The Restriction tab contains the distance from the closest restriction enzyme site. The Intra vs Distance is a cumulative sum of the reads versus the distance between them. The MapQ tab is a histogram of the reads at different MapQ thresholds.
  • Export the map as an image by selecting Export Image. You can choose where to save it and at what size.

Loading Annotations

  • Load basic annotations
    Make sure you have a Hi-C map open. From the Annotations menu, click Load Basic Annotations...

    A pop up window titled Available Features will appear.

    Check the required feature(s) and press "OK".
    The new annotation will be downloaded to your Juicebox viewer and displayed above and to the left of the main map window. Note that some annotations, like the gene track are clickable, showing more information.
    In order to remove the annotation, right click on the track, and select "Remove track", or you can also repeat the steps above and uncheck the annotation(s) you want to remove. Additional annotations include:

    Gene reference:

    Coverage annotation:

    GM12878 CTCF orientation annotation:

    Eigenvector:

  • Loading 1D Tracks
    You can also load you your own bed or wig track files. From the Annotations menu, click Load Basic Annotations...
    Click Add 1D.... A file explorer window will open. Select your track file. The new track file name will appear in Available Features menu. Click "OK" to show your track.
    In case of an unsupported file format, the following error will be displayed:

  • Adding 2D annotations
    Some of the annotations in Juicebox are marked on the main map. An example is available in the GM2878 in situ MBOI primary + replicate map. After opening this map, a "Data-set specific 2D features" annotations are available in the annotations menu. Use the F2 key to toggle the visibility of 2D annotations.
    In order to create your own 2D annotation files, simply follow the following file format:

    chr1 x1 x2 chr2 y1 y2 color comment
    chrX 85000000 89000000 chrX 85000000 89000000 0,255,0 My green region
    chrX 90000000 99100000 chrX 90000000 99100000 0,0,255 My blue region

    Saving the example as a text file and loading to Juicebox will show the following result:

    Note:
    1. Make sure your chromosome names are the same as the ones that appear in the Hi-C map.
    2. Keep the header line.
    3. The file is tab delimited.
  • Custom Annotations

    You can also create custom data-specific 2D annotations to visualize peaks and domains. In order to create a custom annotation, open a Juicebox map (GM2878 in situ MBOI primary + replicate, for example) and hold the shift key over a region of the map. A moving cross-hairs will appear as you move the mouse.

    In order to create a custom 2D annotation for a particular region of interest, hover the mouse over a region of the map that is enriched higher compared to the surrounding area. By clicking on this region, a small box will appear on both sides of the diagonal line indicating the successful annotation.

    To create a custom annotation for a broader region, hold the shift key and use the mouse to again create the moving cross hairs. Click and drag the mouse to highlight a square around the area that is to be annotated. A green rectangle will appear and border the region of interest. If you annotate close to the diagonal, the annotation will auto-capture the region as a square.
  • Load ENCODE tracks

    You can also use Juicebox to display ENCODE tracks. From the annotations menu, click Load Basic Annotations...
    Click Load ENCODE Tracks. The Encode Production Data screen will appear:
    You can use free text to search through any of the track fields, or scroll through the tracks list. Check the required ENCODE track(s) and click "Load" to load the data. A track will be added to top and left of the main map.
  • Configure tracks
    With some tracks, you can change basic appearance. Right click on a track and select Configure track....
    A new screen will appear, where you can change track Name, Min/Max values Scale, and colors for positive and negative values.

Custom Annotations

  • Creating Hand Annotations
    You can also create custom data-specific 2D annotations to visualize peaks and domains. In order to create a custom annotation, open a Juicebox map (GM2878 in situ MBOI primary + replicate, for example) and hold the shift key over a region of the map. A moving cross-hairs will appear as you move the mouse.

    In order to create a custom 2D annotation for a particular region of interest, hover the mouse over a region of the map that is enriched higher compared to the surrounding area. Hold the shift key and use the mouse to again create the moving cross hairs. Click and drag the mouse to highlight a square around the area that is to be annotated. A green rectangle will appear and border the region of interest. If you annotate close to the diagonal, the annotation will snap the corners of the annotation onto the diagonal.
  • Editing Annotations
    Annotations can be edited within Juicebox. Users can adjust an annotation's position, delete it, change its color, or add a text attribute to document any interesting features. Hand annotations can be edited directly, following the directions below. Loaded 2D annotations can also be edited by copying them to hand annotations. To do this, load a basic 2D annotation, then go to Annotations > 2D Annotations > Copy to Hand Annotations. The loaded annotation can now be edited as a hand annotation.
  • Adjusting Size


    To adjust the size of the annotation, hover over the upper lefthand or lower righthand corner, inside of the annotation.



    Click and drag the corner to the desired size. Release the mouse to create the change.



  • Adding/Changing Attributes


    Attributes can be added to annotations to mark interesting features. For example, an attribute name could be "Feature Quality", and its value could be "Poor,""High," etc. To add an attribute, right click an annotation and go to Configure Feature > Change Attributes. An attribute can be added by entering a name, or descriptive category, and value. The attribute will be displayed as a part of the hover text on the righthand bar of the main window.



    To edit an attribute, right click an annotation, go to Configure Feature < Change Attributes. The value of the attribute can now be changed, as shown below.



  • Changing Color


    The color of an annotation can be changed by right clicking an annotation and going to Configure Feature > Change Color.

  • Deleting


    Individual annotations can be deleted by right clicking an annotation and going to Configure Feature > Delete. The last added annotation can also be removed by going to Annotations > Hand Annotations > Undo Annotation, or by pressing "Z," the shortcut key.

  • Exporting Hand Annotations


    A set of hand annotations can be exported by going to Annotations > Hand Annotations > Export...

    Exported annotations can be loaded as a basic 2D annotation, by selecting the file by going to Annotations > Load Basic Annotations... > Add 2D...

Exploring the Data

  • Navigating the map
    • Chromosome drop down menu
      In order to show different location on the map, use the chromosome selector on the top right size of the menu bar.
      Select both chromosomes for x and y axis, and click on the purple refresh arrows to load.
    • Mini-Map
      You can also navigate the map by clicking on the birds-view map on the right side of the screen.
    • Choose Zoom Area
      You can use alt key + click and drag on the main map to draw a rectangle. Release the mouse to complete your selection. The map will zoom into the selected area.
    • Resolution slider
      Use the resolution selector to choose zoom level. Alternatively, double-click on any area in the main map to zoom in.
    • Goto Box
      Use the Goto Box in the upper left corner, and choose a position for the X and Y axis. The Format is
      chr:x1-x2:[BP Resolution]
      chr1:39500001-39750000:250000

      The Resolution is optional. You can also right-click in the heat map and select copy position to clipboard. This will save the current position in the Goto Box. You can also search for a human or mouse gene using its official symbol (e.g. HOXC9).
    • Superzoom
      You can enlarge a region while locking the resolution by using the lock button in the resolution menu. Do this by pressing the lock button, and then selecting a region using the alt key while dragging the mouse. The map will zoom in on the selected region, but will not change the resolution.

  • Compare maps and annotations
    • Control Map After opening a Hi-C map, load a second Hi-C map as a control to compare features in the two maps. From the File menu, click Open control... and select a second map from the list. The title of Juicebox will now show both the names of map and the control loaded.
      Using the Show menu, select Observed to show the main map.
      Using the Show menu, select Control to show the control map.
      Using the Show menu, select Observed/Control to show differences between the maps.
      You can also use the F1 key to switch between the observed main map and the control map.
    • Multiple Maps
      You can open multiple Juicebox windows simultaneously to compare regions. Juicebox also supports location and resolution syncronization between the open windows.
      • Continuous Sync
        Open a second session of Juicebox, and open a map. Arrange the maps side by side and choose a position on one of the maps. Right click the main map, and select Continuous Sync. The two Juicebox sessions will show the same position. The second map will track the location in the first map until the Continuous Sync option is toggled off.
      • Single Sync
        If you are only interested in a single synchronization between the two maps, right-click the map and select Single Sync. This will cause the second Juicebox session to reposition to the location of the first, but will not continuosly sync with the first session.
    • Straight edge
      Use the straight edge to highlight current mouse positions on the map and annotations. Right click on the main map, and select Straight Edge to toggle the feature on and off.
    • Freeze hover text, copy While the mouse hovers over the heat map, information about the position and map features appears in the information pane on the right side. In order to freeze that pane and copy the information, right click and toggle the Freeze Hover Text option. Use the mouse to select the text in the information pane, and copy the data to the clipboard.

  • Change Data Views
    • O/E, Pearson, Expected
      From the menu bar, select the Show scroll down menu. Besides the default Expected view, you can also display additional options.
      The Expected view shows the expected reference map - increasing distance between loci decreases contact frequency.
      The Observed/Expected view shows contacts as a ratio of the observed value map to the the expected reference map.
      The Pearson view shows patterns of correlation between loci.
    • Color slider
      Use the left and right handles of the color slider to set the minimum and maximum values for the map color range respectively. Use the +/- buttons to increase or decrease the overall slider range.
      You can also click the Color Range label to set the minimum and maximum values using a dialog box.
      Setting the values will adjust the color saturation of the heat map with in-between color values linearly interpolated. As an example, this would recalibrate the color range values:
      before
      after
    • Normalizations
      The normalization tool gives you the option to choose between different balancing algorithms used to to remove known biases from the Hi-C matrix. Depending on the map viewed, different balancing options are presented. We recommend using Balanced - the Knight-Ruiz balancing algorithm.

      For more information, read the supplemental materials of the 2014 Cell paper.

Bookmarks

Loading Location
You can use the Bookmarks menu to save and restore location and resolution data. Select Bookmarks and choose Save current location. A pop up window will appear and ask for a name to associate with the position. Enter a description for the new bookmark. Choosing Restore saved location will then navigate immediately to the location and resolution in the current map. The location can also be opened in another map. Saved location are kept in registry and can be used after restarting Juicebox.

Save State
Under the Bookmarks menu, there is an option to Save current state which allows you to save your current workspace, or state, in Juicebox. A state includes the loaded HiC map, matrix type, location, normalization, loaded tracks, etc.
Pic of bookmark menu/save current state option

You have the option to reload these states by going to the Restore previous states option under the Bookmarks tab, which will be filled with a list of your saved states.

pic of restore previous states
Upon clicking the Save current state option, you will be prompted to select a name for your current state. If a state with that name already exists, you have the option to rename it or to overwrite it.
pic of yes/no pane for overwrite
Under the Bookmarks tab, there are options Export Saved States and Import States From File which allow you to share your “saved states” with other Juicebox users.
pic of import/export option
When exporting a file, you can choose what to name your file and where to save it. You can share your states with others through E-mail, Dropbox, etc.

In order to import a file of saved states that someone has shared with you, click on Import States From File. When you go under the Restore previous states menu, it will be filled with a list of the valid states that the person has shared with you. If you import a file of states, but you already have states saved in your Juicebox, they will be exported to a file called OriginalSavedStates.xml

Citing Juicebox

If you use Juicebox in your research, please cite:

Neva C. Durand*, James T. Robinson*, Muhammad S. Shamim, Ido Machol, Jill P. Mesirov, Eric S. Lander, and Erez Lieberman Aiden. "Juicebox provides a visualization system for Hi-C contact maps with unlimited zoom." Cell Systems 3(1), 2016.

Suhas S.P. Rao*, Miriam H. Huntley*, Neva C. Durand, Elena K. Stamenova, Ivan D. Bochkov, James T. Robinson, Adrian L. Sanborn, Ido Machol, Arina D. Omer, Eric S. Lander, Erez Lieberman Aiden. "A 3D Map of the Human Genome at Kilobase Resolution Reveals Principles of Chromatin Looping." Cell 159, 2014.

* contributed equally