Skip to content

Getting started

Jump to bottom Edit New page
Lisa Zhang edited this page Apr 2, 2013 · 102 revisions

#Polychart.js Tutorial

Polychart.js is a flexible library for plotting interactive charts. This tutorial will go through the basics of how to create a chart, and how to tweak it to your liking. We'll do this by examples: each example contains a plot, the code, and an explanation of what the code does.

##A Simple Bar Chart

Let's start with creating a simple bar chart.

var searchterms = polyjs.data({
    term: ["Flower", "Chocolate", "Candy", "Valentine"],
    count: [16600000, 9140000, 7480000, 5000000]
});
polyjs.chart({
    layer: {
        data: searchterms,
        type: "bar",
        x: "term",
        y: "count"
    },
    title: "Monthly Google Search",
    dom: "chart",
    width: 300,
    height: 250
});

The first function call is to the polyjs.chart() function, which creates a wrapper on a dataset. This function takes a dataset in JSON or other formats, and turns it into a data object that Polychart.js can recognize.

The second function call actually creates the chart. The polyjs.chart() function takes a specification and uses it to determine how to render the appropriate chart.

A layer contains information about what is to be plotted. We pass in the data set object created earlier, and also tells Polychart.js that we would like to plot a bar chart, with the variable term mapped to the x-axis and the variable count mapped to the y-axis.

If we had changed the chart type to a line or a point, we would get one of the below charts:

If you want to create a simple chart, then that is all there is!

##Aesthetic Mappings

One different between Polychart and most charting libraries is how easy it is to map data directly to some feature of items in a chart, like color, size, or opacity. We bind data to these features called aesthetics much like we do to the x and y-axes:

var countries = polyjs.data([
    { country: "Canada", population: 33476688, area: 9984670, GDP: 1770000000 },
    { country: "United States", population: 315591000, area: 9826675, GDP: 15609700000},
    { country: "Australia", population: 21507717 , area: 7692024, GDP: 915098000000},
    { country: "China", population: 1353821000, area: 9706961, GDP: 8250000000000}
]);
polyjs.chart({
    layer: {
        data: countries,
        type: "point",
        x: "population",
        y: "area",
        color: "country",
        size: "GDP"
    },
    guide: {
        x: { min: -50000000, max: 1500000000 },
        y: { min: 7000000, max: 10500000 }
    },
    title: "Selected Countries",
    dom: "chart",
    width: 300,
    height: 250
});

##Multiple Layers

##Guides

##Example 2: Intermediate Chart Options This example will focus on multiple chart types, pie charts, random data, and the redraw function. We will be referring to the Wheel graph for this example. (LINK TO CHART)

var jsondata = [];
var i;
for (i = 0; i < 2; i += 1) {
    jsondata.push({
        index: i,
        value: Math.random()
    });
}
var data = polyjs.data({data: jsondata});
var spec = {
    layers: [
        {
            data: data,
            type: 'line',
            x: 'index',
            y: 'value'
        }, 
        {
            data: data,
            type: 'point',
            x: 'index',
            y: 'value',
            id: 'index'
        }
    ],
    guides: {
        y: {
            type: 'num',
            min: 0,
            max: 10,
            ticks: [2, 4, 6, 8],
            labels: {2: 'Two', 4: 'Four', 6: 'Six', 8: 'Eight'}
        },
        x: {
            bw: 1,
            title: 'Year'
        }
    },
    coord: {
        type: 'polar'
    },
    dom: 'chart'
};
var c = polyjs.chart(spec);
var redraw = function () {
    jsondata.push( {index: i += 1, value: Math.random() + i});
    spec.layers[0].data.update({data: jsondata});
    c.make(spec);
    setTimeout(redraw, 1000);
}
setTimeout(redraw, 1000);

###Multiple Chart Types Multiple chart types sounds a bit peculiar at first, but this is a natural part of the modularity of Polychart. In the above example, we have two chart types: a line plot and a scatter plot, which serves to place the specific points of data on the chart. Each individual chart type is defined as a separate object in the layers array. Each chart type may be associated with any dataset, axis or legend by setting the individual options. In our example, the variables and axes associated with the two different chart types are the same because the intention of the above plot is to have a point at the end of a line. Of course, this is but the simplest use of the fact that Polychart allows layers rather than a single layer: plotting is an iterative process, and each component may be defined individually before putting everything into one!

###Random Data Inputting random data is a useful tool to have in your toolbox when working with charts. In this example we first define jsondata as an empty array with var jsondata= []; and then create a for loop that pushes an index i, and a random value, value: Math.random(), into the jsondata array. We can then associate the variables index and value to the layers and guides objects to populate the graph accordingly.

###Redraw Function In order to get the graph to continually populate itself with data we have created a redraw function. The function starts by defining the redraw function with var redraw = function(), and then pushes the new data into the jsondata array. For this example the value increases by an integer of 1 every iteration since we have added +i to value in the redraw function. Next we update the data by accessing data, in layers with spec.layers[0].data.update({data: jsondata}). And then we make the graph with c.make(spec). The function takes 1 second to run with setTimeout(redraw, 1000).

###Pie Charts Pie charts can be by setting a few options in the coord object. Specifically, we set the coordinate type of the chart to polar coordinates by including type: 'polar' in the coord object.

##Example 3: Drill Downs In this example we will focus on something called graph drill downs. Drill downs are functions that zoom into the details of the data. For example if we drilled down on data from year to the month of February we would see data for each day of the month. To see the drill down graph in action visit this link! (link to drill down graph).

var jsondata = [
{ country: 'Canada', region: 'Ontario', city: 'Toronto', value: 286000000000 }, 
{ country: 'Canada', region: 'Ontario', city: 'Kingston', value: 14000000000},
{ country: 'Canada', region: 'Ontario', city: 'Waterloo', value: 21000000000 },
{ country: 'Canada', region: 'Ontario', city: 'Kitchener', value: 19800000000 },
{ country: 'Canada', region: 'BC', city: 'Vancouver', value: 90000000000 },
{ country: 'Canada', region: 'BC', city: 'Victoria', value: 191000000000 },
{ country: 'Canada', region: 'BC', city: 'Kelona', value: 10000000000 },
{ country: 'Canada', region: 'Nova Scotia', city: 'Halifax', value: 14990000000 },
{ country: 'United States', region: 'New York', city: 'Manhattan', value: 802400000000 },
{ country: 'United States', region: 'New York', city: 'Albany', value: 32345000000 },
{ country: 'United States', region: 'California', city: 'San Francisco', value: 518000000000 },
{ country: 'United States', region: 'California', city: 'San Antonio', value: 68400000000}];
var data = polyjs.data({data: jsondata});
var spec = {
    title:'GDP of City',
    layers: [
        { data: data, type: 'bar', y: 'sum(value)', x: 'country', color: 'country'}
    ],
    guides: {
        y : {
            type: 'num',
            title: 'Amount of GDP Made $'
        },
        x : {
            title: 'Country'
        },
        color : {
            title: 'Countries'
        }
    },
    dom: 'chart'
};
var c = polyjs.chart(spec)
c.addHandler(polyjs.handler.drilldown('x', ['country', 'region', 'city']));

First thing that is different about this code is the variable jsondata. To drill down different levels we will look at the country first, and then we will drill down to the countries region, and then we will drill down to the regions city, and then we will drill down to the cities value. In order for this to happen jsondata must be formatted appropriately. So for each value in jsondata we must specify its city, region, and country.

Another thing that is different about the drill downs is the layers array. In the layer we must specify that y is the sum of the values. That is, the value shown for the region level of the drill down is the sum of all the values associated to the cities in that region. Similarly, the value for the country level is the sum of all the values associated with the regions in that country. This is done so that when a level is clicked on so we can compare the total value in each country and region. For this we use y: 'sum(value)'.

The final change is the last line c.addHandler(polyjs.handler.drilldown('x', ['country', 'region', 'city'])). The addHandler method of the chart c takes the drill down handler and adds the interaction to the chart. The drill down handler is created by the call to polyjs.handler.drilldown , with arguments defining the axis to be changed, and the order of the drill down.

##Example 4:Other Important Chart Options There are some important chart options that were not mentioned in the previous example. We will go over them in this section.

###Flipping the Axes

var jsondata = [{a: 'Floyd Mayweather', b: 85000000, c: 'Boxing'}, 
                {a: 'Manny Pacquaio', b: 62000000, c: 'Boxing'}, 
                {a: 'Tiger Woods', b: 59400000, c: 'Golf'}, 
                {a: 'LeBron James', b: 53000000, c: 'Basketball'}, 
                {a: 'Roger Federer', b: 52700000, c: 'Tennis'}, 
                {a: 'Kobe Bryant', b: 52300000, c: 'Basketball'}, 
                {a: 'Phil Mickelson', b: 47800000, c: 'Golf'}, 
                {a: 'David Beckham', b: 46000000, c: 'Soccer'}, 
                {a: 'Cristiano Ronaldo', b: 42500000, c: 'Soccer'}, 
                {a: 'Peyton Manning', b: 42400000, c: 'Football'}];
var data = polyjs.data({data: jsondata});
var spec = {
    title: 'Highest Paid Athletes 2012',
    width: 800,
    layers: [
        { data: data, type: 'bar', x: {var: 'a', sort: 'b'}, y: 'b', color: 'c'}
    ],
    guides: {
        y : {
            type: 'num',
            min: 40000000,
            title: 'Amount of Money Made $'
        },
        x : {
            title: 'Name of Athletes',
            numticks: 10
        },
        color: {
            title: 'Type of Sport'
        }
    },
    coord: {
        type: 'cartesian',
        flip: true
    },
    dom: 'chart'
};
var c = polyjs.chart(spec);

Looking at the example “Highest Paid Athletes of 2012” we can see that having flipped axes is useful because otherwise the x labels would overlap. Flipping the axes has to do with coordinates, so we will look into spec and then into the coord object. We will specify that we want Cartesian coordinates and the axes to be flipped with the lines type: 'cartesian', flip: true.

###Making a Facet Chart

var jsondata = [{a: 871530000, b: 'The Fellowship of the Ring'}, 
                {a: 926047000, b: 'The Two Towers'}, 
                {a: 1119929000, b: 'The Return of the King'}, 
                {a: 949541000, b: 'The Hobbit'}];
var data = polyjs.data({data: jsondata});
var spec = {
    title: 'Lord of the Rings Box Office Gross',
    width: 800,
    layers: [
        { data: data, type: 'bar',  y: 'a', color: 'b', position: 'dodge'}
    ],
    guides: {
        y : {
            type: 'num',
            numticks: 10,
            title: 'Amount of Money Grossed $'
        },
        color: {
            title: 'Movies'
        }
    },
    dom: 'chart',
    facet: {
        type: 'wrap',
        var: 'b',
        cols: 4
    }
};
var c = polyjs.chart(spec);

A facet chart is used for comparing similar groups of data. Faceting a plot by a variable will produce multiple, smaller charts, one for each value of that variable. In the example of “Lord of the Rings” we compare how much money each Lord of the Rings movie grossed. A facet chart was made by putting an object called facet inside spec and then specifying some basic properties. In this example we specified  cols: 4 to tell Polychart that there would be 4 facet charts made, and var: 'b' to tell Polychart to base the different facet charts off the variable b. To specify that we wanted the graphs to continue on the next line if they could not fit we entered type: 'wrap'.

###Making a Box Chart We tell Polychart that we want a box chart to be made by specifying type: 'box' inside of the layers array. To make a box plot the y axis must calculate a median, upper quartile, and a lower quartile. Polychart does the necessary calculations when we specify in the layers array y: 'box(value)'.

Add a custom footer
Add a custom sidebar
Clone this wiki locally