Skip to content

User manual

Jump to bottom
Patrick Durand edited this page Nov 19, 2016 · 2 revisions

Introduction

BioDocumentViewer, or BDV for short, is a software enabling to query, browse, fetch and retrieve sequences and 3D structures from NCBI and EBI public servers.

The software comes with ready-to-use services. However, you can also add your own retrieval services, as explained here.

This document details how to use the standard BDV edition.

###Start the graphical interface

After retrieving an official release of the BioDocumentViewer (BDV) software (see here), you can start it quite easily from a Terminal (Linux, Mac OSX and Windows):

java -jar biodocviewer-x.y.z.jar

Windows, Mac OSX systems: you can also double click on the "jar" file to start the software.

By default, BDV uses NCBI Entrez eUtils services (NCBI, Bethesda, USA) to let you query and retrieve protein and nucleotide sequences, 3D structures and taxonomy information.

However, you can also ask BDV to use EB-eye Search services (EBI, Hinxton, UK) as follows:

java -DV_PROVIDER=EBI -jar biodocviewer-x.y.z.jar

JVM argument "V_PROVIDER" accepts one of: NCBI (default) or EBI.

###Make and run a query

Whatever the data provider you use, NCBI or EBI, the software is quite easy to use:

  • select a bank to query
  • click on the [Go...] button
  • setup the criteria in the query dialogue box
  • click on the [Ok] button... and wait a few seconds to get an answer from the provider

The DocumentNavigator is displayed as soon as you get a valid answer from the bank provider, i.e. your query matches some entries.

Use the DocumentNavigator:

  • to navigate through entries; use [<] [>] buttons located at the top right corner
  • to display an entry in the Sequence or 3D Structure viewer
  • to fetch entries as Fasta or plain format (e.g. Genbank, EMBL, Uniprot, etc.)

###NCBI/EBI recommendations

BDV strictly respects the recommendations of NCBI and EBI for the use or their public resources, especially when retrieving sequences in batch mode.

These receommendations are:

  • keep in mind that you are using resources that are shared by many users around the world
  • do not overload NCBI/EBI remote servers
  • retrieve sequences in batch mode using timers
  • provide your email address: NCBI or EBI can get in touch with you in case they consider your are querying too much their remote services.

More about these recommendations: here for NCBI, here for EBI.

###Batch retrieval of sequences

Here is an example of DocumentNavigator retrieving more than 100K sequences from NCBI using a batch mode following NCBI recommendations:

###Extended configuration

BDV accepts the following optional JVM arguments on the command line:

  • V_DEBUG. Accepts one of: true, false. Default is false.
  • V_PROVIDER. Accepts one of: NCBI, EBI. Default is NCBI.
  • V_EMAIL. Your email address; see "NCBI/EBI recommendations" section, above. Default is none, so BDV will ask you that information at runtime, the first time you use the software.

You use all these arguments as follows:

java -DV_PROVIDER=EBI -DV_DEBUG=true ... -jar biodocviewer-x.y.z.jar

###Log viewer

BDV uses a logging framework to monitor the software.. This can be quite useful when you experience NCBI/EBI connections failure.

To access the log messages, simply click on the little icon located at the top right corner of BDV main frame, next to [Documents] pulldown menu.

By default, BDV uses "info" log level, which does not provide much messages. You can switch from "info" to "debug" level using BDV log viewer (see screenshot, below). In such a way, you can view more messages but you won't have full debug traces including classes/methods information. To enable that feature, you are advised to start BDV with "-DV_DEBUG=true" to get full log messages.

It is worth noting that log messages are localized in your country; e.g. below screenshot is made on a French localized Mac OSX system:

Clone this wiki locally