BioJS InterMineTable Component: A BioJS component for displaying data from InterMine compatible webservice endpoints

Installation

As a visual BioJS component, the intended audience is web-developers aiming to provide extended functionality to web-based resources for life-scientists. It is expected to be deployed within modern browser environments with access to third-party resources. With this in mind, installation comprises of including the dependencies for the InterMine table component on the page (usually added in the head section of an HTML page), see Supplementary materials A. Once the dependency on the InterMine tables library is loaded, the InterMineTable BioJS component may be included (see code listing 1).

Listing 1. Loading the BioJS InterMine Table library

<script
    src="Biojs.InterMine.Table.js"></script>

This last resource contains the definition of the InterMine.Table BioJS component. As it is not available from a reliable third party source, it currently needs to be downloaded from the BioJS registry¹¹, and hosted locally.

Usage

This component is used by instantiating the InterMine table component in a user-included JavaScript file, passing in the appropriate configuration for the desired source of data as well as the query over those data.

Once instantiated, the results of the query against the specified integrated data-warehouse are loaded into a component where they can be browsed and manipulated. This means that the two critical concepts for using this component are 1) the location of the data-store, defined as the uniform resource locator (URL) pointing at the root of a set of web-services, and 2) the query to be run on the data in the store, defined in a configuration object. For example, to load a table of data from FlyMine the user would want the URL to point to FlyMine’s webservices:

Listing 2. Specifying the Data-Store

var url = "http://www.flymine.org/query";

The query can be broadly defined as a list of fields, identified by paths from a root, constrained by a (possibly empty) set of filters. There are some refinements to this (such as sort-order, optional element definition, and constraint composition) for which more detailed documentation¹² exists. The concept of a path is important to the idea of a graph of linked data, as it enables chains of relationships between entities to be followed, with minimal syntactic overhead. For example the chain of relationships the names of the protein domains of the proteins encoded by the genes belonging to a biochemical pathway can be referred to as Pathway.genes.proteins.proteinDomains.name.

A query is defined as a plain JavaScript object which can be simple, such as the following query, which requests the common name, scientific name and taxon ID for all organisms in the data-store:

Listing 3. A simple Query, see Figure 1

// Available organisms
var query = {
  name: "An optional name", 
  from: "Organism", 
  select: ["commonName","name","taxonId"], 
};

Figure 1. A table of data loaded from FlyMine displaying the output of Code Listing 3.

or arbitrarily complex, such as the following query which combines information from multiple data sources (OMIM¹³, PANTHER¹⁴, Treefam¹⁵, KEGG¹⁶, Reactome¹⁷, FlyBase¹⁸) and across different organisms to find the Drosophila melanogaster genes in the pathways of genes which are orthologous to human genes implicated in Alzheimer’s disease:

Listing 4. A Complex Query, see Figure 2

var disease = {
  from: "Disease",
  select: [
    "genes.homologues.homologue.pathways.genes.*"
  ], 
  where: {
    "name": "Alzheimer*",
    "genes.organism.name": "Homo sapiens",
    "genes.homologues.homologue.organism.name": 
        "Drosophila melanogaster"
  }
};

Figure 2. A table of data loaded from FlyMine displaying the output of Code Listing 4.

An element also needs to be present on the page where the table should be loaded. This can be any element (although a DIV element is conventional), and should be uniquely identifiable (through its ID for instance).

Listing 5. Defining the Target Element

var target = "#table-container";

These values are then passed to the component constructor, which builds a new table in the page, and loads the relevant data from the configured service:

Listing 6. Instantiation

var table = new Biojs.InterMine.Table({
  target: target,
  url: url,
  query: query
});

Once instantiated, a table will be loaded into the page displaying rows of data as specified by the query (see Figure 1, Figure 2).

Interaction

The table, as well as providing a number of common dynamic features such as resorting, pagination and column rearrangement, also permits much deeper interaction than other comparable table libraries. The table allows the underlying query to be changed: the constraints of the underlying query can be edited (Figure 3); columns (including ones referring to data types not in the original query) can be added; existing columns can be removed; changes made can be undone; the data can be exported in a number of formats or sent to another application, such as a local Galaxy^19–21 instance, or to a remote application such as GenomeSpace²² (Figure 4); the results can be saved as a resusable set (a list) within the originating service; individual items can also be previewed (Figure 5).

Figure 3. Editing the filters on a table.

Figure 4. Downloading the results of a query.

Figure 5. Previewing an item.

One particularly useful feature is the ability to view the contents of a single column, analysing it on aggregate and adding or editing filters. This facility is able to present summary charts for columns based on data type: binned histograms for numerical data (Figure 6), and column charts for categorical data (Figure 7, showing the user adding a filter by selecting items from the column).

Figure 6. Analysing and filtering a single column of numeric data within a table.

Figure 7. Analysing and filtering a single column of categorical data within a table.

Events

The standard mechanism for communication between components in JavaScript is event signalling. As per the BioJS specification, this component supports other objects registering event listeners so they may be notified when events of interest (such as user interactions) occur.

Once loaded, the table may emit a number of different events (as listed in the API documentation²³), and may be manipulated by calling methods on the instance, allowing the calling page to respond to user interactions. For example, if a developer wished to receive notifications when the user clicks on any of the cells in the table, they can register to listen for these events:

Listing 7. Adding an Event Listener

table.addListener("imo:click",function
    (type, id) {
 alert("User clicked on " + type +" " + id);
});

This integration means that the table need not be an isolated part of an application, but can be fully integrated with other components. For example, instead of just notifying the user by using alert, the information about this object could be displayed in another component. If the user clicked on a protein, this could be detected, and other suitable components could be instantiated to display protein-specific analysis (see code sample 8).

Listing 8. Integrating with Other Components - Example 1

table.addListener("imo:click",function
    (type, id) {
  if("Protein" === type) {
    table.service.findById(type, id)
                .then(loadProteinStructureDisplayer);
  }
  function
      loadProteinStructureDisplayer(protein) {
   // ... load other BioJS component here.
  }
});

As well as responding to user interaction with the table, the table component exposes an API to change the state of the table by changing the query it represents. This allows communication in the other direction. For example if a linked component, such as a protein structure displayer, emits an event indicating the user has selected a given set of protein domains, the table could be modified by adding a filter for these domains to the current query (see code sample 9):

Listing 9. Integrating with Other Components - Example 2

/* Assuming a "displayer" component that
    emits the "domains:selected" event */
displayer.addListener("domains:selected", 
    function (domains) {
  var currentQuery = table.getQuery();
  currentQuery.addConstraint({
    "Gene.proteins.proteinDomains.identifier":
        domains
  }); 
});

In this way, the interoperability of these components makes them of increasing utility to developers, as more of them are published and integrated into third party applications.