12.2.1 ⁑The datapie Package

12.2.1 ⁑The `datapie` Package

As mentioned above, the datapie package is part of the datatool bundle [95]. The datapie package automatically loads the datatool and tikz packages. The following package options are provided:

color: Use colour (default).
gray: Use greyscale.
rotateinner: Rotate the inner labels so that they are aligned with the pie chart radial axis.
norotateinner: Don't rotate the inner labels (default).
rotateouter: Rotate the outer labels so that they are aligned with the pie chart radial axis.
norotateouter: Don't rotate the outer labels (default).

Once you have loaded the data (see §2.2 Loading Data), the numerical data within the database can be displayed as a pie chart using:

\DTLpiechart [⟨condition⟩]{⟨settings⟩}{⟨db-name⟩}{⟨assign list⟩}

The optional argument ⟨condition⟩ is the same as that for \DTLforeach, ⟨db-name⟩ is the label uniquely identifying the database, and ⟨assign list⟩ is a comma-separated list of ⟨cmd⟩=⟨col-label⟩ pairs, the same as the penultimate argument of \DTLforeach. The remaining argument ⟨settings⟩ is a key=value list. The variable key must be present, but the remaining keys may be omitted.

variable: The command to use (as specified in ⟨assign list⟩) that contains the data to be used to construct the pie chart. (Required.)
start: The starting angle (degrees) of the first segment. The default is 0.
radius: The radius of the pie chart. The default is 2 cm. This sets the length \DTLradius.
innerratio: The distance from the centre of the pie chart to the point where the inner labels are placed is given by this value multiplied by the radius. This must come after radius, if the radius also needs to be set. The default is 0.5.
inneroffset: The distance from the centre of the pie chart to the point where the inner labels are placed. This may be used instead of innerratio. If inneroffset is omitted, the innerratio is used.
outerratio: The distance from the centre of the pie chart to the point where the outer labels are placed is given by this value multiplied by the radius. This must come after radius, if the radius also needs to be set. The default is 1.25.
outeroffset: The distance from the centre of the pie chart to the point where the outer labels are placed. This may be used instead of outerratio. If outeroffset is omitted, the outerratio is used.
cutawayratio: The distance from the centre of the pie chart to the point of cutaway segments is given by this value multiplied by the ratio. This must come after radius, if the radius also needs to be set. The default is 0.2.
cutawayoffset: The distance from the centre of the pie chart to the point of cutaway segments. This may be used instead of cutawayratio. If cutawayoffset is omitted, the cutawayratio value is used.
cutaway: The list of cutaway segments. This should be a comma-separated list of individual numbers, or number ranges (separated by a dash). For example, cutaway={1,3} will separate the first and third segments from the rest of the pie chart, whereas cutaway={1-3} will separate the first three segments. If omitted, the pie chart will be whole with no cutaway segments.
innerlabel: The inner label for the segments. The value may contain any of the commands assigned in ⟨assign list⟩. The default is the same as the value of the variable key.
outerlabel: The outer label for the segments. The value may contain any of the commands assigned in ⟨assign list⟩. The default is empty.
rotateinner: This is a boolean key. If true, the inner labels are rotated so that they are aligned with the pie chart radial axis.
rotateouter: This is a boolean key. If true, the outer labels are rotated so that they are aligned with the pie chart radial axis.

The datapie package predefines colours for the first eight segments of the pie chart. If these don't suit your requirements, or if you have more than eight rows of data, you can set the colour for a given segment using:

\DTLsetpiesegmentcolor {⟨n⟩}{⟨colour⟩}

where ⟨n⟩ is the segment index (starting from 1) and ⟨colour⟩ is the colour, as used in commands like \color.

There are two commands provided that can be used within the inner or outer labels:

\DTLpievariable

This is set to the value of the variable key.

\DTLpiepercent

This command is set to the percentage value for the current segment. The value is rounded to ⟨n⟩ digits, where ⟨n⟩ is given by the counter DTLpieroundvar.

Example 60. An Example Pie Chart (datapie package)

Recall the sample booklist.csv file. Suppose, for some reason, I want to create a pie chart that displays the price for each book. The database contains 10 rows, so 10 segment colours need to be defined. A pie chart can be drawn as follows:

\documentclass{article}

\usepackage[x11names]{xcolor}
\usepackage{datapie}

\DTLloaddb{books}{booklist.csv}

% assign segment colours:

\DTLsetpiesegmentcolor{1}{Aquamarine1}
\DTLsetpiesegmentcolor{2}{Azure2}
\DTLsetpiesegmentcolor{3}{Burlywood3}
\DTLsetpiesegmentcolor{4}{CadetBlue2}
\DTLsetpiesegmentcolor{5}{Chartreuse3}
\DTLsetpiesegmentcolor{6}{Salmon1}
\DTLsetpiesegmentcolor{7}{DeepPink1}
\DTLsetpiesegmentcolor{8}{Goldenrod1}
\DTLsetpiesegmentcolor{9}{Honeydew1}
\DTLsetpiesegmentcolor{10}{Plum3}

\begin{document}

\DTLpiechart{%
 variable=\ThePrice,%
 innerratio=0.4,%
 innerlabel={\pounds\ThePrice},%
 rotateinner}%
 {books}% database name
 {\ThePrice=price}% assignment list

\end{document}

**Figure 12.5:** An Example Pie Chart (`datapie` package)
⇩

This produces the chart shown in Figure 12.5. However, this isn't particularly informative. The book titles could be added as an outer label, but as some of the titles are quite long, this would result in a rather messy chart. Instead, it would be neater to have a legend or key. The current text colour can be switched to the colour of a given segment using:

\DTLdopiesegmentcolor {⟨n⟩}

where ⟨n⟩ is the segment index. This is a declaration that internally calls \color. Alternatively, you can use

\DTLdocurrentpiesegmentcolor

which sets the colour for the current segment. This may be used inside a \DTLforeach loop:

\begin{tabular}{ll}
\DTLforeach*{books}{\TheTitle=title}%
{%
  \DTLiffirstrow{}{\\}%
  \DTLdocurrentpiesegmentcolor\rule{10pt}{10pt} & \TheTitle
}
\end{tabular}

Recall from Volume 1 that the tabular environment is a form of box. The pie chart created using \DTLpiechart is also a box, so the two can be placed beside each other, however you might need to adjust the vertical alignment. The complete document is as follows:

\documentclass{article}

\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[x11names]{xcolor}
\usepackage{datapie}

\DTLloaddb{books}{booklist.csv}

% assign segment colours:

\DTLsetpiesegmentcolor{1}{Aquamarine1}
\DTLsetpiesegmentcolor{2}{Azure2}
\DTLsetpiesegmentcolor{3}{Burlywood3}
\DTLsetpiesegmentcolor{4}{CadetBlue2}
\DTLsetpiesegmentcolor{5}{Chartreuse3}
\DTLsetpiesegmentcolor{6}{Salmon1}
\DTLsetpiesegmentcolor{7}{DeepPink1}
\DTLsetpiesegmentcolor{8}{Goldenrod1}
\DTLsetpiesegmentcolor{9}{Honeydew1}
\DTLsetpiesegmentcolor{10}{Plum3}

\begin{document}

% pie chart:
\DTLpiechart{%
 variable=\ThePrice,%
 innerratio=0.4,%
 innerlabel={\pounds\ThePrice},%
 rotateinner}%
 {books}% database name
 {\ThePrice=price}% assignment list
\qquad% add some horizontal space
% legend:
\begin{tabular}[b]{ll}
\DTLforeach*{books}{\TheTitle=title}%
{%
  \DTLiffirstrow{}{\\}%
  \DTLdocurrentpiesegmentcolor\rule{10pt}{10pt} &
  \TheTitle
}
\end{tabular}

\end{document}

This produces the image shown in Figure 12.6. You can download or view this document.

**Figure 12.6:** An Example Pie Chart with a Legend (`datapie` package)
⇩

Exercise 31. A Pie Chart (datapie package)

Recall the sample orders.csv file. Create a pie chart that displays the values in the quantity column. Alternatively you can use the orders SQL table.

For the More Adventurous (SQL)

A pie chart showing just the quantity column isn't particularly informative. It would be more interesting to have a pie chart of the total quantities ordered for each book title (rather than per order) accompanied by the title and format. This requires pulling data from multiple tables, which is far more efficiently done using SQL than using TeX. The SELECT statement is:

> SELECT books.title AS booktitle, books.format AS bookformat, SUM(orders.quantity) AS total FROM orders, books WHERE orders.bookid=books.id GROUP BY orders.bookid

(If you want the data sorted in descending order of total quantities, you can append ORDER BY total DESC.)

Create a pie chart that shows the order totals for each book with a legend that shows the book title and format.

\DTLpiechart uses the tikzpicture environment and there are two hooks available to add additional picture drawing commands to that environment:

\DTLpieatbegintikz

This command is performed before the pie chart is drawn.

\DTLpieatendtikz

This command is performed after the pie chart is drawn.

Use one of these commands to add the legend as a node inside the tikzpicture environment. Hint: tikz allows radial coordinates specified in the form (⟨angle⟩:⟨radius⟩). You can download or view the solution to this exercise.

⇦

⇧

⇨

This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-07-4).