General bar charts
For a general bar chart one needs to prepare an SVG file that has
named (XML attribute ‘id’) groups (XML element ‘g’) of bar segments (XML
element ‘rect’) and, optionally, value labels (XML element ‘text’).
svg <- read_svg(file = "images/fig3.svg",summary = TRUE,display = TRUE)
Reading the SVG file with arguments summary=TRUE and
display=TRUE conveniently prints information about it on
the console and displays the SVG in the current viewport (see here). It might look like that:
Fig. 3: Bar chart example
In this example the XML structure has two named groups. The first
consists of the XML elements (3 rectangles and 3 texts) for the leftmost
bar and is named ‘overall’. The second one is a group named ‘subgroups’
that itself contains three groups of XML elements for the three bars to
the right. See the following excerpt of the file:
...
<g id="overall">
<rect x="156.746" y="255.119" fill="#3C3C3B" width="26.667" height="56.693"/>
<rect x="156.746" y="198.425" fill="#878787" width="26.667" height="56.693"/>
<rect x="156.746" y="141.732" fill="#C6C6C6" width="26.667" height="56.693"/>
<text transform="matrix(1 0 0 1 164.5171 306.2188)" fill="#FFFFFF" font-family="'ArialMT'" font-size="10">20</text>
<text transform="matrix(1 0 0 1 164.5171 249.5259)" fill="#FFFFFF" font-family="'ArialMT'" font-size="10">20</text>
<text transform="matrix(1 0 0 1 164.5171 192.833)" font-family="'ArialMT'" font-size="10">20</text>
</g>
<g id="subgroups">
<g>
<rect x="213.438" y="255.119" fill="#3C3C3B" width="26.667" height="56.693"/>
<rect x="213.438" y="198.425" fill="#878787" width="26.667" height="56.693"/>
<rect x="213.438" y="141.732" fill="#C6C6C6" width="26.667" height="56.693"/>
<text transform="matrix(1 0 0 1 221.21 306.2188)" fill="#FFFFFF" font-family="'ArialMT'" font-size="10">20</text>
<text transform="matrix(1 0 0 1 221.21 249.5259)" fill="#FFFFFF" font-family="'ArialMT'" font-size="10">20</text>
<text transform="matrix(1 0 0 1 221.21 192.833)" font-family="'ArialMT'" font-size="10">20</text>
</g>
<g>
...
</g>
<g>
...
</g>
</g>
...
The summary on the console will reflect this. Note that the number of
child elements depends on wether a named group consists of bar elements
or of further (sub)groups:
[1] "-- NAMED GROUPS:"
[1] "overall with 6 children"
[1] "subgroups with 3 children"
Note: It is not allowed to nest the grouping any further!
The bar chart in the example of figure 3 needs two separate function
calls to be adjusted to values on the statistical scale. The first call
to stackedBar refers to the group named ‘overall’, the
second one to the group named ‘subgroups’. It is necessary to have a
named frame (XML element ‘rect’) for both cases (see here). Since the bar chart will be adjusted in
vertical direction (alignment="vertical" makes sure that
y-coordinates and heights are changed) the SVG needs to have only one
such rectangle for both the overall bar and the bars for subgroups.
The main difference between the two function calls is how one
provides the values. In the case that a group refers to only one bar
(here: ‘overall’) values are provided as a simple numerical vector. If a
matrix or a dataframe were provided, only the first row would be used.
The function call will fail with an error message if the number of
values does not match the number of bar segments (or value labels).
In the case that a group refers to (sub)groups (here: ‘subgroups’)
one needs to provide a matrix or a dataframe. Rows will be used to get
values for each bar, while the order of columns defines the values from
left to right with alignment="horizontal" or bottom to top
with alignment="vertical. The function call will stop with
an error message if the number of rows does not match the number of bars
and also if the number of values does not match the number of bar
segments (or value labels).
svg <- stackedBar(svg = svg,frame_name = "frame",group_name = "overall",
scale_real = c(0,160),values = c(9.97,42.42,105.71),
alignment = "vertical",has_labels = TRUE,label_position = "end",
decimals = 0,display_limits = 10)
df.subgroups <- matrix(1:9*8,nrow=3)
svg <- stackedBar(svg = svg,frame_name = "frame",group_name = "subgroups",
scale_real = c(0,160),values = df.subgroups,
alignment = "vertical",display_limits = 10)
display_svg(svg = svg)
write_svg(svg = svg,file = "images/fig3_values.svg",
remove_hidden = FALSE,flatten = TRUE)
The program code above will ultimately display the following chart
and also save it to a file:
Fig. 4: Adjusted bar chart example
The first function call to stackedBar in the example
above has set every argument there is for this function.
has_labels=TRUE and decimals=0 are actually
default values, which is why things work the same in the second function
call. While the meaning of has_labels=TRUE is obvious, note
how values are rounded to the number of decimal digits desired, so that
‘105.71’ becomes ‘106’ in the chart. It is possible to set the rounding
of the labels to rounding away from zero by
options("svgtools.roundAwayFromZero" = TRUE) such that
‘106.5’ becomes ‘107’ (default: ‘106’).
label_position="end" puts value labels to the top of the
bar segments in vertical aligment and to the right side (or left side
for negative values) in horizontal alignment. The default setting used
in the second function call puts value labels in the center of the bar
segments. Argument display_limits is used to suppress value
labes in a range around zero. If only one number is provided it refers
to the absolute value. In the example the value ‘8’ of the category A in
group 1 is not shown any more because it is lower than 10. Note that
this is evaluated for the exact value, not the rounded one. So ‘10.1’
would be visible (as ‘10’ with decimals=0) while ‘9.9’
would not.
Note that display options for value labels are rather limited in the
current version of svgtools. It is neither possible to set
the distance from the edge of bar segments with
label_position="start" or label_position="end"
nor will stackedBar change any coordinates or alignment of
texts that do not concern the x-axis with
alignment="horizontal" or y-axis with
alignment="vertical". This is why in the example ‘106’
(category C of overall bar) leans to the right: the text element was not
aligned to be centered in the SVG template (set XML attribute
‘text-anchor’ to “middle” beforehand, in order to do this).
The example code calls write_svg with otional arguments
(see here). With
remove_hidden=FALSE one will still have text elements for
the two value labels that are not displayed in the saved SVG file. And
flatten=TRUE leads to an SVG file without any groups (XML
elements ‘g’). All 60 graphical elements are stored directly beneath the
XML document node.
Special bar charts
With the help of hidden bar segments and recalculated
values one could already produce a wide range of bar charts
using stackedBar. For convenience, svgtools
offers three special variants. They work the same as the general case
when it comes to naming SVG elements. The following sections describe
each one very briefly and focussing on their distinct usage of function
arguments.
Reference bar
In svgtools a reference bar is a stacked bar chart that
is aligned around a nullvalue. Bar segments up to a so-called reference
category (a certain column/position of values) are
positioned to the left (with alignment="horizontal") or to
the bottom (with alignment="vertical") while further
segments lie to the right or top.
The following figure shows a possible template. Note that it is not
necessary to adjust bar segments and values (in horizontal direction)
beforehand.
Fig. 5: Reference bar example
An example code for usage of referenceBar looks like
that:
values <- matrix(c(1,2,3,4,2,3,4,1,3,4,1,2,4,1,2,3,1,2,3,4)*10,
nrow = 5,byrow = TRUE)
svg <- referenceBar(svg = svg,frame_name = "frame",group_name = "group",
scale_real = c(-100,100),values = values,
reference = 2,nullvalue = 0)
In regard of the x-axis labels, scale_real has to
provide an interval with a range of 200 that includes the
nullvalue. So even though the percentages in the example
are of course positive, defining the range of values from -100 to 100 is
feasible. The nullvalue will most often be at zero, so this
is also set as the default value. reference=2 defines, that
the first two values in each bar will be represented to the left of
whereever the nullvalue lies, while further values (another two in the
example) will be shown to the right. The result looks like this:
Fig. 6: Adjusted reference bar example
Difference bar
Another specialized bar chart provides the ability to show difference
values in regard to a null value (usually zero). Bar segments, and
optionally value labels, of values lower than the null value are
positioned to the left (with alignment="horizontal") or to
the bottom (with alignment="vertical") while higher values
are represented to the right or to the top.
The following example makes use of the general behavior of
svgtools that elements related to NA values are simply
hidden from the chart:
