  Bioverse Viewer HOWTO
  Aaron Chang, Jason McDermott, and Ram Samudrala
  (viewer@bioverse.compbio.washington.edu)
  v2, January 16, 2006

  Documentation for the Bioverse Viewer and software to visualise inter-
  actomes.

  [1m1.  Introduction[0m

  The Bioverse Viewer is a Java graph applet based on code developed by
  the Sun Corporation <http://www.sun.com> and Ralph Mrowka
  <http://www.charite.de/ch/physio/HK/ag/mrowka.html>. It is small,
  multi-platform, and flexible for use with any interactome data set.
  All that is required is a Java-enabled web browser. See an example
  <http://bioverse.compbio.washington.edu/escherichia-
  coli/explore/contextual> using protein-protein interaction data from
  [4mEscherichia[24m [4mcoli[24m.  It is available as a web-based application
  <http://bioverse.compbio.washington.edu/viewer/> and can also be
  downloaded as a standalone application
  <http://software.compbio.washington.edu/bioverse_viewer/bioverse_viewer.tgz>.

  [1m2.  Initial setup and configuration[0m

  [1m2.1.  Recommended browsers[0m

  [1mMozilla Firefox <[22mhttp://www.mozilla.org/products/firefox/>.

  [1mApple Safari <[22mhttp://www.apple.com/safari/>.

  [1mMicrosoft Internet Explorer (IE)[0m
  [1m<[22mhttp://www.microsoft.com/windows/ie/default.mspx>.

  Make sure Java is enabled in all browsers. For IE, use Java 2 vXXX.

  [1m2.2.  Java installation[0m

  For Windows XP and Linux, download the runtime Edition (JRE) 1.4.2_xx
  for Windows XP and Linux from Sun:
  http://java.sun.com/j2se/1.4.2/download.html.

  For Apple OS X (10.3), download from Apple:
  http://www.apple.com/support/downloads/javaupdate142.html.

  [1m3.  Usage[0m

  [1m3.1.  Usage via the web[0m

  The Bioverse Viewer may be accessed through the Bioverse framework
  <http://bioverse.compbio.washington.edu>, where you can visualise
  predicted protein interaction networks for more than 50 organisms with
  detailed annotations, and through a dedicated Bioverse Viewer
  <http://bioverse.compbio.washington.edu/viewer/> interface, where you
  also have the ability to upload user-supplied interactome data.

  A typical graph view consists of a toolbar and a graph window. The
  toolbar contains a search field, freeze option (which stops the
  relaxation layout algorithm), drop-down functional annotation menu,
  distance selector (distance from selected node), screen refresh
  button, and total node/edge count. Test each feature out to see what
  it does.



  Searches can be performed by typing in the exact node label you're
  looking for, or by using a wildcard asterisk (*) character. Note that
  wildcarding can only be used following a specific character, and only
  once per search term.  If the search fails, a random set of nodes will
  appear. If no matches are found, a message indicating "No match" will
  appear in the search field.  Search terms are case-sensitive.


  Using the left mouse button, select a specific node. It will turn
  green. All neighboring nodes up to a distance selected will highlight
  as yellow. Nodes outside of this neighborhood will be gray. Undirected
  edges with weights will appear according to a color code where green
  denotes the highest confidence, red denotes the lower, and orange and
  yellow denote intermediate confidences.



  Individual nodes can also be dragged by holding down on the left
  button on a specific node. Double-clicking on a node will isolate the
  immediate neighbors around that node, removing other nodes that lie
  outside of the neighborhood set by the distance menu. Right-button
  clicking on a node will display a hyperlinked record file for a given
  node, as well as expand that node for neighbors. The URL path, as well
  as all the relevant node and edge data, is stored as HTML parameters
  in the page that displays the applet.

  A drop-down menu to select only proteins in particular functional
  category is available.  Graph navigation can begin as before.



  [1m3.1.1.  Visualising user-supplied data[0m

  The dedicated Bioverse Viewer
  <http://bioverse.compbio.washington.edu/viewer/> interface enables you
  to upload user-supplied interactome data and visualise it using our
  interface. You can upload a list of interactions and confidences in a
  comma-separated value (csv) file format. You can also optionally
  upload a list descriptions for each of the nodes in the interaction
  file.  Detailed description of these formats is given in the
  documentation for the ``csv2html'' script, and example interaction
  <example_interaction_list.csv> and function
  <example_function_list.csv> list files in csv format are available.

  [1m3.2.  Usage as a standalone application (download source code)[0m

  [1m3.2.1.  Download source code[0m

  The source code may be downloaded at
  http://software.compbio.washington.edu/bioverse_viewer/bioverse_viewer.tgz.
  An HTML file listing the details of the interactome needs to be
  created and the viewer called from within the HTML file. Be sure to
  modify the codebase parameter properly to the path containing the
  compiled ViewerApplet.class file.

  [1m3.2.2.  Format of HTML file[0m

  HTML pages should embed the node, edge, and functional data using the
  following format. Note that the three key data parameters are the
  functionlist, interaction, and functionkey. These parameters are
  consistent with the original Mrowka viewer
  <http://www.charite.de/bioinformatics/interaction/>. However, please
  note that the contents of the data are different in our version.
  functionlist relate node labels to molecule identifiers.  In the
  Bioverse framework <http://bioverse.compbio.washington.edu>, we employ
  a numerical identifier system for proteins. The interaction parameter
  contains the edges between nodes, using the node labels, separated by
  the edge weights. Finally, the functionkey contains two pieces of
  data. The first parameter, if provided, is the URL pattern used to
  hyperlink individual nodes to other detailed record pages. The rest of
  the data contains the functional classes that each protein (identified
  by record ID) belongs to. This data is used for the functional
  annotation drop down menu.

  An example HTML page that is commented in detail is available at
  http://bioverse.compbio.washington.edu/viewer/example.html. Please
  review the comments in the code by viewing the source. Note that this
  is only a fragment of a file, used for instructional purposes. To see
  an actual working file, look at the page source from a Bioverse
  predicted network <http://bioverse.compbio.washington.edu/escherichia-
  coli/explore/contextual>. It is also important to keep in mind that
  this viewer can at most display 400 nodes simultaneously.

  [1m3.2.3.  Using csv2html to create HTML files[0m

  Usage: csv2html [4minteraction-file[24m [[4mfunction-list-file[24m]

  Rather than try to figure out how to code the HTML files, this
  convenient program, available in the src/scripts directory in the
  source distribution
  <http://software.compbio.washington.edu/bioverse_viewer/bioverse_viewer.tgz>,
  can be used. It takes two comma-separated value (csv) files as input
  and generates an HTML page that can be used with the Bioverse Viewer.
  The first file specifies the list of interactions in this form:



       molecule1,molecule2,confidence
       molecule2,molecule3,confidence
       molecule3,molecule1,confidence



  where confidence is a value ranging from 0 to 1 indicating the
  strength of the relationship between the two molecules denoted by a
  single-word identifier.

  The second file, which is optional, is a list of descriptions (such as
  functional descriptions) for the interacting molecules from the first
  file. This is specified in this form:



       molecule1,description1
       molecule2,description2
       molecule3,description3



  where description may be an arbitrary string containing any of the 26
  letters in the English alphabet. Example interaction
  <example_interaction_list.csv> and function
  <example_function_list.csv> list files in csv format are available.

  [1m4.  Implementation notes and code history[0m

  [1m4.1.  Implementation notes[0m

  The Bioverse Viewer is composed of five classes (see the Javadoc
  <http://bioverse.compbio.washington.edu/viewer/doc/javadoc> for more
  detail):


  +o  GoInfo.java - functional annotation object

  +o  Interaction.java - edge object

  +o  Node.java - node object

  +o  ViewerApplet.java - JApplet object

  +o  ViewerPanel.java - Panel object


  [1m4.2.  Code history[0m


  +o  2004: Chang et al. Features added: node searching, color-coded
     weighted edges, URL-linking of nodes, enumeration of functional
     classes, improved compliance with Java 1.4.

  +o  2000: Mrowka <http://www.charite.de/bioinformatics/interaction/>.
     Basic protein-protein interaction graphing features added. Modeled
     as undirected, unweighted graphs. Features include: relaxation
     algorithm, freezing, functional pull-down menu, graph depth
     selection, and reloading graphs.

  +o  1997,1998: Sun        Corporation <http://java.sun.com/>. Core
     graphing applet code released.  Basic graph layout algorithms.

  The code is released under the Sun License:



       * Sun grants you ("Licensee") a non-exclusive, royalty free, license to use,
       * modify and redistribute this software in source and binary code form,
       * provided that i) this copyright notice and license appear on all copies of
       * the software; and ii) Licensee does not utilize the software in a manner
       * which is disparaging to Sun.
       *
       * This software is provided "AS IS," without a warranty of any kind. ALL
       * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY
       * IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
       * NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND ITS LICENSORS SHALL NOT BE
       * LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING
       * OR DISTRIBUTING THE SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS
       * LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT,
       * INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER
       * CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF
       * OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
       * POSSIBILITY OF SUCH DAMAGES.
       *
       * This software is not designed or intended for use in on-line control of
       * aircraft, air traffic, aircraft navigation or aircraft communications; or in
       * the design, construction, operation or maintenance of any nuclear
       * facility. Licensee represents and warrants that it will not use or
       * redistribute the Software for such purposes.



  [1m5.  Credits and references[0m

  [1m5.1.  Credits[0m

  This work has been and is supported in part by:


  +o  The University of Washington's Advanced Technology Initiative in
     Infectious Diseases (Ram Samudrala, 2001-present)

  +o  Searle Scholar Award (Ram Samudrala, 2002-2005)

  +o  National Science Foundation Grant DBI-0217241 (Ram Samudrala,
     2002-2007)

  +o  National Institutes of Health Grant GM068152 (Ram Samudrala,
     2003-2006)

  +o  Puget Sound Partners in Global Health (Ram Samudrala, 2004-2005)

  +o  NLM Medical Informatics Training Grant 1T15LM07441-01 (Aaron Chang,
     2002-2004)

  We also thank the Samudrala group for helpful discussions, and
  acknowledge Ralph Mrowka
  <http://www.charite.de/ch/physio/HK/ag/mrowka.html> and the Sun
  Corporation <http://www.sun.com> for making their code available.

  [1m5.2.  References[0m



  +o  Chang A, McDermott J, Samudrala R. An enhanced Java applet
     interface for visualizing interactomes. [4mBioinformatics[24m, 21:
     1741-1742, 2005.

  +o  McDermott J, Samudrala R. Enhanced functional information from
     protein networks. [4mTrends[24m [4min[24m [4mBiotechnology[24m 22: 60-62, 2004.

  +o  McDermott J, Samudrala R. BIOVERSE: Functional, structural, and
     contextual annotation of proteins and proteomes. [4mNucleic[24m [4mAcids[0m
     [4mResearch[24m 31: 3736-3737, 2003.

  +o  Mrowka R. A Java applet for visualizing protein-protein
     interaction.  [4mBioinformatics[24m 17: 669-671, 2001.



