GView API

The GView API is accessible from other Java applications for interacting directly with GView. Using the API, Java applications have access to tools which allow them to:
  • change the input file used for rendering
  • supply a GSS file to change the appearance of the map
  • modify the zoom level and centre of the genome map
  • and much more.

The API was developed so that GView can be integrated into sequence annotation systems to provide genome visualization.

How to Render a GView Map

The Java object controlling the view of the data is the GViewMap. This object allows a user to interact or change the display. To create a map, three different types of information must be supplied:
  1. The style used to render the map
  2. The data that will be rendered
  3. The layout to use for rendering the map

Style

GView style information is stored and accessed through the MapStyle object. MapStyle provides access to two different types of styles, Global Styles and Data Styles.

Global Style

GlobalStyle defines all styling information that has global effects on the GView map. This includes background colors, initial size of the map, or how to display the ruler.
MapStyle mapStyle = new MapStyle();

// Extract associated GlobalStyle from newly created MapStyle object
GlobalStyle global = mapStyle.getGlobalStyle();

// Set initial height/width of the map
global.setDefaultWidth(1200);
global.setDefaultHeight(900);

global.setBackgroundPaint(Color.WHITE);

// Set tool tip style.  This is used to display extra information about various items on the map.
TooltipStyle tooltip = global.getTooltipStyle();
tooltip.setFont(new Font("SansSerif", Font.PLAIN, 12));
tooltip.setBackgroundPaint(new Color(134, 134, 255)); // set background paint to (r,g,b)=(134,134,255)
tooltip.setOutlinePaint(new Color(0.0f, 0.0f, 0.0f, 0.5f)); // set outline paint of tool tip item to (r,g,b) = (0,0,0) and alpha=0.5
tooltip.setTextPaint(Color.BLACK);  // set the paint of the text for the tool tip item

// Set style information dealing with the backbone.  This is the item displayed in the very centre of the slots.
BackboneStyle backbone = global.getBackboneStyle();
backbone.setPaint(Color.GRAY.darker());
backbone.setThickness(2.0);
backbone.setInitialBackboneLength(1100); // sets the "length" of the backbone along which the various items are to be displayed

// Set information dealing with the ruler style
RulerStyle ruler = global.getRulerStyle();
ruler.setMajorTickLength(15.0);  //
ruler.setMinorTickLength(5.0);
ruler.setTickDensity(0.5f);
ruler.setTickThickness(2.0);
ruler.setMinorTickPaint(Color.GREEN.darker().darker());
ruler.setMajorTickPaint(Color.GREEN.darker().darker());
ruler.setFont(new Font("SansSerif", Font.BOLD, 12));  // font/font paint set information dealing with the text label of the ruler
ruler.setTextPaint(Color.BLACK);

Data Style

DataStyle is used to define styling information that relates to the genome data. The primary method of styling genome data is by using slots.A slot is a single track along the backbone where features or sets of features can be displayed. Slots are divided into upper and lower slots, with Slot.FIRST_UPPER and Slot.FIRST_LOWER being the first slots in their respective directions. Slots are numbered sequentially starting with these constants, so that Slot.FIRST_UPPER + 1, and Slot.FIRST_LOWER - 1 refer to the two slots above and below the first upper and lower slots.

The DataStyle object provides the ability to create SlotStyle objects for different slots. The SlotStyleobject is used to define the thickness and colors for items in the slots.
// Assumes mapStyle created as above

// Extract data style from map style
DataStyle dataStyle = mapStyle.getDataStyle();

// Creates the first two slots
SlotStyle firstUpperSlot = dataStyle.createSlotStyle(Slot.FIRST_UPPER); // first slot above backbone
SlotStyle firstLowerSlot = dataStyle.createSlotStyle(Slot.FIRST_LOWER); // first slot below backbone

// Creates slots right next to the first slots
SlotStyle secondUpperSlot = dataStyle.createSlotStyle(Slot.FIRST_UPPER + 1);
SlotStyle secondLowerSlot = dataStyle.createSlotStyle(Slot.FIRST_LOWER - 1);

// Sets the default color of any features in these slots
firstUpperSlot.setPaint(Color.BLACK);
firstLowerSlot.setPaint(Color.BLACK);
secondUpperSlot.setPaint(Color.BLACK);
secondLowerSlot.setPaint(Color.BLACK);

 // Sets the thickness of the respective slots
firstUpperSlot.setThickness(15);
firstLowerSlot.setThickness(15);
secondUpperSlot.setThickness(15);
secondLowerSlot.setThickness(15);

Each slot on the map can contain sets of Features each of which has its own styling information. The styling information is stored in a FeatureHolderStyles object. A FeatureHolderStyle can be built from a SlotStyle object to define a set of features and how the features should be displayed within that slot. A FeatureHolderStyle contains a FeatureFilter, which provides the ability to define the set of features contained within the FeatureHolderStyle. Different colors and thickness' can then be defined for each FeatureHolderStyle. All features filtered out by a FeatureFilter will be styled according to the settings of the FeatureHolderStyle.

FeatureHolderStylesare hierarchical in that each holder style can contain subsets of features, each with its own style.Styles inherit properties from their parents, but can also be modified individually and override parent properties.
// Assumes SlotStyles were created as above

// Creates a feature holder style in the first upper slot containing all the positive stranded features
FeatureHolderStyle positiveFeatures = firstUpperSlot.createFeatureHolderStyle(new FeatureFilter.StrandFilter(StrandedFeature.POSITIVE));
positiveFeatures.setThickness(0.7); // sets the thickness of these features as a proportion of the thickness of the slot
positiveFeatures.setTransparency(0.9f); // sets transparency of all features drawn within this slot
positiveFeatures.setToolTipExtractor(new LocationExtractor());    // sets how to extract text to be displayed for tool tips on these features
positiveFeatures.setPaint(Color.BLUE); // sets default color of the positive features

// Creates a sub feature holder style below the positiveFeatures feature holder.  This can be used to extract and override style information
//   for features that would be contained within the positiveFeatures feature holder.
// In this example, we will override the blue color for positive features that overlap bases [50,95] and color them a darker blue.
FeatureHolderStyle subPositiveFeatures = positiveFeatures.createFeatureHolderStyle(new FeatureFilter.OverlapsLocation(new RangeLocation(50,95)));
subPositiveFeatures.setPaint(Color.BLUE.darker().darker().darker().darker()); // overrides the color for these features, making it darker

// Creates a holder containing all negative features in the first lower slot
FeatureHolderStyle negativeFeatures = firstLowerSlot.createFeatureHolderStyle(new FeatureFilter.StrandFilter(StrandedFeature.NEGATIVE));
negativeFeatures.setThickness(0.7);
negativeFeatures.setToolTipExtractor(new LocationExtractor());
negativeFeatures.setPaint(Color.RED);

// Creates a holder containing all features in the second upper slot
FeatureHolderStyle allFeatures = secondUpperSlot.createFeatureHolderStyle(FeatureFilter.all);
allFeatures.setThickness(0.7);
allFeatures.setToolTipExtractor(new LocationExtractor());
allFeatures.setPaint(Color.GREEN);

// Creates a holder containing only features overlapping bases [0,50] in the second lower slot
FeatureHolderStyle locationFeatures = secondLowerSlot.createFeatureHolderStyle(new FeatureFilter.OverlapsLocation(new RangeLocation(0,50)));
locationFeatures.setThickness(0.7);
locationFeatures.setToolTipExtractor(new LocationExtractor());
locationFeatures.setPaint(Color.BLACK);

Data

GView uses the BioJava Sequence object to store and retrieve information about genome data. In GView, a GenomeData object contains the BioJava Sequence, and can be created using the GenomeDataFactory.

Creating GenomeData in Code

If a BioJava Sequence object is already created, then you can create the corresponding GenomeData object using GenomeDataFactory.createGenomeData(Sequence sequence) as follows:
Sequence sequence;
GenomeData data = GenomeDataFactory.createGenomeData(sequence);

If the BioJava Sequence object is not already built, then you must build it yourself. More information on how to use and create Sequences can be found at the BioJava Sequences and Features Tutorial.

In addition to sequences with associated symbols, GView provides an implementation of SymbolList called BlankSymbolList which can be used to create sequences with a length and features, but no symbol information.

An example of how to use BlankSymbolList to create a GenomeDataobject with sequence length 95, and some Features on the sequence is as follows:
GenomeData data = null;

// Create a blank symbol list with a length of 110
SymbolList blankList = new BlankSymbolList(110);

try
{
   // Create a factory to build the blank sequence
   SimpleSequenceFactory seqFactory = new SimpleSequenceFactory();
   
   // Creates a sequence from the blank symbol list
   Sequence blankSequence = seqFactory.createSequence(blankList, null, null, null);
   
   // Creates a basic feature located at the beginning of the sequence
   Feature.Template basic = new Feature.Template();
   basic.location = new RangeLocation(1,9);
   blankSequence.createFeature(basic);
   
   // Creates a basic feature located at the end of the sequence
   basic.location = new RangeLocation(91,94);
   blankSequence.createFeature(basic);
   
   // Creates a positive stranded feature
   StrandedFeature.Template stranded = new StrandedFeature.Template();
   stranded.strand = StrandedFeature.POSITIVE;
   stranded.location = new RangeLocation(11,19);
   blankSequence.createFeature(stranded);
   
   // Creates another positive stranded feature
   stranded.location = new RangeLocation(31,39);
   blankSequence.createFeature(stranded);
   
   // and another positive stranded feature
   stranded.location = new RangeLocation(51,59);
   blankSequence.createFeature(stranded);
   
   // and another positive stranded feature
   stranded.location = new RangeLocation(71,79);
   blankSequence.createFeature(stranded);
   
   // Creates a negative stranded feature
   stranded.strand = StrandedFeature.NEGATIVE;
   stranded.location = new RangeLocation(21,29);
   blankSequence.createFeature(stranded);
   
   // negative stranded feature
   stranded.location = new RangeLocation(41,49);
   blankSequence.createFeature(stranded);
   
   // negative stranded feature
   stranded.location = new RangeLocation(61,69);
   blankSequence.createFeature(stranded);
   
   // negative stranded feature
   stranded.location = new RangeLocation(81,89);
   blankSequence.createFeature(stranded);
   
   // Creates a GenomeData object from the Sequence
   data = GenomeDataFactory.createGenomeData(blankSequence);
}
catch (IllegalSymbolException ex)
{
   ex.printStackTrace();
}
catch (BioException be)
{
   be.printStackTrace();
}

Reading GenomeData from a File

A GenomeData object can be read directly from a file through a GViewFileReader. GViewFileReader will read in the file, and returns a GViewFileData object with the extracted information (a GenomeData and MapStyle).If one field in GViewFileData does not apply for some file format (MapStyle is not included in Genbank files, but is included in CGview XML files) then it will be null.

GViewFileReader will attempt to automatically detect the format of the file being read. Alternatively, GViewFileReader provides a read method which accepts a particular FileFormatReader. This can be useful if you wish to force interpreting the file under a specific format.

An example of extracting a GenomeDatainstance from a genbank file is as follows:
try
{
   GViewFileData fileData = GViewFileReader.read("example_data/NC_007622.gbk");
   
   return fileData.getGenomeData();
}
catch (IOException e)
{
   e.printStackTrace();
}
catch (GViewDataParseException e)
{
   e.printStackTrace();
}

An example of extracting a GenomeData and MapStyle instance from a CGViewxml file is as follows:
try
{
   GViewFileData fileData = GViewFileReader.read("example_data/roseobacter_denitrificans.xml");
   
   GenomeData genomeData = fileData.getGenomeData();
   MapStyle mapStyle = fileData.getMapStyle();

   // perform operations with genomeData and mapStyle
}
catch (IOException e)
{
   e.printStackTrace();
}

Layout

The layout of the map can be one of circular or linear.It is defined by the LayoutFactory object, of which there are two pre-built implementations: LayoutFactoryLinear and LayoutFactoryCircular. Creating a new layout is as simple as instantiating which factory to use.
LayoutFactory layoutFactory;

layoutFactory = new LayoutFactoryLinear();
// or
layoutFactory = new LayoutFactoryCircular();

The layout can be set on the map itself by using GViewMap.setLayout(LayoutFactory layoutFactory), or it can be set when initially building a map.

Creating the Map

The GViewMap can be created using a GViewMapFactory. It requires a GenomeData, MapStyle, and LayoutFactoryto be created and will build up the map from the information stored in these objects.
// creates the 3 components necessary to build the map
GenomeData data = buildData();
MapStyle style = buildStyle();
LayoutFactory layoutFactory = new LayoutFactoryLinear();

// builds the map from the data/style/layout information
GViewMap gViewMap = GViewMapFactory.createMap(data, style, layoutFactory);

Exporting to an Image

GView supports exporting the rendered map in different image formats.This is done using an ImageWriter. A specific instance of ImageWriter is created using the ImageWriterFactory, which allows you to build writers specific to different file formats.

For example, exporting a map to PNG or SVG would involve:
GViewMap gviewMap = buildGViewMap(); // builds the gview map

// Builds an ImageWriter used to write the map to a file using different formats
ImageWriter writerPNG = ImageWriterFactory.createImageWriter("png");
ImageWriter writerSVG = ImageWriterFactory.createImageWriter("svg");

// Writes the map to a file
try
{
   writerPNG.writeToImage(gViewMap, "example1.png");
   writerSVG.writeToImage(gViewMap, "example1.svg");
}
catch (IOException e)
{
   e.printStackTrace();
}

Putting it all Together

Putting all this code together will result in the following rendered images.

Circular Linear
example1-circular-thumb.png example1-linear-thumb.png
Source: apitutorial1.java
Note: To compile code using the GView API, gview.jar must be placed on the classpath.For example, the below commands can be used to compile/run apitutorial1.java. Assumes that gview.jar is located in the same directory as apitutorial1.java.
  javac -cp gview.jar:. apitutorial1.java
  java -cp gview.jar:. apitutorial1

More Examples

More examples of the GView API can be found on the GView API Examples page or within the gview/examples directory of GView.
 
Contact: Aaron Petkau, Eric Marinier, Matthew Stuart-Edwards at gview@phac-aspc.gc.ca