12.3.2 ⁑The databar Package

12.3.2 ⁑The `databar` Package

The databar package is part of the datatool bundle [95] and can be used to generate bar charts from data stored in a datatool database. The bar charts may be either vertical or horizontal. The default is vertical. The databar package has the following package options:

color: Create coloured bar charts (default).
gray: Create grey scale bar charts.
vertical: Create vertical bar charts (default). The x-axis is the horizontal axis and the y-axis is the vertical axis.
horizontal: Create horizontal bar charts. The x-axis is the vertical axis and the y-axis is the horizontal axis.

There are two commands provided to generate a bar chart:

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

and

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

The former generates a bar chart from a single column of data and the latter generates a bar chart with groups of bars representing multiple columns of data. The ⟨condition⟩, ⟨db-name⟩ and ⟨assign list⟩ are the same as for \DTLforeach. The ⟨settings⟩ argument is a key=value list where the following keys are available:

variable: This specifies the control sequence (which must be set in ⟨assign list⟩) that contains the value used to construct the bar chart. This key is required for \DTLbarchart and is unavailable for \DTLmultibarchart.
variables: This specifies a comma-separated list of control sequences (which must all be set in ⟨assign list⟩) that contain the values used to construct the bar chart. This key is required for \DTLmultibarchart and is unavailable for \DTLbarchart.
max: The maximum value on the y-axis. (A decimal number.)
length: The overall length of the y-axis. (A dimension.)
maxdepth: A zero or negative number (not a dimension) that specifies the maximum depth of the y-axis.
axes: This may take one of the following values: both (show both axes), x (only show the x-axis), y (only show the y-axis) or none (don't show either axes).
barlabel: Sets the lower bar label. When used with \DTLmultibarchart this indicates the group label.
multibarlabels: This value should be a comma-separated list of labels for each bar within a group for \DTLmultibarchart. This key is not available for \DTLbarchart.
upperbarlabel: The upper bar label. This key is not available for \DTLmultibarchart.
uppermultibarlabels: This value should be a comma-separated list of upper labels for each bar within a group for \DTLmultibarchart. This key is not available for \DTLbarchart.
yticpoints: A comma-separated list of tick locations for the y-axis. This setting overrides yticgap.
yticgap: Specifies the gap (a number not a dimension) between the y-tick marks.
yticlabels: A comma-separated list of tick labels for the y-axis.
ylabel: The y-axis label.
groupgap: The gap (a number in terms of the width of a bar) between groups when using \DTLmultibarchart. The default is 1, which indicates one bar width. This key is not available for \DTLbarchart.
verticalbars: A boolean key where true indicates a vertical bar chart and false indicates a horizontal bar chart.

In addition to the above settings, you can also change the appearance of the bar chart by changing any of the following before drawing the chart. Remember that you need to use \setlength to change the value of a length register. The y-tick labels are rounded to ⟨n⟩ digits after the decimal point, where ⟨n⟩ is given by the counter DTLbarroundvar.

\DTLbarchartlength

This is a length register that stores the total length of the y-axis. The default is 3 in.

\DTLbarwidth

This is a length register that stores the width of each bar. The default is 1 cm.

\DTLbarlabeloffset

This is a length register that stores the distance from the x-axis to the lower bar label. The default is 10 pt.

\DTLsetbarcolor {⟨n⟩}{⟨colour⟩}

This sets the ⟨n⟩th bar colour to ⟨colour⟩. Only the first eight bars have a colour defined by default. You need to use this command if you need more than eight bars or if you want to override the default colours.

\DTLdobarcolor {⟨n⟩}

Sets the current text colour to the colour of the ⟨n⟩th bar.

\DTLbaroutlinecolor

This macro expands to the colour of the bar outlines. This defaults to black. Use \renewcommand to change this value.

\DTLbaroutlinewidth

A length register that stores the line width for the bar outlines. If it is set to 0 pt, the outline is not drawn. The default value is 0 pt.

Both \DTLbarchart and \DTLmultibarchart draw the chart inside a tikzpicture environment. You can redefine the following commands to insert code at the start or end of this environment:

\DTLbaratbegintikz

for the hook at the start (after the unit vectors are set) and

\DTLbaratendtikz

for the hook at the end.

There is also a hook for code to apply at every bar:

\DTLeverybarhook

Within this book you can use \DTLstartpt (the start of the bar), \DTLmidpt (the mid point of the bar) and \DTLendpt (the end of the bar).

There are other commands as well that can be redefined to change the appearance of the bar chart. See the databar section of the datatool manual [95] for further details.

Example 62. An Example Bar Chart (databar package)

The pie chart from Example 60 can be reproduced as a bar chart as shown below. Since some of the book titles are quite long, the title has been placed inside a \parbox to prevent the image from becoming overly tall and the bars are made wider by changing the value of \DTLbarwidth.

\documentclass{article}

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

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

\DTLloaddb{books}{booklist.csv}

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

\setlength{\DTLbaroutlinewidth}{1pt}
\setlength{\DTLbarwidth}{1.2cm}

\begin{document}

\setcounter{DTLbarroundvar}{2}

\DTLbarchart
 {variable=\ThePrice,% database column
  axes=both,% show both axes
  barlabel=\parbox{4cm}{\raggedright\TheTitle},% bar labels
  upperbarlabel={\pounds{ThePrice}},% upper bar labels
  yticgap=10,% gap between y tick marks
  ylabel={Price (\pounds)}% y-axis label
 }% settings
 {books}% database
 {\ThePrice=price,\TheTitle=title}% assignment list

\end{document}

This produces the chart shown in Figure 12.10. You can download or view this example.

**Figure 12.10:** A Bar Chart (`databar` package)
⇩

⇦

⇧

⇨

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