BlobToolKit API and viewer code
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
demo
src
test
.env.dist
CHANGELOG.md
INSTALL.md
LICENSE
README.md
package-lock.json
package.json
postcss.config.js
webpack.config.js

README.md

BlobToolKit Viewer (v0.5)

DOI

BlobToolKit Viewer is a genome-scale dataset visualistion tool developed as part of the blobtoolkit project to allow browser-based identification and filtering of target and non-target data in genome assemblies.

We are running the BlobToolKit insdc-pipeline on all public (INSDC registered) eukaryote genome assemblies and making the results available in an instance of this viewer at blobtoolkit.genomehubs.org.

Quick start guide:

  1. Install node/npm
conda create -n btk_viewer_env git nodejs
conda activate btk_viewer_env

Visit conda.io for instructions on how to install/run conda on your system. For other ways to install node, search your preferred package manager or visit nodejs.org.

  1. Install BlobToolKit Viewer
git clone https://github.com/blobtoolkit/viewer
cd viewer
npm install
  1. Start BlobToolKit Viewer
  • on Linux/OS X (start in a detached screen session)
cp .env.dist .env
screen -dmS btk_api npm run api
screen -dmS btk_client npm run client
  • on Windows (start in separate anaconda prompts)
xcopy .env.dist .env
# select option to copy as file
npm start

In a new Anaconda prompt:

conda activate btk_viewer_env
npm run client
  1. Visit site
http://localhost:8080/view/
  1. If you have started BlobToolKit in a detached screen session, attach to the screen session and use ctrl-c to quit:
screen -r btk_api
# (press ctrl-c)
screen -r btk_client
# (press ctrl-c)

Customisation

To run blobtoolkit on alternate ports, change the hostname or use a different data directory, change settings in the .env file:

NODE_ENV=local
BTK_CLIENT_PORT=8080
BTK_API_PORT=8000
BTK_API_URL=http://localhost:8000/api/v1
BTK_BASENAME=/view
BTK_HTTPS=false
BTK_ORIGINS='http://localhost:8080 http://localhost null'
BTK_HOST=localhost
BTK_FILE_PATH=
BTK_OUT_FILE_PATH=/dev/null

Use Local data

If you have already analysed a dataset using BlobTools, data can be exported from the BlobDB using the experimental view (currently requires the BlobToolKit fork of BlobTools):

blobtools view \
    -i assembly.BlobDB.json \
    -x "bestsumorder" \
    --experimental assembly.yaml

Any fields added to the assembly or taxon sections of an assembly.yaml file will be indexed for search. Fields that will be displayed (and should be filled in in a minimal assembly.yaml file) are shown below:

assembly:
  level: scaffold
  accession: draft
  prefix: Assembly_name
taxon:
  name: Genus species

To analyse a new assembly, the BlobToolKit pipeline can take an assembly and reads as input and automate all steps through to generating a dataset ready to load in the Viewer.

Production build

The exact settings will depend on your system, use the following as a guide for what may need changing:

  1. Modify your .env file for a production setting
NODE_ENV=production
BTK_CLIENT_PORT=8081
BTK_API_PORT=8002
BTK_API_URL=http://example.com/api/v1
BTK_BASENAME=/viewer
BTK_HTTPS=false
BTK_ORIGINS='http://example.com null'
BTK_HOST=example.com
BTK_FILE_PATH=/path/to/data
BTK_OUT_FILE_PATH=/dev/null
  1. Build and minify the client code
npm run build
  1. Move the contents of dist/public to a subdirectory of your webroot

  2. Configure your web server to redirect non-file requests to index.html to allow BlobToolKit Viewer to run as a single page app

  • e.g. for apache
  • activate mod_rewrite
  • set allowoverride to all
  • restart apache
  • add a .htaccess file to the subdirectoy containing the minified code
<ifModule mod_rewrite.c>
  RewriteEngine on
  RewriteCond %{REQUEST_FILENAME} -s [OR]
  RewriteCond %{REQUEST_FILENAME} -l [OR]
  RewriteCond %{REQUEST_FILENAME} -d
  RewriteRule ^.*$ - [NC,L]
  RewriteRule ^(.*) index.html [NC,L]
</ifModule>
  1. Start the api as in the quick start guide

  2. Visit site

http://example.com/viewer/

Query string/list parameters:

Most settings can be altered directly using the url, the list below provides an overview of most available settings:

  • xField=gc
  • yField=SRR000000_cov
  • zField=length
  • catField=bestsumorder_phylum
  • color0=gold
  • color1=purple
  • color2=rgb(255,0,0)
  • palette=user
  • gc--Min=0.32
  • gc--Max=0.58
  • gc--LimitMin=0
  • gc--LimitMax=1
  • gc--Inv=true|false
  • bestsumorder_phylum--Keys=3,7,12
  • bestsumorder_phylum--Order=Arthropoda,Echinodermata,no-hit
  • bestsumorder_superkingdom--Active=true
  • plotShape=square|hex|circle
  • plotResolution=30 (range: 5-50)
  • zReducer=sum|min|max|count|mean
  • zScale=scaleLog|scaleLinear|scaleSqrt