Dygraphs Coordinate Systems, 1/3

This is the first of three posts about the coordinate systems used throughout Dygraphs.

• Part 1: Introduction and the Dygraph Data Coordinate System
• Part 2: DOM Coordinate System
• Part 3: Percentage Coordinate System

Introduction

This series of articles covers the three primary coordinate systems used in Dygraphs. They are: data coordinates, DOM coordinates, and percentage coordinates.

Each has its own distinct rules about origins and directions.

The entire series is based on this graph:

which is generated by this snippet of code:

new Dygraph(document.getElementById("graph"),

    [

      [1, [10,  10, 100]],

      [2, [15,  20, 110]],

      [3, [10,  30, 100]],

      [4, [15,  40, 110]],

      [5, [10, 120, 100]],

      [6, [15,  50, 110]],

      [7, [10,  70, 100]],

      [8, [15,  90, 110]],

      [9, [10,  50, 100]]

     ], {

       width: 500,

       height: 350,

       customBars: true,

       errorBars: true

     });

Dygraph Data coordinate system

The most obvious coordinate system to dygraphs is its inherent data coordinate system. The best way to demonstrate that coordinate system is through an example:

This highlighted point can be represented by the data coordinate system (4, 40). We’re even aided by the display on top showing the currently selected point.

Not to put too fine a point on it, but the x-value is 4, and the y-value is 40.

Graph data is always specified in the data coordinate system, and dygraphs does the job of translating those into points on the canvas. This should be no surprise to you, reading the code above shows the middle value for x=4 is 40.

This doesn’t always mean that the origin is in the lower-left corner of the graph area, since a graph can be resized and moved, but values almost always increase up and to the right.#

Before moving on to the next coordinate system, let’s play with the graph and its API. You can skip this section if you’re already comfortable with pulling values out of the graph.

Sidebar: Extremes and Visual Ranges

Extremes

Dygraphs provides a function that describes the extremes, or minimum and maximum data values, of the x-axis with xAxisExtremes:

g.xAxisExtremes()

[1, 9]

There is currently no yAxisExtremes function but Dygraphs an open source project; contributions are always welcome.

Visible Ranges

xAxisRange shows the visible data range along the x axis:

g.xAxisRange()

[1, 9]

Similarly yAxisRange shows the visible data range along the specified y axis:

g.yAxisRange()

[0, 131]

You’re wondering why the y axis range ends at 131 and not 120. This is because Dygraphs automatically adds a buffer to the top of most graphs’ y ranges for improved readability.
If you want the range to be precise, you can use the valueRange option with g.updateOptions({valueRange: [0, 120]}):

(Note there is currently a rendering bug where setting the value to 120 does something funny. This graph was rendered with a value range of 0-120.1.)

Remember these are visual ranges and not extremes of the data. So panning a graph along the x axis would result in a change in the x-axis range, but not x-axis extremes.