Documentation


Usage

CanvasXpress is a standalone JavaScript library that works in all modern browsers on mobile, tablets and desktop devices. The following example shows the basic usage which consists of four steps; include the JavaScript and the CSS framework in the <head> section of the web page, include the data also in the <head> section of the web page, include a <canvas> element in the <body> section of the web page and last include a mechanism to instanciate the canvasXpress object which in this example is a call to a function triggered after loading the web page.

<html>
  <head>
    <link rel="stylesheet" href="path-to-canvasXpress.css" type="text/css"/>
    <script type="text/javascript" src="path-to-canvasXpress.min.js"></script>
    <script>
      var initPage = function () {        
        var data = {"y": {"vars": ["Gene1"],
                          "smps": ["Smp1", "Smp2", "Smp3"],
                          "data": [[10, 35,88]]
                         }};
        var conf = {"graphType": "Bar"};                 
        var cX = new CanvasXpress("canvasId", data, conf);
      }
    </script>
  </head>
  <body onload="initPage();">
    <canvas  id="canvasId" width="540" height="540"></canvas>
  </body>
</html>

CanvasXpress Framework

The canvasXpress framework conists of two files: (1) a CSS file, canvasXpress.css and (2) a JavaScript file, canvasXpress.min.js. These two files must be included in <head> section of the web page pointing directly to the www.canvasXpress.org web site:

<link rel="stylesheet" href="http://www.canvasxpress.org/css/canvasXpress.css" type="text/css"/>
<script type="text/javascript" src="http://www.canvasxpress.org/js/canvasXpress.min.js"></script>

or downloaded and included in the <head> section of the web page pointing to the desired location. Make sure to register the copy if you plan to download the framework.

<link rel="stylesheet" href="path-to-canvasXpress.css" type="text/css"/>
<script type="text/javascript" src="path-to-canvasXpress.min.js"></script>

Data

There are two ways to initialize the canvasXpress data object. The first one is to pass three or more arguments (which will be disscused below).

var cX = new CanvasXpress(targetId, data, config, events);

or one single argument:

var cX = new CanvasXpress(
  {
   renderTo: targetId,
   data: data,
   config: config,
   events: events
  }
);

CanvasXpress Instances

The CanvasXpress instances in the web page can be retrieved and accessed at any time using the target id as follows:

var cX = CanvasXpress.$(targetId);

Similarily, any CanvasXpress instance in the web page can be destroyed programatically. This is very important if there is a need to remove the CanvasXpress instance since there are many events that are created at the time of the instanciation and this is the only way to cleanly remove all of them. This can be done using the target id as follows:

CanvasXpress.destroy(targetId);

or using the instance itself:

CanvasXpress.$(targetId).destroy();

Arguments

targetId is the id of the <canvas> element element included in the <body> section of the web page and will be the place where the graph will be rendered.

data is a json object with the data to plot. The are many formats which depend on the visualization. One for the genome browser, one for the networks, one for the Venn diagramas, one for the correlation plots, one for the stock market data and one for all the other graphs.

config is a json object to customize the graph and includes a very large number of properties.

events is a json object with user-defined mouse events.

Data Format

Data format for most of the graphs: Area, AreaLine, Bar, BarLine, Boxplot, Candlestick, Circular, Contour, DotLine, Dotplot, Heatmap, Histogram, Kaplan-Meier, Line, Pie, Scatter2D, Scatter3D, ScatterBubble2D, Stacked, StackedLine, StackedPercent, StackedPercentLine, TagCloud, Treemap.

The data structure can be graphically represented like this:

A data set is always a series of values organized in rows and columns. In canvasXpress, the rows are refered to variables while the columns are refered to samples. Very often we have additional discrete or continuous data that help us annotating either the samples or the variables which in statistical terms are refered to as factors. Conceptually, the data in canvasXpress can be divided into three compartments. The (y) compartment which contains the actual numerical values, the (x) compartment which contains characteristics of the samples and the (z) compartment which contains annotations for the variables. It is not required however that all data sets must have all these attributes except for the (y) compartment.

Example of data for a single series:

{
  "y" : {
     "vars" : ["Variable1"],
     "smps" : ["Sample1", "Sample2", "Sample3", "Sample4"],
     "data" : [[10, 20, 30, 40]]
  },
  "x" : {
     "Tissue" : ["Kidney", "Liver", "Lung", "Heart"],
     "Donor" : ["D1", "D1", "D2", "D2"]
  },
  "z" : {
     "Symbol" : ["AAA"],
     "Pathway" : ["P1"]
  }
}

Example of data for two series:

{
  "y" : {
     "vars" : ["Variable1", "Variable2", ],
     "smps" : ["Sample1", "Sample2", "Sample3", "Sample4"],
     "data" : [[10, 20, 30, 40], [20, 30, 40, 50]]
  },
  "x" : {
     "Tissue" : ["Kidney", "Liver", "Lung", "Heart"],
     "Donor" : ["D1", "D1", "D2", "D2"]
  },
  "z" : {
     "Symbol" : ["AAA", "BBB"],
     "Pathway" : ["P1", "P2"]
  }
}

There are additional properties that can be added to the json object depending on the graph type. For example, you can add a (t) property to specify a dendrogram in newick format for both samples and variables. In cases of a line combination graph you must add an (a) property to specify the axis for each series.

{
  "y" : {
     "vars" : ["Variable1", "Variable2", ],
     "smps" : ["Sample1", "Sample2", "Sample3", "Sample4"],
     "data" : [[10, 20, 30, 40], [20, 30, 40, 50]]
  },
  "x" : {
     "Tissue" : ["Kidney", "Liver", "Lung", "Heart"],
     "Donor" : ["D1", "D1", "D2", "D2"]
  },
  "z" : {
     "Symbol" : ["AAA", "BBB"],
     "Pathway" : ["P1", "P2"]
  },
  "t" : {
     "vars" : "("Variable1","Variable2")",
     "smps" : "((("Sample1","Sample2"),"Sample3"),"Sample4")"
  },
  "a" : {
     "xAxis" : ["Variable1"],
     "xAxis2" : ["Variable2"]
  }
}

There are many more properties that can be included in this data format that can be found in each of the graph types examples.

The data format for the correlation plot is as follows:

{
  "y" : {
    "smps" : ["Sample1", "Sample2", "Sample3", "Sample4"],
    "cor" : [
      [1.0, 0.9, 0.8, 0.7],
      [0.9, 1.0, 0.8, 0.8],
      [0.8, 0.8, 1.0, 0.7],
      [0.7, 0.8, 0.7, 1.0]
    ]
  }
}

As you can see this is just an extension of the previous format in which the correlation between samples (in this case) is represented in a two dimensional array under the property (cor). In fact if you try to plot a correlation plot and you don"t have the (cor) property, canvasXpress will do it for you as long as you provide the raw data.

The data format for the Venn with three groups is as follows:

{
  "venn" : {
    "data" : {
      "A" : 340,
      "B" : 562,
      "C" : 620,
      "AB" : 639,
      "AC" : 456,
      "BC" : 915,
      "ABC" : 552
    },
    "legend" : {
      "A" : "List1",
      "B" : "List2",
      "C" : "List3"
    }
  }
}

This format contains the property (venn) where the data is organized. The (data) property contains the actual data and the (legend) property the different lists in the Venn diagram. The basic idea here is that in this case there are three lists, A, B and C so you just have to assign a number to each one and also to any combination of them but they must be in alphabetical order; that is, they have to be "AB" rather than "BA". If you have four lists then you only have to assign numbers to A, B, C and D; if you have two list then you only have to assign numbers to A nad B.

The data format for the Networks is as follows:

{
  "nodes" : [
    {
      "id" : "Node1",
      "color" : "rgb(255,0,0)",
      "shape" : "circle",
      "size" : 1
    }, {
      "id" : "Node2",
      "color" : "rgb(0,255,0)",
      "shape" : "square",
      "size" : 1.5
    }, {
      "id" : "Node3",
      "color" : "rgb(0,0,255)",
      "shape" : "triangle",
      "size" : 2
    }
  ],
  "edges" : [
    {
      "id1" : "Node1",
      "id2" : "Node2",
      "color" : "rgb(125,125,0)",
      "type" : "line"
    }, {
      "id1" : "Node1",
      "id2" : "Node3",
      "color" : "rgb(0,125,125)",
      "type" : "squareHeadLine"
    }, {
      "id1" : "Node2",
      "id2" : "Node3",
      "color" : "rgb(125,0,125)",
      "type" : "arrowHeadLine"
    }
  ]
}

The (nodes) property contains as it name indicates the nodes in the network. Each node must have a unique (id) property. Also, (color), (shape), (rotate), (pattern), (outline), (outlineWidth) and either (size) or (width) and (height) can be specified for each node. The (color) property is specified in an rgb format compatible with the <canvas> element. The (shape) must be one of the shapes in this library (see the options section). The rotation for the shape must be expressed in degrees. The (pattern) is either "closed" or "open". The (size) is a multiplier and not the actual size of the node, for example, to make a node twice as big, the size should be set to 2. If you need more control over the shape then you need to specify (width) and (height). The (edges) property as you can imagine, contains the info for the edges in the network. Each edge must contain an (id1) and an (id2) properties which must match two nodes in the network. Similarly, you can specify the (color), the (width), which is the actual width of the line, the (cap) which could be "butt", "round" or "square" and the line (type) which should be one of the types in this library (see the options section). The property (legend) is an object that contains the information for the nodes and edges and additional text.

Each node may have one parent under the property "parentNode" and it has to match a valid node id. This feature is useful if you want to group nodes together. You can assign a name and / or a label to each node. The order in which the text will be displayed is label or name or id.

The data format for the Candlestick is as follows:

{
  "market": [
    {
      "symbol": "BMY",
      "data": [
        [20100824, 26.26, 26.37, 25.95, 26.02, 11625900, 26.02],
        [20100823, 26.48, 26.76, 26.38, 26.48, 12146600, 26.48],
        [20100820, 26.31, 26.54, 26.08, 26.44, 18140100, 26.44],
        [20100819, 26.20, 26.29, 25.81, 26.06, 8218000, 26.06],
        [20100818, 26.53, 26.57, 26.23, 26.28, 12235800, 26.28],
        [20100817, 26.40, 26.79, 26.26, 26.59, 12325700, 26.59],
        [20100816, 26.24, 26.34, 26.04, 26.28, 10377700, 26.28],
        [20100813, 26.24, 26.46, 26.10, 26.32, 5760100, 26.32],
        [20100812, 26.01, 26.39, 26.00, 26.33, 7350500, 26.33],
        [20100811, 26.32, 26.50, 26.15, 26.25, 8808100, 26.25],
        [20100810, 26.32, 26.78, 26.30, 26.66, 7009500, 26.66],
        [20100809, 26.37, 26.54, 26.30, 26.51, 6825300, 26.51],
        [20100806, 26.29, 26.45, 26.05, 26.37, 8774900, 26.37],
        [20100805, 25.83, 26.38, 25.80, 26.38, 12264600, 26.38],
        [20100804, 25.70, 26.13, 25.61, 26.03, 10233700, 26.03],
        [20100803, 25.65, 25.85, 25.58, 25.68, 6842900, 25.68],
        [20100802, 25.33, 25.61, 25.29, 25.53, 9770900, 25.53],
        [20100730, 24.98, 25.13, 24.78, 24.92, 11435700, 24.92],
        [20100729, 25.37, 25.50, 24.85, 25.08, 9463800, 25.08],
        [20100728, 25.25, 25.36, 25.02, 25.12, 8072400, 25.12],
        [20100727, 25.09, 25.35, 24.84, 25.32, 14152600, 25.32],
        [20100726, 24.57, 25.03, 24.57, 24.97, 8817400, 24.97],
        [20100723, 24.94, 24.95, 24.26, 24.65, 13043700, 24.65],
        [20100722, 24.96, 25.22, 24.75, 24.93, 10385300, 24.93],
        [20100721, 24.92, 25.11, 24.59, 24.75, 9830000, 24.75],
        [20100720, 24.65, 25.09, 24.46, 25.02, 10655500, 25.02],
        [20100719, 25.27, 25.27, 24.78, 24.84, 11804800, 24.84],
        [20100716, 25.44, 25.47, 25.10, 25.17, 13136300, 25.17]
      ]
    }
  ]
}

It is the same format you download data from Yahoo except that the hyphens in the date are stripped. Also, you can add many symbols too.

And finally the last data format used for the Genome is as follows:

{
  "tracks" : [
    {
      "name" : "Affy Probes",
      "type": "box",
      "connect": true,
      "fill" : "rgb(255,255,51)",
      "line" : "rgb(0,0,0)",
      "data" : [
        {
          "id" : "123456_at",
          "dir" : "right",
          "data" : [[100,120], [123,132], [141,160]]
        },{
          "id" : "234567_at",
          "dir" : "left",
          "data": [[181,200], [211,230], [251,270]]
        },{
          "id" : "345678_at",
          "dir" : "right", 
          "data" : [[281,300], [311,330], [351,370]]
        }
      ]
    }, {
      "hide" : true,
      "type" : "bar",
      "height" : 20,
      "fill" : ["rgb(255,0,0)", "rgb(0,0,255)", "rgb(255,255,0)"],
      "line" : ["rgb(255,0,0)", "rgb(0,0,255)", "rgb(255,255,0)"],
      "data" : [
        {
          "id": "123456_at", 
          "data": [100,25,35,46]
        }, {
          "id" : "234567_at", 
          "data" : [181,80,45,10]
        }, {
          "id" : "345678_at",
          "data" : [281,65,46,29]
        }
      ]
    }, {
      "name": "Tissue Distribution (Heart, Liver, Kidney)",
      "hide": false,
      "type": "heatmap",
      "autowidth": true,
      "height": 20,
      "line": "rgb(0,0,0)",
      "smps": ["Heart", "Kidney", "Liver"],
      "data": [
        {
          "id": "123456_at", 
          "data": [100,25,35,46]
        }, {
          "id" : "234567_at", 
          "data" : [181,80,45,10]
        }, {
          "id" : "345678_at",
          "data" : [281,65,46,29]
        }
      ]
    }, {
      "name" : "SNP",
      "type" : "triangle",
      "fill" : "rgb(100,0,0)",
      "line" : "rgb(0,0,0)",
      "data" : [
        {
          "id" : "SNP123", 
          "data" : 123
        }, {
          "id" : "SNP234", 
          "data" : 145
        }, {
          "id" : "SNP789", 
          "data" : 220
        }
      ]
    }, {
      "name" : "SNP",
      "type" : "line",
      "line" : "rgb(0,255,0)",
      "data" : [
        {
          "id" : "SNP123", 
          "data" : 123
        }, {
          "id" : "SNP234", 
          "data" : 145
        }, {
          "id" : "SNP789", 
          "data" : 220
        }
      ]
    }, {
      "type" : "sequence",
      "subtype" : "DNA",
      "hide" : true,
      "line" : "rgb(255,255,255)",
      "data" : [
        {
          "id" : "SNP123", 
          "data" : [119,"AGCT[TA]CGAG"]
        }, {
          "id" : "SNP234", 
          "data" : [141,"ATCG[TG]AATA"]
        },{
          "id": "SNP789", 
          "data": [216, "GCCC[CT]AGGG"]
        }
      ]
    }
  ]
}

If you are not in the biology field please skip this data format since I will assume a general understanding of some terms. If you are stubborn enough to continue reading or you do have the biology background then look at the genome example so you can figure out how to format the data. The property (tracks) is an array with the tracks you want to represent in a region of the genome. They can be of six different (type)s, box, bar, heatmap, triangle, line and sequence. The sequence type can be of (subtype) "DNA" or "Protein". You may specify the color of the shapes with the property (fill) for the inside of the shape and (line) for the edge of the shape. Only in the track type "bar", the (fill) and the (line) properties are represented as an array of colors so you can assign each bar different colors. The (tracks) may have a (name) which will be used as the title for the track but you can use the property (hide) to prevent displaying it. This is useful in some cases to save landscape as well as to make closer elements in adjacent tracks. You may also specify the height of the track with the property (height) but if you do not, it will take the default value (see the options section). Finally you can add as many propertys as you please in each track if you need to access them for a click or mouseover event (see the event section).

First, the "box" type can have many features specified in its (data) property as an array and each one of them may have many segments specified in its corresponding (data) property as a nested array. The segments can be displayed connected or not with the property (connect) which is boolean and is specified at the track level. That is, if it is true all the segments in each of the features in the track will be connected using a slanted line with their apexes in the middle between the adjacent segments. Also, each feature must have a unique (id) in the track, that is, it is not necessary to have a unique id among all the tracks, and it may have an orientation represented as an arrow which can be specified with the property (dir) which could be right or left. As I mentioned, the segments in each feature are an array with the first element representing the coordinate for the starting point and the second element with the coordinates for the ending point in the genome. Similar you can add many more propertys as you please if you need to make use of them for mouse events (see the event section).

The "bar" and the "heatmap" types, similarily, may have many features specified in its (data) property represented as an array. Each feature identified with a unique (id) may have many values identified in its corresponding (data) property also represented as an array. The first element of the array is the coordinates for the feature in the genome, the rest of the elements will be y values for the bar graphs or for the heatmap. In the case of the type "bar", you may specify a (width) for the "bar" at the track level or you may specify (autowidth) and in that case the width of the bar will be a unit of the base pair in the genome. That is, if you have three bars the width of each bar is going to be a third of a base pair. The only difference for the "heatmap" type is that the bars will be stacked and the colors will be automatically assigned according to the y values.

The "triangle" and the line types are also very similar except that each feature will have a property data to identify the coordinates for it in the genome.

Finally, the "sequence" type may also have many features. The only difference in the structure of the data is that in each feature"s data structure, the first element represent the coordinates in the genome and the second element is the actual sequence. If there are multiple alleles at a given position then the sequence is represented in square brackets, for example, [AG].

Configuration

Pretty much everything in this library is customazible. The configuration parameters are divided in major sections. Each parameter in a section contains a link to an example (in the name of the parameter) followed by the type of the value (in italic letters). There is also a description, a default, the options if approprieate and links to related parameters and graphs. Some of the parameters are private to CanvasXpress and are denoted with the work private in red. These are the major categories for the parameters:

3D Attributes, Acknowledgment, Animation, Area Graphs, Aspect Ratio, Axis, Axis Resizer, Background, Bins, Boxplot Graphs, Candlestick Plots, Circular Graphs, Citations or References, Clustering, Colors, Combination Plots, Contours, Correlation Graphs, DOE, Data, Data Filters, Data Point Attributes, Data Table, Data Table/Filter, Debug, Decorations, Dendrograms, Events, Foreground, General, General Attributes, Genome Browser, Gradients, Heatmap Graphs, Histograms, Images, Legends, Line Graphs, Lines, Loess, Margins, Network Graphs, Overlays, Patterns, Pie Charts, Plot area, R, R-Axis, Random, Remote Procedures, Samples, Scatter Plot Matrix, Scatter Plots, Shadows, Snapshots, Space and Width, Tag Cloud, Text, Titles and Subtitles, Treemap Graphs, Variables, Venn Diagrams, Videos, X-Axis, X-Axis2, Y-Axis, Z-Axis, Zooming and Panning.

Events

The parameter events is a json object with the user defined events. By default I assign the four events that canvasXpress supports which are mousemove, mouseout, click and dblclick. The events can also handle scope as shown below. In json format the events is like this:

{
  "mousemove" : function(o, e, t) {
    // Do something ...
  },
  "mouseout" : function(o, e, t) {
    // Do something more...
  },
  "click" : function(o, e, t) {
    // Do something else ...
  },
  "dblclick" : function(o, e, t) {
    // Do even more stuff
  }
}

or

{
  "scope" : myScope,
  "handler" : {
    "mousemove" : function(o, e, t) {
      // Do something ...
    },
    "mouseout" : function(o, e, t) {
      // Do something ...
    },
    "click": function(o, e, t) {
      // Do something else ...
    }
  }
}

The parameter (o) passed to the user defined callback has the same format as that one you passed in the data parameter. the (e) is the event that triggered the action and (t) is the full CanvasXpress object. Just go ahead and mouseover and/or click in any element in the graphs and see what I mean. It is up to you to include additional code to handle the events of course.

The default mouseover event in canvasXpress is to show the data value for most of the graphs or the feature/node/edge name for the Genome and Network graphs.

<canvas> element

The <canvas> element in the <body> section of the web page can include a responsive parameter so the graph is resized according to its parentNode container. If you want to mantain the aspect ratio you may also specify the aspectRatio parameter in the <canvas> element. This is very usefull if canvasXpress is used with other libraries like Bootstrap in any mobile or desktop devices. An example where the graph is responsive is as follows:

<div class="row">
  <div class="col-xs-12 col-sm-12 col-md-12 col-lg-12">
    <canvas id='bar1' width='290' height='540' aspectRatio='1:1' responsive='true'></canvas>
  </div>
</div>

Instanciation

The prefer method to initialize the graphs in the a web page is by using the onload method in the <body> of the web page and call a function to initialize the canvasXpress objects.

<body onload="initPage();">