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'
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:
`
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.
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’."