If you have been following this series from the beginning, you might have noticed that Plotly.js uses the same scatter type for creating both line charts and bubble charts. The only difference is that we had to set the mode to lines while creating line charts and markers when creating bubble charts. 

Similarly, Plotly.js allows you to create pie, donut and gauge charts by using the same value for the type attribute and changing the value of other attributes depending on the chart you want to create.

Creating Pie Charts in Plotly.js

You can create pie charts in Plotly.js by setting the type attribute to pie. There are also other attributes like opacity, visible and name that are common to other chart types as well. The name attribute is used to provide a name for the current pie trace. This name is then shown in the legend for identification. You can show or hide the pie trace in the legend of a chart by setting the showlegend attribute to true or false respectively. You can set a label name for the different sectors of a pie chart by using the labels attribute.

In the case of pie charts, the marker object is used to control the appearance of different sectors of the chart. The color attribute nested inside marker can be used to set the color of each sector of the pie chart. The color for different sectors can be specified as an array value to the color attribute.

You can also set the color and width of all the lines enclosing each sector using the color and width attributes nested inside the line object. You also have the option to sort all the sectors of the pie chart from largest to smallest using the boolean sort attribute. Similarly, the direction of the sectors can be changed to clockwise or counterclockwise with the help of the direction attribute.

The following code creates a basic pie chart that lists the forested area of the top five countries in the world.

var pieDiv = document.getElementById("pie-chart");

var traceA = {
  type: "pie",
  values: [8149300, 4916438, 4776980, 3100950, 2083210],
  labels: ['Russia', 'Canada', 'Brazil', 'United States', 'China']
};

var data = [traceA];

var layout = {
  title: "Area Under Forest for Different Countries"
};

Plotly.plot(pieDiv, data, layout);

As you can see, we are no longer using the x and y attributes to specify the points that we want to plot. This is now done with the help of values and labels. The percentages are determined automatically based on the input values.

By default, the first slice of the pie starts at 12 o'clock. You can change the starting angle of the chart using the rotation attribute, which accepts a value between -360 and 360. The default 12 o'clock value is equal to the angle 0.

If you want a slice in your chart to stand out, you can use the pull attribute, which can accept either a number or an array of numbers with values between 0 and 1. The pull attribute is used to pull the specified sectors out of the pie. The pull distance is equal to a fraction of the larger radius of the pie or donut.

It is very easy to convert a pie chart into a donut chart by specifying a value for the hole attribute. It will cut the given fraction of the radius out from the pie to make a donut chart.

You can control the color of individual sectors in a pie chart using the colors attribute nested inside the marker object. The width and color of the line that encloses each sector can also be changed with the help of the width and color attributes nested inside the line object. The default width of the enclosing line is 0. This means that no line will be drawn around the sectors by default.

There is also a hovertext attribute, which can be used to provide some extra textual information for each individual sector. This information will be visible to viewers when they hover over a sector. One condition for the text to appear is that the hoverinfo attribute should contain a text flag. You can set the color of text lying inside or outside of the pie sectors using the family, size and color attributes nested inside the insidetextfont and outsidetextfont objects respectively.

The following code uses the data from our previous pie chart to create a donut chart that uses the additional attributes we just learned about.

var pieDiv = document.getElementById("pie-chart");

var traceA = {
  type: "pie",
  values: [8149300, 4916438, 4776980, 3100950, 2083210],
  labels: ['Russia', 'Canada', 'Brazil', 'United States', 'China'],
  hole: 0.25,
  pull: [0.1, 0, 0, 0, 0],
  direction: 'clockwise',
  marker: {
    colors: ['#CDDC39', '#673AB7', '#F44336', '#00BCD4', '#607D8B'],
    line: {
      color: 'black',
      width: 3
    }
  },
  textfont: {
    family: 'Lato',
    color: 'white',
    size: 18
  },
  hoverlabel: {
    bgcolor: 'black',
    bordercolor: 'black',
    font: {
      family: 'Lato',
      color: 'white',
      size: 18
    }
  }
};

var data = [traceA];

var layout = {
  title: "Area Under Forest for Different Countries"
};

Plotly.plot(pieDiv, data, layout);

Creating Gauge Charts in Plotly.js

The basic structure of a gauge chart is similar to a donut chart. This means that we can use some cleverly selected values and create simple gauge charts by still keeping the type attribute set to pie. Basically, we will be hiding some sections of the full pie to make it look like a gauge chart.

First, we need to choose some values for the values attribute. To keep things simple, I will be using the top half of the pie as my gauge chart. This means that the values should be divided equally between the part that I want to be visible and the part of the pie chart that I want to hide. The visible section of the chart can further be divided into smaller parts. Here is an example of choosing the values for our gauge chart.

values: [100 / 5, 100 / 5, 100 / 5, 100 / 5, 100 / 5, 100]

The number 100 in the above line is arbitrary. As you can see, the first five slices together add up to 100, which is also the value set for the hidden area of the pie chart. This divides the whole pie equally between the hidden and visible part.

Here is the complete code that creates our basic gauge chart. You should note that I have set the color attribute of the sector that should be hidden to white. Similarly, the text and labels values for the corresponding sector have also been set to empty strings. The rotation attribute has been set to 90 so that the chart is not drawn from its default 12 o'clock position.

var gaugeDiv = document.getElementById("gauge-chart");

var traceA = {
  type: "pie",
  showlegend: false,
  hole: 0.4,
  rotation: 90,
  values: [100 / 5, 100 / 5, 100 / 5, 100 / 5, 100 / 5, 100],
  text: ["Very Low", "Low", "Average", "Good", "Excellent", ""],
  direction: "clockwise",
  textinfo: "text",
  textposition: "inside",
  marker: {
    colors: ["rgba(255, 0, 0, 0.6)", "rgba(255, 165, 0, 0.6)", "rgba(255, 255, 0, 0.6)", "rgba(144, 238, 144, 0.6)", "rgba(154, 205, 50, 0.6)", "white"]
  },
  labels: ["0-10", "10-50", "50-200", "200-500", "500-2000", ""],
  hoverinfo: "label"
};

The next part of the code deals with the needle of the gauge chart. The value that you set for the degrees variable will determine the angle at which the needle is drawn. The radius variable determines the length of the needle. The attributes x0 and y0 are used to set the starting point of our line. Similarly, the attributes x1 and y1 are used to set the ending point of our line. 

You can create more complex shapes for your needle with the help of SVG paths. All you have to do is set the type attribute to path and specify the actual path using the path attribute. You can read more about it in the layout shapes section of the reference.

var degrees = 115, radius = .6;
var radians = degrees * Math.PI / 180;
var x = -1 * radius * Math.cos(radians);
var y = radius * Math.sin(radians);

var layout = {
  shapes:[{
      type: 'line',
      x0: 0,
      y0: 0,
      x1: x,
      y1: 0.5,
      line: {
        color: 'black',
        width: 8
      }
    }],
  title: 'Number of Printers Sold in a Week',
  xaxis: {visible: false, range: [-1, 1]},
  yaxis: {visible: false, range: [-1, 1]}
};

var data = [traceA];

Plotly.plot(gaugeDiv, data, layout, {staticPlot: true});

All the code of this section creates the following gauge chart. Right now, the chart is not very fancy, but it can act as a good starting point.

Final Thoughts

In this tutorial, you learned how to create pie and donut charts using the pie trace type in Plotly.js. You also learned how to carefully set the values of a few attributes to convert those pie charts into simple gauge charts. You can read more about pie charts and their different attributes on the reference page.

This was the last tutorial of our interactive Plotly.js charts series. The first introductory tutorial provided you an overview of the library. The second, third and fourth tutorials showed you how to create line charts, bar charts, and bubble charts respectively. I hope you enjoyed this tutorial as well as the whole series. If you have any questions, feel free to let me know in the comments.