About
Shop
LaTeX
Software
Books
Gallery
News
Contact
Blog
Settings
Account


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)
 
Image of pie chart with 10 segments. The price is placed inside the corresponding segment, rotated so that it's along the segment's midway axis.

Segment 1 (aquamarine fill colour): £10.99.
Segment 2 (azure fill colour): £19.99.
Segment 3 (burly-wood brown fill colour): £12.99.
Segment 4 (cadet blue fill colour): £11.99.
Segment 5 (chartreuse green fill colour): £19.99.
Segment 6 (salmon fill colour): £18.99.
Segment 7 (deep pink fill colour): £14.99.
Segment 8 (goldenrod fill colour): £8.99.
Segment 9 (honeydew fill colour): £5.99.
Segment 10 (plum fill colour): £59.99.

End of Image.

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:

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

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)
 
Image: the pie chart is the same as in the previous image, but there is now a legend to the right of the chart. Each row of the legend has a coloured square matching the corresponding segment colour and the book title.

[aquamarine square] The Adventures of Duck and Goose
[azure square] The Return of Duck and Goose
[burly-wood brown square] More Fun with Duck and Goose
[cadet blue square] Duck and Goose on Holiday
[chartreuse green square] The Return of Duck and Goose
[salmon square] The Adventures of Duck and Goose
[deep pink square] My Friend is a Duck
[goldenrod square] Annotated Notes on the ‘Duck and Goose’ chronicles
[honeydew square] ‘Duck and Goose’ Cheat Sheet for Students
[plum square] ‘Duck and Goose’: an allegory for modern times?

End of Image.

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:

This command is performed before the pie chart is drawn.

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).

© 2015 Dickimaw Books. "Dickimaw", "Dickimaw Books" and the Dickimaw parrot logo are trademarks. The Dickimaw parrot was painted by Magdalene Pritchett.

Terms of Use Privacy Policy Cookies Site Map FAQs