Welcome to cgpJBrowseToolkit’s documentation!

General

This project is provides scripts and tools which work with or on JBrowse that are considered publicly useful.

jbrowse_rasterize.js

Generate screenshots from your JBrowse instance using the URL and a BED file of locations of interest.

Benefits over phantomjs rasterize.js

The advantages of this over looping on the standard phantomjs rasterize.js are:

• Cache of data is maintained.
• Also works with sites secured with http_basic (see HTTP-BASIC authentication).
• Trims/expands images to correct height.
• Handles variable track loading time by monitoring network activity/
• Hides tracklist automatically.

Usage

See command line help for most current options:

$ js/jbrowse_rasterize.js --help
Usage: jbrowse_rasterize [options]

Generate images against a JBrowse server


Options:

  -l, --locs <file>        Bed file of locations, see --help
  -b, --baseUrl [value]    URL from pre configured JBrowse webpage, ommit if provided in BED file
  -w, --width [n]          Width of image (default: 600)
  -i, --imgType [value]    Type of image (jpeg|png) (default: png)
  -o, --outdir [value]     Output folder (default: ./)
  -n, --navOff             Remove nav bars
      --highlight          Highlight region (for short events)
  -q, --quality [n]        Image resolution (1..3) (default: 3)
  -p, --passwdFile [file]  User password for httpBasic
  -t, --timeout [n]        For each track allow upto N sec. (default: 10)
  -v, --version            output the version number
  -h, --help               output usage information

Additional information:

Image quality:
  Best image quality is achieved with:
    --imgType png --quality 3


--locs bed file:

  Can include comment lines to switch the baseUrl used for the next block of
  coordinates.

  Any comment line will be processed into a datasource ($DS) name and URL.  Files generated will be
  output to a subfolder of the specified --output area as $OUTPUT/$DS/$CHR-$START_$END.

  FORMAT:

    # DATASET_NAME URL
    CHR START END
    # DATASET_NAME2 URL
    CHR START END
    ...

Usage is simple, set up the display with relevant tracks in the browser and provide the updated URL it to the script:

$ jbrowse_rasterize.js \
--width 1200 \
--imgType png \
--locs test/volvox.bed \
--outdir wibble1 \
--baseUrl 'http://jbrowse.org/code/JBrowse-1.12.4/?tracks=DNA%2CTranscript%2Cvolvox-sorted_bam_coverage%2Cvolvox-sorted_bam&data=sample_data%2Fjson%2Fvolvox'

Command line args

Argument	Required	Type/Values	Description
locs	Yes	*.bed	Bed file of locations to snapshot, not bgzip’ed.
baseUrl	No *	URL	JBrowse URL to base all snapshots on, unless defined in bed file.
width	Yes	integer	Width in pixels for generated image.
imgType	Yes	pdf|jpeg	Type of image to generate.
outdir	Yes	path	Output folder.
navOff	No	N/A	Presence causes the navigation panel to be excluded.
highlight	No	N/A	Highlights the targeted range, for use with short events where JBrowse pads image.
quality	No	1,2,3	Resolution of image, 3 = best
passwdFile	No	path	Path to file containing password (please secure).
timeout	No	integer	Extends the default MAX timeout per track.
version	No	N/A	Output version of script and exit when found.
help	No	N/A	Prints help text.

HTTP-BASIC authentication

To use this with a site secured with http_basic you need to provide your password for the authentication phase. To do this under casperjs it’s being read from a file (if you know of a better way please get in touch).

Please set permissions accordingly, don’t expose your password on a network drive.

Other:

• Sites not requiring auth load silently.
• If not provided when required you will see the message:: ERROR: Check you connection and if you need to provide a password (http error code: 401)

Tested track types

All testing carried out under JBrowse 1.12.3 rc1 onwards.

Functionality of the following tracks has been tested:

• Alignments2
• VCF
• XYplot
• CanvasFeatures
• Sequence

Known issues

• multibigwig - plugin track will only render with v0.7.0+

Please report any problems with other track types on the GitHub issue tracker

Installation

Requires a working installation of node with the following npm modules:

• commander
• puppeteer
• mkdirp

` npm install commander puppeteer mkdirp `

Installation of jbrowse_rasterize can be achieved a number of ways but the simplest is:

export VERSION=master # or version number, e.g. 1.1.0
export JBTK=https://raw.githubusercontent.com/cancerit/cgpJBrowseToolkit
curl -sSL  $JBTK/$VERSION/js/jbrowse_rasterize.js> $HOME/local/bin/jbrowse_rasterize.js
chmod u+x $HOME/local/bin/jbrowse_rasterize.js

How jbrowse_rasterize works

jbrowse_rasterize now uses Puppeteer which allows testing for network activity to cease before indicating a page has completed rendering.

There is no longer a guess as to how long it will take for elements to have completed drawing as

Prior to 2.0

The ability to take screenshots in JBrowse is made diffcult by there being no true end-point to the generation of a view. All actions are asynchronous with no single testable variable or element.

jbrowse_rasterize attempted to compensate for this by testing several critical elements of the DOM:

document.readyState === "complete" &&
document.getElementsByClassName('innerTrackContainer')[0].getElementsByClassName('track').length === trackCount+1 &&
document.getElementsByClassName('loading').length === 0

trackCount needs +1 to account for the grid background track.

CHANGES

License

The project is licensed under the GNU Affero General Public License v3.0 license:

Copyright (c) 2016-2018 Genome Research Ltd.

Author: Cancer Genome Project <cgpit@sanger.ac.uk>

This file is part of cgpJBrowseToolkit.

cgpJBrowseToolkit is free software: you can redistribute it and/or modify it under
the terms of the GNU Affero General Public License as published by the Free
Software Foundation; either version 3 of the License, or (at your option) any
later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.

1. The usage of a range of years within a copyright statement contained within
this distribution should be interpreted as being equivalent to a list of years
including the first and last year specified and all consecutive years between
them. For example, a copyright statement that reads ‘Copyright (c) 2005, 2007-
2009, 2011-2012’ should be interpreted as being identical to a statement that
reads ‘Copyright (c) 2005, 2007, 2008, 2009, 2011, 2012’ and a copyright
statement that reads ‘Copyright (c) 2005-2012’ should be interpreted as being
identical to a statement that reads ‘Copyright (c) 2005, 2006, 2007, 2008,
2009, 2010, 2011, 2012’."