This vignette explains the unikn functions forplotting graphical elements and text decorations. (See the vignette oncolors for general information on colors,color palettes, and corresponding functions, or the more specializedvignettes on color recipes and institutional colors.)
Overview
Beyond providing support for colors,unikn provides functions for plotting graphicalelements (like boxes) and text decorations (with colored backgrounds orunderlining). Before illustrating these functions, please note somecaveats:
Plotting text (i.e., graphically rendering characters) is rarelya good idea. In contrast to the vector fonts used by DTP programs,plotted text typically does not scale (when changing the size of images)and cannot be recognized automatically (e.g., copied, indexed, orscraped). Hence, the following functions should only be used when nobetter solutions are available (e.g., for adding text to graphs, or forobstructing automatic text recognition).
Like all other templates, our renderings are subject toconstraints and limitations. For instance, as any standard installationof R lacks the prescribed“Theinhardt” fonts, we only mimic the official design specifications (inArial, sans serif).
That said, digital decorations can be useful to emphasize orstructure information, provided that they can be produced easily andflexibly. The unikn package helps preventing commonmistakes by novices (e.g., boxes or lines extending beyond text, orstep-functions in multi-line headings) and can be customized andimproved by expert users. Hence, we hope that the following functionsare useful for plotting graphical elements (e.g., boxes, logos, etc.)and help you achieve a uniform look when styling presentations orvisualizations.
Please load the unikn package to get started:
library(unikn) # load unikn package
Plotting empty slides and boxes
As the text functions of unikn add styled text to anexisting plot, we must first create a plot to which we can add text.unikn provides 2 basic functions for creating newplots:
slide
plots an empty canvass (a rectangular box orframe);xbox
plots a colored box with an X in its top rightcorner.
Here are both commands with their default settings:
slide() # plot default slide
xbox() # plot default xbox
Both functions accept additional arguments to customize theirappearance.
Colors
The background and border colors of slides can be changed by settingtheir col
, border
, and lwd
arguments:
slide(col = pal_seeblau[[1]], border = Petrol, lwd = 5) # set colors of slide background and border
slide(col = pal_peach[[2]], border = NA) # colored slide without a border
Similarly, the background color of xboxes can be changed by thecol
argument:
xbox(col = Pinky) # set background color of xbox
Dimensions
By default, both slide
and xbox
fill theentire plotting region (i.e., all margins are set to 0).
The width of a slide is set to 4/3of its height (of1). To changethis default, use the dim
argument for specifying theslide’s x- and y-dimensions, respectively:
slide(dim = c(3, 1)) # a slide 3 times wider than high
Note that changes in slide dimensions are invisible when viewingimages interactively, as R automatically scales images to the size ofthe canvass. They mostly affect the relation between metrics when addingelements to anobject.
Similarly, an xbox has the default dimensions of a unit square (i.e.,dim = c(1, 1)
). To change this default, use thedim
argument for specifying the xbox’s x
- andy
-dimensions, respectively:
xbox(col = Petrol, dim = c(1, 2)) # an xbox 2 times higher than wide
The two strokes of theX (in the top right corner) are orthogonalwhen viewing the xbox
at the aspect ratio indicated bydim
(i.e., here: at a ratio of width x = 1 to height y =2). When viewing the box at any different aspect ratio, the X appears tobe distorted. Hence, viewing and printing plots at the desired aspectratio helps when creating an xbox.
Plotting styled text
There are three main functions for plotting text withdecorations:
mark()
allows highlighting text with colored backgroundboxes;uline()
allows underlining text with coloredlines;post()
allows posting text in rectangularxbox
elements.
In addition, there are 2 auxiliary functions:
headline()
allows plotting headlines with coloredbackground boxes;url_unikn()
allows formatting URLs the uni.kn way.
The following sections illustrate the functions and their mainoptions in turn.
Mark text
The mark()
function allows highlighting text by plottingit with colored background boxes (to provide the functionality of“Markieren”):
By default, mark()
assumes that we want to addhighlighted text to anexisting plot. The text labels to be added areprovided (as a character vector) by the labels
argument,their coordinates as the correspondingx
andy
arguments. Various text decorations (i.e., text and background colors,text sizes, and font types) can be set by specifying additionalarguments (i.e., col
, col_bg
,cex
, and font
, respectively):
# Some pre-existing plot: n <- 20set.seed(1)par(mar = c(0, 0, 0, 0))plot(x = runif(n), y = runif(n), type = "p", pch = 16, cex = 20, col = grey(0, .2), axes = FALSE, xlab = "", ylab = "")# Add 1 marked label:mark(labels = "Some messy plot", x = .02, y = .9)# Add 2 more marked labels:mark(labels = c("Note something here.", "More highlighting here."), x = c(.1, .6), y = c(.2, .4), col_bg = c(pal_seeblau[[2]], pal_peach[[3]]), cex = 1.2)
If no pre-existing plot is available, setting thenew_plot
argument to either"blank"
or"slide"
will generate a new default plot (by calling theslide()
function described above):
# A sentence to plot: s <- c("Markieren", "ist ein Bestandteil", "von Studieren.")# Create a new plot (of type "slide"):mark(labels = s, x = 0, y = .85, y_layout = .03, col_bg = Seeblau, cex = 1.5, new_plot = "slide")# Add text to the same plot:mark(labels = s, x = 0, y = .40, y_layout = .03, col_bg = pal_pinky[[2]], cex = 1.5, new_plot = "none")
Rather than providing explicit x
andy
coordinates for all text elements inlabels
,the calls above defined an initial coordinate and used a numericy_layout
argument to fix the distance between consecutivetext labels (to a value of.03
).
As an alternative to numeric coordinates and position values,x_layout
and y_layout
also accept some specialvalues (as character strings):
x_layout
accepts:x_layout = "center"
for centering labels horizontally(on the first label or the middle),x_layout = "left"
left-justifies labels (on the firstlabel or the middle), andx_layout = "right"
right-justifies labels (on the firstlabel or the middle).
y_layout
accepts:y_layout = "even"
for an even distribution of labelsacross the available y-space, andy_layout = "flush"
to omit space between adjacentlabels (as iny_layout = 0
).
Thus, the position and orientation of the text labels can becontrolled by using the x_layout
and y_layout
options:
See ?mark
for details.
Underline text
The uline()
function allows emphasizing text by plottingit with colored underlining (to provide the functionality of“Unterstreichen”):
As with mark()
above, the uline()
commanddistinguishes between creating a new plot (by settingnew_plot
to either "blank"
or“slide
”) or adding to a pre-existing plot (by using thedefault new_plot = "none"
):
lbl_uline <- c("This is neat, true, and terribly important")uline(labels = lbl_uline, new_plot = "blank", y = .6, cex = 1.1) # create a new plotuline(labels = "(which is why we underline it).", y = .45, cex = 1) # add to plot
The arguments for text elements (labels
), text positions(x
, y
, y_layout
), and textproperties and decorations (col
, col_bg
,cex
, and font
) work as they do formark()
. For instance, shorter vectors are recycled to matchthe length of labels
:
slogan <- c("Geradlinig", "Farbenfroh", "Beweglich", "Bunt", "Paradiesisch")uline(labels = slogan, x = c(0, .5), y = .9, y_layout = "even", col = c("black", Bordeaux), col_bg = c(Seeblau, Seegruen), cex = 1.1, font = 2, new_plot = "blank")
The position and orientation of the text labels can be controlled byusing the x_layout
and y_layout
options:
Post text
The post()
function allows adding text to arectangularxbox
(to provide the functionality of“Merken”):
By default, post()
assumes a pre-existingxbox
to which the text elements of labels
areto be added.
For square boxes, setting new_plot
to "xbox"
creates a newxbox
with its default dimensions ofdim = c(1, 1)
.
By adjusting its color and text arguments, post()
allowscreating simple badges or logos:
# Badge (to view as 250 x 250 pixel):post(labels = "ToDo", y = .35, col = "white", col_bg = pal_signal[[1]], cex = 3, font = 2, new_plot = "xbox") # Badge (to view as 250 x 250 pixel):post(labels = "R", y = .35, col = "white", col_bg = pal_seeblau[[5]], cex = 8, font = 2, new_plot = "xbox")
Another potential use of post()
is for creating imagesproviding contact details:
address <- c("Dr. B. F. Skinner", " ", "Department of Psychology", "Office Z101", "Tel.: +49 7531 88-0815", "Fax: +49 7531 88-0810", "b.f.skin@uni-konstanz.de")post(labels = "Contact", y = .7, cex = 1.2, font = 2, col_bg = Petrol, new_plot = "xbox") # create new plot post(labels = address, y = .5, y_layout = .03, new_plot = "none") # add to plot
As above, the position and orientation of the text labels can becontrolled by using the x_layout
and y_layout
options:
Headings
The heading()
function makes it easy to createrecognizable headings:
By default, the function creates a new slide (i.e.,new_plot = "slide"
) and positions the text elementsoflabels
on its left edge (i.e., x = 0
,y = .8
and y_layout = "flush"
). When headingsviolate the official recommendations, a message is provided:
heading(labels = c("Ewig", "währt am", "längsten..."), y = 2/3, col_bg = usecol(pal_pinky))
Re-arranging words helps to avoid step-wise titles (see p.25 of theCDmanual):
# Beware of step-wise arrangements:heading(labels = c("Ich", "bin keine", "gute Headline."))#> Step-wise titles are discouraged: Consider re-arranging?
# Avoiding warning:heading(labels = c("Ich bin", "eine alternative", "Headline."))
When colors are left unspecified, heading()
selectscolors that are appropriate for the number of elements inlabels
(i.e., shades of Seeblau
forcol_bg = "default"
). However, default colors can beoverwritten by setting thecol
andcol_bg
arguments:
heading(labels = c("Ene,", "mene, miste,", "es rappelt", "in der Kiste."), col = "white", col_bg = c(Pinky, Seegruen, Bordeaux, Karpfenblau))
URLs
One of the more obscure rules (on p.31 of the CD manual) concernsthe rendering of URLs, in which typical web patterns (like “http” or“www”) are to be omitted and replaced by a typographical dash (which islonger than a hyphen). The url_unikn
utility functionallows formatting URLs the uni.kn way:
my_url <- url_unikn("https://www.uni-konstanz.de/") # input URL as copied from web browsermy_url # formatted URL#> [1] "‒ uni-konstanz.de"# Put URL at bottom of an xbox:post(labels = my_url, x = .05, y = .1, font = 4, col_bg = pal_seeblau[[5]], new_plot = "xbox")
Resources
The following versions of unikn and correspondingresources are currently available:
Type: | Version: | URL: |
---|---|---|
A. unikn (R package): | Release version | https://CRAN.R-project.org/package=unikn |
Developmentversion | https://github.com/hneth/unikn/ | |
B. Online documentation: | Releaseversion | https://hneth.github.io/unikn/ |
Development version | https://hneth.github.io/unikn/dev/ |
Vignettes
The following vignettes provide instructions and examples for usingthe unikn colors, color palettes, and functions:
Nr. | Vignette | Content |
---|---|---|
1. | Colors | Colors and color functions |
2. | Color recipes | Recipes for color-related tasks |
3. | Institutional colors | Creating color palettes for other institutions |
4. | Text | Text boxes and decorations |