|
| Quick JBrowse tutorial
This quick guide on how to set up JBrowse should no doubt be regarded as experimental, etc.
install pre-requisites
- BioPerl, JSON (e.g. from CPAN command-line client)
- or skip to next step and get an Amazon EC2 machine image
Installing Bioperl on an Apple OS X machine can be problematic; you may find it necessary to do a force install from CPAN, if the regular installation fails repeatedly.
download the source
Do one of the following:
The public git clone syntax is
git clone git://github.com/jbrowse/jbrowse.git
To do git clone, you need to install the Git software (Wikipedia) .
After git clone (or tar -xvzf), enter the top-level jbrowse directory
cd jbrowse
Everything from now on assumes you are sitting in the root directory of the cloned (or otherwise downloaded) repository.
compile binaries
To build the C++ parts (only WIG tracks currently require this, for the wig2png program),
type
make
On an Apple OS X machine, you may need to edit the Makefile to add libpng and png.h to your compiler's library & include paths.
- e.g.
make GCC_LIB_ARGS=-L/opt/local/lib GCC_INC_ARGS=-I/opt/local/include
- or somewhere like
/usr/X11R6
- Try
locate libpng
three easy steps
Prepare (i) reference sequences, (ii) tracks, (iii) name index.
See workflow diagram for overview.
stick yer annotations here
run some scripts
We will now walk through each preparation step individually.
In what follows, a number of Perl scripts in the bin/ directory are referred to (e.g. bin/prepare-refseqs.pl).
Running any of these scripts without any options should display a short help message.
sequences
First you have to break the reference sequences, specified in your FASTA file, into chunks.
tracks
Next you have to prepare your annotation tracks.
These can include co-ordinates of genes and other finite elements, specified in GFF files...
...or they can include quantitative tracks (histograms), specified in WIG files.
A variety of command-line arguments to these two scripts can be used to change the appearance and layout of tracks.
The scripts can be run repeatedly to add multiple tracks from different data sources.
names
Your feature co-ordinate tracks will be navigable by feature name, through a text box.
After generating the tracks, you have to build a name index:
On linux machines with SELinux enabled (Fedora, recent Cent OS and Red Hat) you need to mark the files generated by generate-names.pl as servable by apache. To see if SELinux is enabled, run the "getenforce" command. If it replies "Enforcing", then you need to run an additional command after generate-names.pl:
chcon -R -t httpd_sys_content_t names/
If getenforce replies with something else, or if there's no getenforce command on your machine, then you don't need to worry about it.
point yr browser here
We assume Apache can see where you are, yes?
For (rather fragile) reference/debugging purposes, here are the files you should expect to be able to access
Downloaded with git repository
- index.html
- genome.css
- js/
- jslib/
Generated by preparation scripts (& JsonGenerator , NCList , LazyPatricia, ... packages in lib/)
- data/
- refSeqs.js
- trackInfo.js
- tracks/
- tiles/
- names/
(Fragile, because this stuff may change as the code matures. But potentially useful for alpha-test troubleshooting)
additional sections
the makefile
An example Makefile is provided (as part of the TWiki plugin) which uses suffix rules to implement the workflow shown in the diagram
more-or-less exactly, with a few typical GNU make kludges (e.g. symlinking files into temporary directories, touching empty targets, etc.)
Please note that the Makefile is provided to illustrate script usage, and possibly to help write plugins (such as the TWiki plugin); it's NOT intended as a supported serverside interface to the preparation scripts.
To run all preparation scripts on default (basic) settings, assuming your annotation files all have the correct filename suffices and reside in the current directory, just type:
make jbrowse -f twiki/JBrowsePlugin/Makefile.jbrowse
This runs all three preparation steps for you (sequences, tracks & feature names).
The default Makefile rules recognize
.fasta, .gff, .bed, and/or .wig
as valid (case-sensitive) filename suffices and associated file types.
The effective "annotation data source" (c.f. this diagram) is the current working directory.
The Makefile also recognizes an optional track configuration file, config.js.
In theory you should now be able to point your browser at this directory and start browsing anotations.
In practice you will typically want to hand-walk the process a little more than this.
file formats & suffix rules
The following file types are automatically recognized by the Makefile, via the filename suffix:
example "genome wiki" using makefile
This is a simple "JBrowse plugin" for the TWiki wiki management system.
It runs the JBrowse Makefile on uploaded data files whenever a user attaches a file to a wiki page.
build from database
The power tool of JBrowse scripts:
A more flexible alternative to flatfile-to-json.pl.
the config file
The JBrowse config file, read by biodb-to-json.pl, controls the rendering of feature tracks from a single data source.
The data source can be Chado, or it can be another Bioperl-compatible database -- including, for example, a simple GFF file.
The full documentation for the config file is at docs/config.html in the git repository.
using config files with make
It's possible to use snippets of JBrowse config files with the included Makefile, to control generation of feature tracks from GFF files in the current directory,
but this functionality is currently limited.
If a config.js file is present in the current working directory,
containing a list of tracks to make from a GFF file,
the Makefile will run biodb-to-json.pl on every GFF file instead of flatfile-to-json.pl.
NB the config.js file should include only the track descriptions from the full JBrowse config file;
that is, where the JBrowse config file has this...
{
"description": "blah",
"db_adaptor": "blah blah,
"db_args": { ... },
"TRACK DEFAULTS": { ... },
"tracks" : [ X, Y, Z ]
}
...the config.js file should have only this...
X, Y, Z
The rest is autogenerated by the Makefile.
It's probably just as easy to write a complete JBrowse config file (see above) and run biodb-to-json.pl directly.
building from chado
more to follow here, we hope... or add your own comments on serving JBrowse from Chado...
example: flybase
WRITE ME!
workflow diagram
Boxes indicate scripts; circles are data files (inputs & outputs).
The outputs of the key preparation steps are bold ovals.
Dashed lines show alternate/optional steps.
biodb-to-json can replace flatfile-to-json for a richer set of configuration options (e.g. working directly from a Bioperl database).
This workflow is more-or-less exactly implemented by the example Makefile and the TWiki Plugin.
Like winter's bare branch
functions and statements sloughed off
tree-structured json
-- ChrisMungall, MitchSkinner, IanHolmes (c) EvolutionarySoftwareFoundation - 20 Mar 2009 |
