From 1fe0300c8b89d20e84bfc617aabf5339edcc133c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hansj=C3=B6rg=20Neth?= Date: Tue, 16 Apr 2024 20:27:58 +0200 Subject: [PATCH] update HTML files in online documentation --- docs/articles/color_functions.html | 838 +++++++++++++++++ docs/articles/inst_colors.html | 579 ++++++++++++ docs/articles/text_decorations.html | 632 +++++++++++++ docs/dev/articles/color_functions.html | 839 ++++++++++++++++++ docs/dev/articles/institutional_colors.html | 577 ++++++++++++ .../articles/text_boxes_and_decorations.html | 632 +++++++++++++ docs/dev/reference/get_col_names.html | 125 +++ docs/reference/get_col_names.html | 125 +++ 8 files changed, 4347 insertions(+) create mode 100644 docs/articles/color_functions.html create mode 100644 docs/articles/inst_colors.html create mode 100644 docs/articles/text_decorations.html create mode 100644 docs/dev/articles/color_functions.html create mode 100644 docs/dev/articles/institutional_colors.html create mode 100644 docs/dev/articles/text_boxes_and_decorations.html create mode 100644 docs/dev/reference/get_col_names.html create mode 100644 docs/reference/get_col_names.html diff --git a/docs/articles/color_functions.html b/docs/articles/color_functions.html new file mode 100644 index 00000000..9fdecede --- /dev/null +++ b/docs/articles/color_functions.html @@ -0,0 +1,838 @@ + + + + + + + +Colors and color functions • unikn + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Colors and color functions

+

SPDS, +uni.kn

+ +

2023 07 28

+ + Source: vignettes/color_functions.Rmd + + +
+ + + + +

+unikn::

+

This vignette explains the colors, color palettes, and color-related +functions provided by the unikn package. (See the +vignettes on color recipes and institutional colors for more specialized +tasks and the vignette on text for +information on text boxes and decorations.)

+

Please install and/or load the unikn package to get +started:

+
+# install.packages('unikn')  # install unikn from CRAN client
+library('unikn')             # loads the package
+
+

Overview +

+

The unikn package provides some colors (e.g., +Seeblau) and color palettes (e.g., pal_unikn). +However, its functionality is mainly based on color-related functions +that are useful beyond the colors and palettes of this package.

+ +

The package provides two main functions for interacting with color +palettes: seecol() and usecol().

+
    +
  1. +

    seecol() is a general-purpose tool for +seeing (inspecting or visualizing) colors or color +palettes. The seecol() function takes two main +arguments:

    +
      +
    • +pal provides either one or multiple color palettes +(with a default of pal = "unikn_all");
      +
      • +
    • +n specifies the number of desired colors (with a +default of n = "all").
      • +
    +
    2. +
+

Based on the input of pal, the seecol() +function distinguishes between two modes:

+
    +
  • A. viewing the details of a single color palette +(when providing only one color palette);
    • +
  • B. comparing multiple color palettes (when providing a +keyword or list-object).
    • +
+
    +
  1. +

    usecol() allows using colors or color +palettes (e.g., when creating visualizations) without showing +its details. The usecol() function also takes arguments for +conveniently manipulating color palettes:

    +
      +
    • +pal provides either one or multiple color palettes +(with a default of pal = pal_unikn);
      +
      • +
    • +n specifies the number of desired colors (with a +default of n = "all");
      • +
    • +alpha adjusts the opacity of all colors in +pal (e.g., alpha = .50 for medium +transparency).
      • +
    +
    2. +
+

Two additional functions allow finding colors by +similarity or name:

+
    +

  1. simcol() allows finding similar +colors (given a target color, a set of candidate colors, and +some tolerance threshold(s));

    2. +

  2. grepal() allows finding colors with +particular names (i.e., colors whose names match some +pattern or regular expression);

    3. +
+

Finally, some auxiliary functions support specific +color functions:

+
    +

  • ac() adjusts color +transparency;

    • +

  • shades_of() allows creating linear color +gradients;

    • +

  • newpal() allows defining new color +palettes (as vectors or data frames with dedicated color +names); and

    • +

  • demopal() allows illustrating color +palettes for different types of visualizations.

    • +
+

The rest of this vignette provides examples of and some details on +using these functions. (See the Color +recipes vignette for more examples of solving color-related +tasks.)

+
+
+

Viewing colors and color palettes with seecol() +

+

The behavior of the seecol() function distinguishes +between two modes and depends on the input to its initial +pal argument. It either shows (A) the details of an +individual color palette, or (B) allows comparing multiple color +palettes. The next two sections will address both modes in turn.

+
+

A. Viewing details of a single color palette +

+

When the pal argument of the seecol() +function specifies a single color palette, the function plots a +more detailed view of this particular color palette:

+
+seecol(pal_unikn)  # view details of pal_unikn
+

+

The detailed overview of a color palette provides us with

+
    +
  • the color names (where available),
    +
    • +
  • their numeric indices (within the color palette),
    +
    • +
  • the HEX values for each color,
    +
    • +
  • the RGB values for each color.
    • +
+

When a color palette contains too many colors, the HEX and RGB values +are no longer printed. However, setting hex and +rgb to TRUE will force them to be shown.

+ +

Note that seecol() also returns the color palette that +is being shown. Thus, a typical workflow comprises both seeing +a particular color palette and saving it (for storing and +applying it later):

+
+my_pal <- seecol(pal_unikn_light)  # view details of AND save a color palette
+

+

Due to saving the color palette (here to my_pal) we can +later use it in a visualization:

+
+barplot(1/sqrt(1:10), col = my_pal)  # use my_pal in a plot
+

+

Note that seecol() invisibly returns the color +palette.
+Thus, the following will plot the palette pal_bordeaux +without doing anything else with it:

+
+seecol(pal_bordeaux)
+

+

but the following would both plot and assign the palette to +my_pal:

+
+my_pal <- seecol(pal_bordeaux)
+
+
+

B. Viewing and comparing multiple color palettes +

+

The second mode of seecol() is invoked by providing (a +list of) multiple color palettes to its pal +argument.
+In this case, the function allows comparing these palettes by plotting a +color vector for each palette. Some special keywords within the +unikn package denote sets of color palettes:

+
    +
  • The keywords "unikn_all", "unikn_basic", +pair_all", "pref_all" and +"grad_all" refer to University of Konstanz color +palettes.
    • +
+

Calling seecol with pal set to these +keywords allows comparing pre-defined sets of the color palettes:

+

Viewing the uni.kn color +palettes:

+
+seecol("unikn_all")  # all uni.kn color palettes
+

+
    +
  1. three basic color palettes:
    2. +
+
+seecol("unikn_basic")
+

+

Note, that pal_unikn_web and pal_unikn_ppt +are almost identical, but differ in how vibrant their colors are.

+
    +
  1. three paired color palettes:
    2. +
+
+seecol("pair_all")
+

+
    +
  1. all preferred colors from the spectrum and their respective +gradients:
    2. +
+
+seecol("pref_all")
+

+
    +
  1. only the pre-defined color gradients:
    2. +
+
+seecol("grad_all")
+

+ +

See the vignette on Institutional +colors for creating color palettes for other institutions.

+
+
+

Other seecol() arguments +

+

The seecol() function provides some aesthetic parameters +for adjusting how color palettes are plotted:

+
    +
  • +col_brd allows specifying the color of box borders (if +shown. Default: col_brd = NULL);
    +
    • +
  • +lwd_brd allows specifying the line width of box borders +(if shown. Default: lwd_brd = NULL);
    +
    • +
  • +main and sub allow replacing the default +titles with custom titles.
    • +
+

Examples:

+
+seecol("grad_all", col_brd = "black", lwd_brd = .5, main = "Color gradients (with black borders)")
+

+
+seecol(pal_seegruen, col_brd = "white", lwd_brd = 5, main = "A color palette (with white borders)")
+

+
+
+
+

Using a color palette with usecol() +

+

The usecol() function allows directly using a color +palette in a plot (i.e., without first viewing it). +usecol() corresponds to seecol() by taking the +same main arguments (pal and n). However, as +its purpose is using the colors specified by pal, +rather than plotting (or seeing) them, its +pal argument typically contains only one color palette:

+
+# Using a color palette:
+barplot(1/sqrt(1:11), col = usecol(pal_unikn))
+

+ +

Note that the seecol() and usecol() +functions are both quite permissive with respect to specifying their +pal argument: A particular color palette (e.g., +pal_seegruen) can not only be displayed by providing it (as +an object) but also by providing its name (i.e., +"pal_seegruen") or even an incomplete object name or name +(i.e., "seegruen" or seegruen). Hence, the +following expressions all yield the same result:

+
+seecol(pal_seegruen)
+seecol("pal_seegruen")
+seecol("seegruen")
+seecol(seegruen)  # issues a warning, but works
+
+
+

Customizing color palettes +

+

Both the seecol() and the usecol() +functions allow a flexible on-the-fly customization of color +palettes.

+

Specifying a value for the n argument of +seecol() an usecol() allows:

+
    +
  • specifying subsets of colors and comparing these subsets for +different palettes for n smaller than the length +of the color palette;
    +
    • +
  • extending color palettes and comparing different palettes for +n greater than the length of the color +palette.
    • +
+

Passing a vector of colors and/or color palettes allows users to +create and view their own color palettes.

+

Finally, specifying a value for alpha (in a range from 0 +to 1) allows controlling the transparency of the color palette(s), with +higher values for alpha corresponding to higher +transparency (i.e., lower opacity).

+
+

Selecting subsets +

+

Using only a subset of colors:

+
+seecol("unikn_all", n = 4)
+

+
+seecol(pal_unikn, 4)
+

+

Importantly, when using pre-defined color palettes of +unikn but a value of n that is smaller +than the length of the current color palette, usecol and +seecol select a predefined subset of colors:

+
+barplot(1/sqrt(1:2), col = usecol(pal_seeblau, n = 2))
+barplot(1/sqrt(1:3), col = usecol(pal_seeblau, n = 3))
+

+
+
+

Extending color palettes +

+

For values of n that are larger than the number of +available colors in pal, the specified color palette is +extended using ColorRampPalette:

+
+seecol("unikn_all", n = 12)
+

+

Both seecol() and usecol() allow extending +or truncating color palettes to a desired number n of +colors. For instance:

+
    +
  • Inspecting an extended version of pal_seeblau (with +n = 8 colors):
    • +
+
+seecol(pal_seeblau, n = 8)
+
    +
  • Using a truncated version of pal_bordeaux (with +n = 3 colors):
    • +
+
+barplot(1/sqrt(1:9), col = usecol(pal_bordeaux, n = 3))
+
+
+

Mixing colors and color palettes +

+

By passing a vector to pal, we can concatenate 2 color +palettes and connect them with a color (here: "white") as +the midpoint of a new color palette:

+
+seecol(pal = c(rev(pal_petrol), "white", pal_bordeaux))
+

+

We can combine a set of colors and extend this palette by specifying +an n argument that is larger than the length of the +specified palette:

+
+seecol(pal = usecol(c(Karpfenblau, Seeblau, "gold"), n = 10))
+

+

These custom palettes can easily be used in a plot. For instance, we +can define and use a subset of the pal_unikn_pair palette +as follows:

+
+my_pair <- seecol(pal_unikn_pair, n = 10)
+

+
+
+# Create data: 
+dat <- matrix(sample(5:10, size = 10, replace = TRUE), ncol = 5)
+
+# Plot in my_pair colors:
+barplot(dat, beside = TRUE, col = my_pair)
+

+

Creating linear color gradients is also supported by the +shades_of() function (see below).

+
+
+

Controlling transparency +

+

Both seecol() and usecol() accept an +alpha argument (in a range from 0 to 1) for controlling the +transparency of color palettes, with higher values for +alpha corresponding to lower transparency (i.e., higher +opacity).

+

Displaying a specific color palette at a medium +opacity/transparency:

+
+seecol(pal_unikn, alpha = 0.5)
+

+

Setting opacity for a custom color palette:

+
+four_cols <- usecol(c("steelblue", "gold", "firebrick", "forestgreen"), alpha = 2/3)
+
+seecol(four_cols, main = "Four named colors with added transparency")
+

+

Setting opacity for comparing of multiple color palettes:

+
+seecol("grad", alpha = 0.67, main = "Seeing transparent color palettes")
+

+
+
+

Creating and comparing custom palettes +

+

Suppose we want to compare a newly created color palette to existing +color palettes. To achieve this, advanced users can use the +seecol() function for displaying and comparing different +custom palettes. When provided with a list of color palettes as the +input to its pal argument, seecol() will show +a comparison of the inputs:

+
+# Define 2 palettes: 
+pal1 <- c(rev(pal_seeblau), "white", pal_bordeaux)
+pal2 <- usecol(c(Karpfenblau, Seeblau, "gold"), n = 10)
+
+# Show the my_pair palette from above, the 2 palettes just defined, and 2 pre-defined palettes:  
+seecol(list(my_pair, pal1, pal2, pal_unikn, pal_unikn_pair))
+

+

Note that unknown color palettes are named pal_\(n\), in increasing order. Palettes known to +seecol() are labeled by their respective names. Labeling +only custom palettes works by setting the pal_names +argument to a character vector of appropriate length:

+
+seecol(list(my_pair, pal1, pal2, pal_unikn, pal_unikn_pair), 
+       pal_names = c("my_pair", "blue_bord", "blue_yell"),
+       main = "Labeling custom color palettes")
+

If the pal_names argument is specified and corresponds +to the length of all color palettes, the default names of all +color palettes are overwritten by pal_names:

+
+seecol(list(my_pair, pal1, pal2, pal_unikn, pal_unikn_pair), 
+       pal_names = c("my_pair", "blue_bord", "blue_yell", "blue_black", "mix_pair"),
+       main = "Comparing and labeling custom color palettes")
+

As before, we can use lower values of n for +truncating/obtaining shorter subsets of color palettes:

+
+seecol(list(my_pair, pal1, pal2, pal_unikn, pal_unikn_pair), n = 5)
+

+

or higher values of n for extending color palettes:

+
+seecol(list(my_pair, pal1, pal2, pal_unikn, pal_unikn_pair), n = 15)
+

+
+
+
+

Finding colors +

+

Two familiar color search tasks are addressed by the +simcol() and grepal() functions:

+
    +
  • +simcol() allows searching for colors that are similar +to a given target color
    • +
  • +grepal() allows searching for colors whose names match +some pattern
    • +
+
+

Finding similar colors with simcol() +

+

Assuming that our favorite color is "deeppink", a good +question is: How can we find similar colors? Given some target color, +the simcol() function searches through a set of colors to +find and return visually similar ones:

+
+simcol("deeppink", plot = FALSE)
+#>     deeppink    deeppink2      maroon1      maroon2   violetred1   violetred2 
+#>   "deeppink"  "deeppink2"    "maroon1"    "maroon2" "violetred1" "violetred2"
+

By default, simcol() searches though all named R colors +of colors() (of the grDevices package), +but adjusting the col_candidates and tol +arguments allows for more fine-grained searches:

+
+simcol("deepskyblue", col_candidates = pal_seeblau, tol = c(50, 50, 100))
+#>   deepskyblue      seeblau3      seeblau4      seeblau5 
+#> "deepskyblue"     "#59C7EB"     "#00A9E0"     "#008ECE"
+

+
+
+

Finding color names with grepal() +

+

We often search for some particular color hue (e.g., some sort of +purple), but also know that the particular color named “purple” is +not the one we want. Instead, we would like to see all colors +that contain the keyword “purple” in its name. The grepal() +function addresses this need:

+
+grepal("purple")  # get & see 10 names of colors() with "purple" in their name
+

+
#>  [1] "mediumpurple"  "mediumpurple1" "mediumpurple2" "mediumpurple3"
+#>  [5] "mediumpurple4" "purple"        "purple1"       "purple2"      
+#>  [9] "purple3"       "purple4"
+

Note that the grepal() function allows searching color +names by regular expressions:

+
+length(grepal("gr(a|e)y", plot = FALSE))    # shades of "gray" or "grey"
+#> [1] 224
+length(grepal("^gr(a|e)y", plot = FALSE))   # shades starting with "gray" or "grey"
+#> [1] 204
+length(grepal("^gr(a|e)y$", plot = FALSE))  # shades starting and ending with "gray" or "grey"
+#> [1] 2
+

By default, grepal() searches the vector of named colors +x = colors() (of the grDevices package) +and plots its results (as a side effect). However, it also allows for +searching color palettes provided as data frames (with color names) and +for suppressing the visualization (by setting +plot = FALSE):

+
+grepal("see", pal_unikn)   # finding "see" in (the names of) pal_unikn (as df)
+

+
#>   seeblau5 seeblau4 seeblau3 seeblau2 seeblau1 seegrau1 seegrau2 seegrau3
+#> 1  #008ECE  #00A9E0  #59C7EB  #A6E1F4  #CCEEF9  #E5E5E5  #CCCCCC  #999999
+#>   seegrau4
+#> 1  #666666
+grepal("blau", pal_unikn_pref, plot = FALSE)  # finding "blau" in pal_unikn_pref
+#>   Seeblau Karpfenblau
+#> 1 #59C7EB     #3E5496
+
+
+
+

Auxiliary color functions +

+
+

Adjusting transparency with ac() +

+

The ac() function provides a flexible wrapper around the +adjustcolor() function of the grDevices +package. Its key functionality is that it allows for +vectorized col and alpha +arguments:

+
+my_cols <- c("black", "firebrick", "forestgreen", "gold", "steelblue")
+seecol(ac(my_cols, alpha = c(rep(.25, 5), rep(.75, 5))))
+

+

The name ac is an abbreviation of “adjust color”, but +also a mnemonic aid for providing “air conditioning”.

+
+
+

Creating color gradients with shades_of() +

+

We have seen that the main usecol() function allows +stretching and squeezing color palettes and thus creating complex color +gradients. An even simpler way for creating linear color gradients is +provided by the shades_of() function:

+
+seecol(shades_of(n = 5, col_1 = Karpfenblau), main = "5 shades of Karpfenblau")
+

+

Internally, shades_of() is just a convenient wrapper for +a special usecol() function. The limitation of +shades_of() is that it only allows creating bi-polar color +palettes (i.e., gradients between two colors). When the final color +col_n is unspecified, its default of “white” is used (as in +the example). By contrast, the usecol() function allows +creating color gradients between an arbitrary number of colors. Thus, +the following two expressions define the same bi-polar color +palette:

+
+pg_1 <- usecol(c("deeppink", "gold"), 5)
+pg_2 <- shades_of(5, "deeppink", "gold")
+all.equal(pg_1, pg_2)
+#> [1] TRUE
+
+seecol(pg_2, main = "A bi-polar color gradient")
+

+
+
+

Defining color palettes with newpal() +

+

Having created, combined or found all those beautiful colors, we may +wish to define a new color palette. Defining a new named color palette +allows to consistently access and apply colors (e.g., to a series of +visualizations in a report or publication). The newpal() +function makes it easy to define color palettes:

+
+col_flag <- c("#000000", "#dd0000", "#ffce00")  # source: www.schemecolor.com
+
+flag_de  <- newpal(col = col_flag,
+                   names = c("black", "red", "gold"))
+
+seecol(flag_de, main = "Defining a flag_de color palette")
+

+

By default, newpal() returns the new color palette as a +(named) vector. Setting as_df = TRUE returns a data +frame.

+
+
+

Illustrating color palettes with demopal() +

+

After choosing, creating or modifying a color palette, we usually +inspect the result with seecol(). Alternatively, we can use +the demopal() function to use a color +palette pal in a visualization. Currently, the +type argument supports the following visualizations:

+
    +
  1. “bar”: A bar plot
    2. +
  2. “curve”: A plot of normal distribution curves (with +transparency)
    3. +
  3. “mosaic”: A mosaic/table plot
    4. +
  4. “polygon”: An area/polygon plot
    5. +
  5. “scatter”: A scatter plot of points (with transparency)
    6. +
+

All types of demopal() invisibly return their (randomly +generated) data and accept some graphical arguments (e.g., +col_par and alpha), a scaling n +and a seed value (for reproducible results), as well as +main and sub arguments (for setting plot +titles). Some functions additionally accept type-specific arguments +(e.g., logical beside, horiz, and +as_prop arguments for plot type = "bar").

+
+demopal(pal = pg_2, type = 3)
+

+ +

This concludes our quick tour through the colors and color functions +of the unikn package. We hope that they enable you to +find, design, and use beautiful color palettes — and spice up your +visualizations by vivid and flamboyant colors!

+
+
+
+

Resources +

+

The following versions of unikn and corresponding +resources are currently available:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type:Version:URL:
A. unikn (R package):Release versionhttps://CRAN.R-project.org/package=unikn
 Development +versionhttps://github.com/hneth/unikn/
B. Online documentation:Release +versionhttps://hneth.github.io/unikn/
 Development versionhttps://hneth.github.io/unikn/dev/
+
+
+

Vignettes +

+

The following vignettes provide instructions and examples for using +the unikn colors, color palettes, and functions:

+ +

+unikn::

+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Nr.VignetteContent
1.ColorsColors and color functions
2.Color recipesRecipes for color-related tasks
3.Institutional +colorsCreating color palettes for other institutions
4.TextText boxes and decorations
+ +
+
+ + + +
+ + + + +
+ + + + + + + + diff --git a/docs/articles/inst_colors.html b/docs/articles/inst_colors.html new file mode 100644 index 00000000..213e8583 --- /dev/null +++ b/docs/articles/inst_colors.html @@ -0,0 +1,579 @@ + + + + + + + +Institutional colors • unikn + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Institutional colors

+

SPDS, +uni.kn

+ +

2023 08 16

+ + Source: vignettes/inst_colors.Rmd + + +
+ + + + +

+unikn::

+

The color palettes included in the unikn package are +based on the CD manual of the University of Konstanz. However, +the functionality provided by the package makes it easy and +straightforward to define and use your own colors.

+

Version 0.8.0 of unikn (released in 2023-01-06) +contained 52 additional color palettes from other institutions (mostly +universities).

+ +

As the number of color palettes has been growing beyond the scope of +this package, the color palettes from other institutions are now being +collected in a separate R package unicol.

+

Installing unicol +currently provides access to a diverse range of over 200 color +palettes from over 80 institutions.

+ +

+unicol::

+ +

The rest of this vignette explains how the color-related tools of +unikn can be used for creating new color +palettes. If you do so, please consider submitting it to be +included in future versions of the unicol +package. (For a general introduction of the +unikn colors, color palettes, and color functions, see +the vignettes on Colors and color +functions and Color recipes. The +vignette on Text boxes and +decorations provides information on plotting slides and text +elements.)

+

We install or load the unikn package to get +started:

+
+# install.packages('unikn')  # install unikn from CRAN client
+library('unikn')             # load the package
+
+

Creating new color palettes +

+

A color palette is an ordered collection of color objects. Creating +new color palettes in R is simple and only requires two steps:

+
    +

  1. Define the palette’s elementary colors as R objects.

    2. +

  2. Combine colors into a color palette.

    3. +
+

In the following, we illustrate both steps. As we will see, Step 1 +can either be omitted (when the to-be-combined colors exist as R +objects) or can be included in Step 2.

+

As an example, we will re-create the color palette of the German Max Planck Society (that +unikn exports as mpg_pal) from the color +definitions in its Corporate Design manual (available here).

+
+

1. Defining colors +

+

Before we can a create new color palette in R, its elementary colors +need to exist as R objects. (If all colors to-be-combined into a new +palette exist as R objects, we can skip this step and directly proceed +to 2. Combining colors into a palette.) Defining new +colors in R requires a basic understanding of their underlying +representation.

+

How colors are represented and perceived is a wide-ranging topic that +has fascinated scholars and practitioners for centuries. Essentially, +there are many alternative ways to analyze or synthesize colors, and the +most appropriate representational way depends on the specific context of +a particular use case (see Wikipedia: Color +model for an introduction).

+

In R, the grDevices package (included in any default +installation) provides colors and color-related functions. Although R +supports many color models (including HCL, HSV, Lab, Luv, and RGB +variants), the three most common ways of expressing colors in R are:

+
    +

  1. by R color name: R includes 657 named colors, whose names are +provided (as a character vector) by evaluating the colors() +function of grDevices.

    2. +

  2. by RGB values: Every color (or hue) is expressed by a triple of +numeric values on three dimensions that denote the additive primary +colors (red, green, blue). The range of values is either expressed on a +scale from 0 to 1, or — more typically — on a scale from 0 to 255 (i.e., +on an 8 bit scale allowing for \(2^8 = +256\) different values).

    3. +

  3. by HEX values: Every color (or hue) is expressed by a character +string (with the prefix #), followed by a triple of +hexadecimal values (each ranging from 00 +to FF) that correspond to the triple of decimal RGB values +(in the range from 0 to 255).

    4. +
+

Importantly, the same color (or hue) can be denoted by its +name, its RGB values, and its HEX values. Thus, the three different +systems (i.e., color name, RGB values, or HEX values) can be +alternative representations of the same object. However, just +as the properties of an alphabet or numeral notation system constraints +the words or numbers that can be expressed by it, the universe of +possible colors is limited by their representation. For instance, +whereas the RGB and HEX systems usually distinguish between more than +16 million (i.e., \((2^8)^3 = 256^3 = +16.777.216\)) possible colors, only a limited number of them are +named. Similarly, when multiple names refer to the same triple of RGB or +HEX values, they denote the same color.1

+ + +

An example helps clarifying these abstract terms. When viewing an +existing color or color palette with the seecol() function +of unikn, the name, HEX and RGB values of the +individual colors are being shown. For instance, the following color +palette mpg_pal provides the colors of the Max Planck Society:

+

+

As the middle color of mpg_pal is one of the 657 named +colors of colors(), R will recognize it as a color when we +type its name (as a character object "white") in a context +that expects color inputs. However, the two other colors of +mpg_pal have specifically been defined by the Max Planck Society and thus are +not pre-defined colors of R (i.e., not contained in +colors()). To use such colors in R, we first need to define +them as color objects.

+ +

So how can we define new colors in R? Most institutions will provide +definitions of their corporate colors or instructions how they can be +defined in some standard color system. Unfortunately, some definitions +(such as those using the subtractive CMYK model) are aimed at printing +(as opposed to computer screens) and other standards (such as numeric +PANTONE™ PMS codes) are proprietary. But as most institutions have an +interest in widely disseminating their colors, they typically include +translations or approximations for alternative color models in their +definitions.

+

+MPG

+

The Max Planck Society defines +two main colors in its CD manual (available here):

+
    +

  • A dark shade of green is defined as Pantone 328, and approximated +by CMYK 100/0/57/30 or RGB 17/102/86.

    • +

  • A light shade of grey is Pantone 427, and approximated by +CMYK 0/0/6/15 or RGB 221/222/214.

    • +
+

In the following, we will first use the RGB values to define both +colors (as these are provided in the definition). However, we then show +that we alternatively could have used the colors’ HEX values (had they +been provided) to define the same color objects.

+
+

Defining colors from their RGB values +

+

As our two colors of interest are given in RGB values, we can use the +rgb() function of the grDevices package to +define corresponding objects:

+
+mpg_green <- grDevices::rgb( 17, 102,  86, maxColorValue = 255)
+mpg_grey  <- grDevices::rgb(221, 222, 214, maxColorValue = 255)
+

The first three arguments specify values on the red, +green, and blue dimension, respectively. +Importantly, the values must be in the range \([0, max]\), where \(max\) is provided by +maxColorValue = 255. Whereas the sRGB standard expresses +all values in a normalized range of \([0, +1]\), most color definitions use the traditional 8-bit +representation that distinguish between \(2^8 += 256\) levels in the range \([0, +255]\). The rgb() function additionally allows for +adding names and a transparency level alpha, +but as we can modify these aspects later, we do not need to use them at +this point.

+

What do we obtain when we evaluate our new color objects? Let’s +see:

+
+mpg_green
+#> [1] "#116656"
+mpg_grey
+#> [1] "#DDDED6"
+

When evaluating an object created by rgb(), R returns a +character sequence of the form "#rrggbb". In this string, +the sequence rrggbb expresses the three RGB values (for the +red, green, and blue dimension, +respectively) in hexadecimal (HEX) notation (in the range \([0, 255]\)). In HEX notation, the ten +numeral symbols (i.e., the digits from 0 to 9) or the decimal system are +extended by the first six letters of the alphabet (i.e., A to F) to turn +our familiar base-10 notation into an analogous place-value notation +with a base of 16. Thus, the HEX values of "#116656" is +merely a more compact way of expressing

+
    +
  • +red: \(1 \cdot 16 + 1 = +17\) +
    • +
  • +green: \(6 \cdot 16 + 6 = +102\) +
    • +
  • +blue: \(5 \cdot 16 + 6 = +86\) +
    • +
+

Thus, the HEX values "#116656" provide an alternative +way of expressing the RGB values 17/102/86 — and both refer to the color +“MPG green” (shown as mpg_pal[1] above).

+
+
+

Defining colors from their HEX values +

+

The equivalence of the RGB and HEX notations can be illustrated by +defining the same colors a second time, but this time specifying their +HEX values (returned above):

+
+mpg_green_2 <- "#116656"
+mpg_grey_2  <- "#DDDED6"
+

If both definitions really yield identical R objects, the following +checks must evaluate to TRUE:

+
+all.equal(mpg_green, mpg_green_2)
+#> [1] TRUE
+all.equal(mpg_grey,  mpg_grey_2)
+#> [1] TRUE
+

Thus, we can define colors from both their RGB or HEX values — and +the two notations are really just two alternative ways of representing +the same colors.

+
+
+
+

2. Combining colors into a palette +

+

Having defined two new colors, we can easily combine them into a new +color palette. A color palette is simply a sequence of colors +that are stored in some sequential data structure. The two simplest data +structures in R that are suited for this purpose are vectors or data +frames. Thus, the following two expressions both define valid color +palettes:

+
+c(mpg_green, mpg_grey)
+#> [1] "#116656" "#DDDED6"
+data.frame(mpg_green, mpg_grey)
+#>   mpg_green mpg_grey
+#> 1   #116656  #DDDED6
+

As it often is easier to remember and access colors by their names, +it usually makes sense to name the elements of a color palette (e.g., by +using the name() function).

+ +

The newpal() function of unikn provides +a convenient wrapper for defining color palettes. Its main argument +col uses a vector of color objects that make up the new +palette, whereas names and as_df allow +specifying color names and switching between returning the new palette +as a vector or data base.
+Importantly, the color objects of col can be provided as +RGB values, as R color names, or as HEX values:

+
+mpg_pal_3 <- newpal(col = c(rgb( 17, 102,  86, maxColorValue = 255), "white", "#DDDED6"),
+                    names = c("MPG green", "white", "MPG grey"),
+                    as_df = FALSE)
+

The new color palette mpg_pal_3 contains the three basic +colors of mpg_pal (shown above):

+
+seecol(mpg_pal_3, 
+       main = "My new color palette", col_brd = "black", lwd_brd = .5)
+

+

The 5-color palette provided as mpg_pal includes two +intermediate colors (at positions mpg_pal[2] and +mpg_pal[4]) that are extrapolated by mixing the two main +MPG colors with “white” in a balanced (50:50) fashion. The +usecol() function of unikn automatically +performs these extrapolations when extending a 3-element color palette +(e.g., mpg_pal_3) to n = 5 colors:

+
+my_mpg_pal <- usecol(mpg_pal_3, n = 5)
+

The resulting color palette my_mpg_pal recreates the +colors of the unikn color palette mpg_pal +(shown above):

+
+seecol(my_mpg_pal, main = "My new MPG color palette", 
+       col_brd = "black", lwd_brd = .5)
+

+

Technically, the two color palettes differ in some names and the way +in which its middle color (“white”) was specified (by its R color name +or HEX values). However, when using col2rgb() for +converting both palettes into their RGB values, we see that they contain +the same colors:

+
+all.equal(col2rgb(mpg_pal), col2rgb(my_mpg_pal), check.attributes = FALSE)
+#> [1] "Numeric: lengths (9, 15) differ"
+

This concludes our illustration of defining a new colors and color +palettes.

+
+
+
+

Comparing color palettes +

+

Once a new palette has been defined (and is available in your current +R environment), the seecol() and usecol() +functions allow comparing, scaling, and using them in the same fashion +as the native unikn color palettes:

+
+# Scaled palettes: 
+seecol(list(mpg_pal, pal_unikn), n = 7,
+       pal_names = c("Max Planck", "Uni Konstanz"),
+       main = "Comparing scaled color palettes")
+

+

See the vignette on Color recipes +for additional examples of using unikn functions for +solving color-related tasks.

+ +
+
+

Call for contributions +

+

We are still expanding the range of color palettes from other +institutions in a dedicated R package unicol.

+

Collecting color palettes

+ +

+unicol::

+
    +
  • Are you using the unikn color functions to create +your own color palettes?
    • +
+

If so, please let us know (e.g., by posting on this +GitHub +issue)!

+

We collect color palettes from other institutions to make them +available to R users in future versions of unicol.

+

To enable us to verify and provide credit to your contributions, +please send us the following information:

+
    +
  1. your code (e.g., the newpal() command creating your +color palette),
    +
    2. +
  2. your reference or source information (e.g., some URL with color +definitions),
    +
    3. +
  3. your name and some contact information (e.g., an Email +address).
    4. +
+

We’re looking forward to your inputs and contributions (at this GitHub issue)!

+
+
+

Resources +

+

The following versions of unikn and corresponding +resources are currently available:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type:Version:URL:
A. unikn (R package):Release versionhttps://CRAN.R-project.org/package=unikn
 Development +versionhttps://github.com/hneth/unikn/
B. Online documentation:Release +versionhttps://hneth.github.io/unikn/
 Development versionhttps://hneth.github.io/unikn/dev/
+
+
+

Vignettes +

+

The following vignettes provide instructions and examples for using +the unikn colors, color palettes, and functions:

+ +

+unikn::

+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Nr.VignetteContent
1.ColorsColors and color functions
2.Color recipesRecipes for color-related tasks
3.Institutional +colorsCreating color palettes for other institutions
4.TextText boxes and decorations
+ +
+
+
+
    +

  1. Strictly speaking, different shades of a given color can +be further distinguished by different opacity or +transparency levels (typically denoted by an alpha +value). However, the visual appearance of a transparent color can be +mimicked by mixing the color with the background color (usually +“white”). Hence, transparent shades of a color are usually not counted +as different colors.↩︎

    2. +
+
+
+ + + +
+ + + + +
+ + + + + + + + diff --git a/docs/articles/text_decorations.html b/docs/articles/text_decorations.html new file mode 100644 index 00000000..dcf2d4c8 --- /dev/null +++ b/docs/articles/text_decorations.html @@ -0,0 +1,632 @@ + + + + + + + +Text boxes and decorations • unikn + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Text boxes and decorations

+

SPDS, +uni.kn

+ +

2023 01 01

+ + Source: vignettes/text_decorations.Rmd + + +
+ + + + +

+unikn::

+

This vignette explains the unikn functions for +plotting graphical elements and text decorations. (See the vignette on +colors for general information on +colors, color palettes, and corresponding functions, or the more +specialized vignettes on color recipes +and institutional colors.)

+

Please install and/or load the unikn package to get +started:

+
+# install.packages('unikn')  # install unikn from CRAN client
+library('unikn')             # loads the package
+
+

Overview +

+

Beyond providing support for colors, unikn provides +functions for plotting graphical elements (like boxes) and text +decorations (with colored backgrounds or underlining). Before +illustrating these functions, please note some caveats:

+
    +

  • Plotting text (i.e., graphically rendering characters) is rarely +a 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, or +scraped). Hence, the following functions should only be used when no +better solutions are available (e.g., for adding text to graphs, or for +obstructing automatic text recognition).

    • +

  • Like all other templates, our renderings are subject to +constraints and limitations. For instance, as any standard installation +of R lacks the prescribed +“Theinhardt” fonts, we only mimic the official design specifications (in +Arial, sans serif).

    • +
+

That said, digital decorations can be useful to emphasize or +structure information, provided that they can be produced easily and +flexibly. The unikn package helps preventing common +mistakes by novices (e.g., boxes or lines extending beyond text, or +step-functions in multi-line headings) and can be customized and +improved by expert users. Hence, we hope that the following functions +are useful for plotting graphical elements (e.g., boxes, logos, etc.) +and help you achieve a uniform look when styling presentations or +visualizations.

+

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 an +existing plot, we must first create a plot to which we can add text. +unikn provides 2 basic functions for creating new +plots:

+
    +
  1. +slide plots an empty canvass (a rectangular box or +frame);
    2. +
  2. +xbox plots a colored box with an X in its top right +corner.
    3. +
+

Here are both commands with their default settings:

+
+slide()  # plot default slide
+

+
+xbox()  # plot default xbox
+

+

Both functions accept additional arguments to customize their +appearance.

+
+

Colors +

+

The background and border colors of slides can be changed by setting +their 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 the +col argument:

+
+xbox(col = Pinky)  # set background color of xbox
+

+
+
+

Dimensions +

+

By default, both slide and xbox fill the +entire plotting region (i.e., all margins are set to 0).

+

The width of a slide is set to 4/3 of its height (of 1). To change +this default, use the dim argument for specifying the +slide’s x- and y-dimensions, respectively:

+
+slide(dim = c(3, 1))  # a slide 3x wider than high
+

+

Note that changes in slide dimensions are invisible when viewing +images interactively, as R automatically scales images to the size of +the canvass. They mostly affect the relation between metrics when adding +elements to an object.

+

Similarly, an xbox has the default dimensions of a unit square (i.e., +dim = c(1, 1)). To change this default, use the +dim argument for specifying the xbox’s x- and +y-dimensions, respectively:

+
+xbox(col = Petrol, dim  = c(1, 2))  # an xbox 2 times higher than wide
+

+

The two strokes of the X (in the top right corner) are orthogonal +when viewing the xbox at the aspect ratio indicated by +dim (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 to +be distorted. Hence, viewing and printing plots at the desired aspect +ratio helps when creating an xbox.

+
+
+
+

Plotting styled text +

+

There are three main functions for plotting text with +decorations:

+
    +
  • +mark() allows highlighting text with colored background +boxes;
    • +
  • +uline() allows underlining text with colored +lines;
    • +
  • +post() allows posting text in rectangular +xbox elements.
    • +
+

In addition, there are 2 auxiliary functions:

+
    +
  • +headline() allows plotting headlines with colored +background boxes;
    • +
  • +url_unikn() allows formatting URLs the uni.kn way.
    • +
+

The following sections illustrate the functions and their main +options in turn.

+
+

Mark text +

+

The mark() function allows highlighting text by plotting +it with colored background boxes (to provide the functionality of +“Markieren”):

+

+

By default, mark() assumes that we want to add +highlighted text to an existing plot. The text labels to be added are +provided (as a character vector) by the labels argument, +their coordinates as the corresponding x and y +arguments. Various text decorations (i.e., text and background colors, +text sizes, and font types) can be set by specifying additional +arguments (i.e., col, col_bg, +cex, and font, respectively):

+
+# Some pre-existing plot: 
+n <- 20
+set.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 the +new_plot argument to either "blank" +or "slide" will generate a new default plot (by calling the +slide() 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 and +y coordinates for all text elements in labels, +the calls above defined an initial coordinate and used a numeric +y_layout argument to fix the distance between consecutive +text labels (to a value of .03).

+

As an alternative to numeric coordinates and position values, +x_layout and y_layout also accept some special +values (as character strings):

+
    +
  1. +

    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 first +label or the middle), and
      +
      • +
    • +x_layout = "right" right-justifies labels (on the first +label or the middle).
      • +
    +
    2. +
  2. +

    y_layout accepts:

    +
      +
    • +y_layout = "even" for an even distribution of labels +across the available y-space, and
      +
      • +
    • +y_layout = "flush" to omit space between adjacent +labels (as in y_layout = 0).
      • +
    +
    3. +
+

Thus, the position and orientation of the text labels can be +controlled by using the x_layout and y_layout +options:

+ + +

+

See ?mark for details.

+
+
+

Underline text +

+

The uline() function allows emphasizing text by plotting +it with colored underlining (to provide the functionality of +“Unterstreichen”):

+

+

As with mark() above, the uline() command +distinguishes between creating a new plot (by setting +new_plot to either "blank" or +“slide”) or adding to a pre-existing plot (by using the +default 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 plot
+uline(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 text +properties and decorations (col, col_bg, +cex, and font) work as they do for +mark(). For instance, shorter vectors are recycled to match +the 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 by +using the x_layout and y_layout options:

+ + +
+
+

Post text +

+

The post() function allows adding text to a +rectangular xbox (to provide the functionality of +“Merken”):

+

+

By default, post() assumes a pre-existing +xbox to which the text elements of labels are +to be added.
+For square boxes, setting new_plot to "xbox" +creates a new xbox with its default dimensions of +dim = c(1, 1).
+By adjusting its color and text arguments, post() allows +creating 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 images +providing 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 be +controlled by using the x_layout and y_layout +options:

+ + +

+
+
+

Headings +

+

The heading() function makes it easy to create +recognizable headings:

+

+

By default, the function creates a new slide (i.e., +new_plot = "slide") and positions the text elements +of labels on its left edge (i.e., x = 0, +y = .8 and y_layout = "flush"). When headings +violate 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 the +CD manual):

+
+# 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() selects +colors that are appropriate for the number of elements in +labels (i.e., shades of Seeblau for +col_bg = "default"). However, default colors can be +overwritten by setting the col and col_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) concerns +the rendering of URLs, in which typical web patterns (like “http” or +“www”) are to be omitted and replaced by a typographical dash (which is +longer than a hyphen). The url_unikn utility function +allows formatting URLs the uni.kn way:

+
+my_url <- url_unikn("https://www.uni-konstanz.de/")  # input URL
+my_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 corresponding +resources are currently available:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type:Version:URL:
A. unikn (R package):Release versionhttps://CRAN.R-project.org/package=unikn
 Development +versionhttps://github.com/hneth/unikn/
B. Online documentation:Release +versionhttps://hneth.github.io/unikn/
 Development versionhttps://hneth.github.io/unikn/dev/
+
+
+

Vignettes +

+

The following vignettes provide instructions and examples for using +the unikn colors, color palettes, and functions:

+ +

+unikn::

+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Nr.VignetteContent
1.ColorsColors and color functions
2.Color recipesRecipes for color-related tasks
3.Institutional +colorsCreating color palettes for other institutions
4.TextText boxes and decorations
+ +
+
+ + + +
+ + + + +
+ + + + + + + + diff --git a/docs/dev/articles/color_functions.html b/docs/dev/articles/color_functions.html new file mode 100644 index 00000000..a2d3d576 --- /dev/null +++ b/docs/dev/articles/color_functions.html @@ -0,0 +1,839 @@ + + + + + + + +Colors and color functions • unikn + + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Colors and color functions

+

SPDS, +uni.kn

+ +

2023 07 28

+ + Source: vignettes/color_functions.Rmd + + +
+ + + + +

+unikn::

+

This vignette explains the colors, color palettes, and color-related +functions provided by the unikn package. (See the +vignettes on color recipes and institutional colors for more specialized +tasks and the vignette on text for information +on text boxes and decorations.)

+

Please install and/or load the unikn package to get +started:

+
+# install.packages('unikn')  # install unikn from CRAN client
+library('unikn')             # loads the package
+
+

Overview +

+

The unikn package provides some colors (e.g., +Seeblau) and color palettes (e.g., pal_unikn). +However, its functionality is mainly based on color-related functions +that are useful beyond the colors and palettes of this package.

+ +

The package provides two main functions for interacting with color +palettes: seecol() and usecol().

+
    +
  1. +

    seecol() is a general-purpose tool for +seeing (inspecting or visualizing) colors or color +palettes. The seecol() function takes two main +arguments:

    +
      +
    • +pal provides either one or multiple color palettes +(with a default of pal = "unikn_all");
      +
      • +
    • +n specifies the number of desired colors (with a +default of n = "all").
      • +
    +
    2. +
+

Based on the input of pal, the seecol() +function distinguishes between two modes:

+
    +
  • A. viewing the details of a single color palette +(when providing only one color palette);
    • +
  • B. comparing multiple color palettes (when providing a +keyword or list-object).
    • +
+
    +
  1. +

    usecol() allows using colors or color +palettes (e.g., when creating visualizations) without showing +its details. The usecol() function also takes arguments for +conveniently manipulating color palettes:

    +
      +
    • +pal provides either one or multiple color palettes +(with a default of pal = pal_unikn);
      +
      • +
    • +n specifies the number of desired colors (with a +default of n = "all");
      • +
    • +alpha adjusts the opacity of all colors in +pal (e.g., alpha = .50 for medium +transparency).
      • +
    +
    2. +
+

Two additional functions allow finding colors by +similarity or name:

+
    +

  1. simcol() allows finding similar +colors (given a target color, a set of candidate colors, and +some tolerance threshold(s));

    2. +

  2. grepal() allows finding colors with +particular names (i.e., colors whose names match some +pattern or regular expression);

    3. +
+

Finally, some auxiliary functions support specific +color functions:

+
    +

  • ac() adjusts color +transparency;

    • +

  • shades_of() allows creating linear color +gradients;

    • +

  • newpal() allows defining new color +palettes (as vectors or data frames with dedicated color +names); and

    • +

  • demopal() allows illustrating color +palettes for different types of visualizations.

    • +
+

The rest of this vignette provides examples of and some details on +using these functions. (See the Color +recipes vignette for more examples of solving color-related +tasks.)

+
+
+

Viewing colors and color palettes with seecol() +

+

The behavior of the seecol() function distinguishes +between two modes and depends on the input to its initial +pal argument. It either shows (A) the details of an +individual color palette, or (B) allows comparing multiple color +palettes. The next two sections will address both modes in turn.

+
+

A. Viewing details of a single color palette +

+

When the pal argument of the seecol() +function specifies a single color palette, the function plots a +more detailed view of this particular color palette:

+
+seecol(pal_unikn)  # view details of pal_unikn
+

+

The detailed overview of a color palette provides us with

+
    +
  • the color names (where available),
    +
    • +
  • their numeric indices (within the color palette),
    +
    • +
  • the HEX values for each color,
    +
    • +
  • the RGB values for each color.
    • +
+

When a color palette contains too many colors, the HEX and RGB values +are no longer printed. However, setting hex and +rgb to TRUE will force them to be shown.

+ +

Note that seecol() also returns the color palette that +is being shown. Thus, a typical workflow comprises both seeing +a particular color palette and saving it (for storing and +applying it later):

+
+my_pal <- seecol(pal_unikn_light)  # view details of AND save a color palette
+

+

Due to saving the color palette (here to my_pal) we can +later use it in a visualization:

+
+barplot(1/sqrt(1:10), col = my_pal)  # use my_pal in a plot
+

+

Note that seecol() invisibly returns the color +palette.
+Thus, the following will plot the palette pal_bordeaux +without doing anything else with it:

+
+seecol(pal_bordeaux)
+

+

but the following would both plot and assign the palette to +my_pal:

+
+my_pal <- seecol(pal_bordeaux)
+
+
+

B. Viewing and comparing multiple color palettes +

+

The second mode of seecol() is invoked by providing (a +list of) multiple color palettes to its pal +argument.
+In this case, the function allows comparing these palettes by plotting a +color vector for each palette. Some special keywords within the +unikn package denote sets of color palettes:

+
    +
  • The keywords "unikn_all", "unikn_basic", +pair_all", "pref_all" and +"grad_all" refer to University of Konstanz color +palettes.
    • +
+

Calling seecol with pal set to these +keywords allows comparing pre-defined sets of the color palettes:

+

Viewing the uni.kn color +palettes:

+
+seecol("unikn_all")  # all uni.kn color palettes
+

+
    +
  1. three basic color palettes:
    2. +
+
+seecol("unikn_basic")
+

+

Note, that pal_unikn_web and pal_unikn_ppt +are almost identical, but differ in how vibrant their colors are.

+
    +
  1. three paired color palettes:
    2. +
+
+seecol("pair_all")
+

+
    +
  1. all preferred colors from the spectrum and their respective +gradients:
    2. +
+
+seecol("pref_all")
+

+
    +
  1. only the pre-defined color gradients:
    2. +
+
+seecol("grad_all")
+

+ +

See the vignette on Institutional +colors for creating color palettes for other institutions.

+
+
+

Other seecol() arguments +

+

The seecol() function provides some aesthetic parameters +for adjusting how color palettes are plotted:

+
    +
  • +col_brd allows specifying the color of box borders (if +shown. Default: col_brd = NULL);
    +
    • +
  • +lwd_brd allows specifying the line width of box borders +(if shown. Default: lwd_brd = NULL);
    +
    • +
  • +main and sub allow replacing the default +titles with custom titles.
    • +
+

Examples:

+
+seecol("grad_all", col_brd = "black", lwd_brd = .5, main = "Color gradients (with black borders)")
+

+
+seecol(pal_seegruen, col_brd = "white", lwd_brd = 5, main = "A color palette (with white borders)")
+

+
+
+
+

Using a color palette with usecol() +

+

The usecol() function allows directly using a color +palette in a plot (i.e., without first viewing it). +usecol() corresponds to seecol() by taking the +same main arguments (pal and n). However, as +its purpose is using the colors specified by pal, +rather than plotting (or seeing) them, its +pal argument typically contains only one color palette:

+
+# Using a color palette:
+barplot(1/sqrt(1:11), col = usecol(pal_unikn))
+

+ +

Note that the seecol() and usecol() +functions are both quite permissive with respect to specifying their +pal argument: A particular color palette (e.g., +pal_seegruen) can not only be displayed by providing it (as +an object) but also by providing its name (i.e., +"pal_seegruen") or even an incomplete object name or name +(i.e., "seegruen" or seegruen). Hence, the +following expressions all yield the same result:

+
+seecol(pal_seegruen)
+seecol("pal_seegruen")
+seecol("seegruen")
+seecol(seegruen)  # issues a warning, but works
+
+
+

Customizing color palettes +

+

Both the seecol() and the usecol() +functions allow a flexible on-the-fly customization of color +palettes.

+

Specifying a value for the n argument of +seecol() an usecol() allows:

+
    +
  • specifying subsets of colors and comparing these subsets for +different palettes for n smaller than the length +of the color palette;
    +
    • +
  • extending color palettes and comparing different palettes for +n greater than the length of the color +palette.
    • +
+

Passing a vector of colors and/or color palettes allows users to +create and view their own color palettes.

+

Finally, specifying a value for alpha (in a range from 0 +to 1) allows controlling the transparency of the color palette(s), with +higher values for alpha corresponding to higher +transparency (i.e., lower opacity).

+
+

Selecting subsets +

+

Using only a subset of colors:

+
+seecol("unikn_all", n = 4)
+

+
+seecol(pal_unikn, 4)
+

+

Importantly, when using pre-defined color palettes of +unikn but a value of n that is smaller +than the length of the current color palette, usecol and +seecol select a predefined subset of colors:

+
+barplot(1/sqrt(1:2), col = usecol(pal_seeblau, n = 2))
+barplot(1/sqrt(1:3), col = usecol(pal_seeblau, n = 3))
+

+
+
+

Extending color palettes +

+

For values of n that are larger than the number of +available colors in pal, the specified color palette is +extended using ColorRampPalette:

+
+seecol("unikn_all", n = 12)
+

+

Both seecol() and usecol() allow extending +or truncating color palettes to a desired number n of +colors. For instance:

+
    +
  • Inspecting an extended version of pal_seeblau (with +n = 8 colors):
    • +
+
+seecol(pal_seeblau, n = 8)
+
    +
  • Using a truncated version of pal_bordeaux (with +n = 3 colors):
    • +
+
+barplot(1/sqrt(1:9), col = usecol(pal_bordeaux, n = 3))
+
+
+

Mixing colors and color palettes +

+

By passing a vector to pal, we can concatenate 2 color +palettes and connect them with a color (here: "white") as +the midpoint of a new color palette:

+
+seecol(pal = c(rev(pal_petrol), "white", pal_bordeaux))
+

+

We can combine a set of colors and extend this palette by specifying +an n argument that is larger than the length of the +specified palette:

+
+seecol(pal = usecol(c(Karpfenblau, Seeblau, "gold"), n = 10))
+

+

These custom palettes can easily be used in a plot. For instance, we +can define and use a subset of the pal_unikn_pair palette +as follows:

+
+my_pair <- seecol(pal_unikn_pair, n = 10)
+

+
+
+# Create data: 
+dat <- matrix(sample(5:10, size = 10, replace = TRUE), ncol = 5)
+
+# Plot in my_pair colors:
+barplot(dat, beside = TRUE, col = my_pair)
+

+

Creating linear color gradients is also supported by the +shades_of() function (see below).

+
+
+

Controlling transparency +

+

Both seecol() and usecol() accept an +alpha argument (in a range from 0 to 1) for controlling the +transparency of color palettes, with higher values for +alpha corresponding to lower transparency (i.e., higher +opacity).

+

Displaying a specific color palette at a medium +opacity/transparency:

+
+seecol(pal_unikn, alpha = 0.5)
+

+

Setting opacity for a custom color palette:

+
+four_cols <- usecol(c("steelblue", "gold", "firebrick", "forestgreen"), alpha = 2/3)
+
+seecol(four_cols, main = "Four named colors with added transparency")
+

+

Setting opacity for comparing of multiple color palettes:

+
+seecol("grad", alpha = 0.67, main = "Seeing color palettes with added transparency")
+

+
+
+

Creating and comparing custom palettes +

+

Suppose we want to compare a newly created color palette to existing +color palettes. To achieve this, advanced users can use the +seecol() function for displaying and comparing different +custom palettes. When provided with a list of color palettes as the +input to its pal argument, seecol() will show +a comparison of the inputs:

+
+# Define 2 palettes: 
+pal1 <- c(rev(pal_seeblau), "white", pal_bordeaux)
+pal2 <- usecol(c(Karpfenblau, Seeblau, "gold"), n = 10)
+
+# Show the my_pair palette from above, the 2 palettes just defined, and 2 pre-defined palettes:  
+seecol(list(my_pair, pal1, pal2, pal_unikn, pal_unikn_pair))
+

+

Note that unknown color palettes are named pal_\(n\), in increasing order. Palettes known to +seecol() are labeled by their respective names. Labeling +only custom palettes works by setting the pal_names +argument to a character vector of appropriate length:

+
+seecol(list(my_pair, pal1, pal2, pal_unikn, pal_unikn_pair), 
+       pal_names = c("my_pair", "blue_bord", "blue_yell"),
+       main = "Labeling custom color palettes")
+

If the pal_names argument is specified and corresponds +to the length of all color palettes, the default names of all +color palettes are overwritten by pal_names:

+
+seecol(list(my_pair, pal1, pal2, pal_unikn, pal_unikn_pair), 
+       pal_names = c("my_pair", "blue_bord", "blue_yell", "blue_black", "mix_pair"),
+       main = "Comparing and labeling custom color palettes")
+

As before, we can use lower values of n for +truncating/obtaining shorter subsets of color palettes:

+
+seecol(list(my_pair, pal1, pal2, pal_unikn, pal_unikn_pair), n = 5)
+

+

or higher values of n for extending color palettes:

+
+seecol(list(my_pair, pal1, pal2, pal_unikn, pal_unikn_pair), n = 15)
+

+
+
+
+

Finding colors +

+

Two familiar color search tasks are addressed by the +simcol() and grepal() functions:

+
    +
  • +simcol() allows searching for colors that are similar +to a given target color
    • +
  • +grepal() allows searching for colors whose names match +some pattern
    • +
+
+

Finding similar colors with simcol() +

+

Assuming that our favorite color is "deeppink", a good +question is: How can we find similar colors? Given some target color, +the simcol() function searches through a set of colors to +find and return visually similar ones:

+
+simcol("deeppink", plot = FALSE)
+#>     deeppink    deeppink2      maroon1      maroon2   violetred1   violetred2 
+#>   "deeppink"  "deeppink2"    "maroon1"    "maroon2" "violetred1" "violetred2"
+

By default, simcol() searches though all named R colors +of colors() (of the grDevices package), +but adjusting the col_candidates and tol +arguments allows for more fine-grained searches:

+
+simcol("deepskyblue", col_candidates = pal_seeblau, tol = c(50, 50, 100))
+#>   deepskyblue      seeblau3      seeblau4      seeblau5 
+#> "deepskyblue"     "#59C7EB"     "#00A9E0"     "#008ECE"
+

+
+
+

Finding color names with grepal() +

+

We often search for some particular color hue (e.g., some sort of +purple), but also know that the particular color named “purple” is +not the one we want. Instead, we would like to see all colors +that contain the keyword “purple” in its name. The grepal() +function addresses this need:

+
+grepal("purple")  # get & see 10 names of colors() with "purple" in their name
+

+
#>  [1] "mediumpurple"  "mediumpurple1" "mediumpurple2" "mediumpurple3"
+#>  [5] "mediumpurple4" "purple"        "purple1"       "purple2"      
+#>  [9] "purple3"       "purple4"
+

Note that the grepal() function allows searching color +names by regular expressions:

+
+length(grepal("gr(a|e)y", plot = FALSE))    # shades of "gray" or "grey"
+#> [1] 224
+length(grepal("^gr(a|e)y", plot = FALSE))   # shades starting with "gray" or "grey"
+#> [1] 204
+length(grepal("^gr(a|e)y$", plot = FALSE))  # shades starting and ending with "gray" or "grey"
+#> [1] 2
+

By default, grepal() searches the vector of named colors +x = colors() (of the grDevices package) +and plots its results (as a side effect). However, it also allows for +searching color palettes provided as data frames (with color names) and +for suppressing the visualization (by setting +plot = FALSE):

+
+grepal("see", pal_unikn)   # finding "see" in (the names of) pal_unikn (as df)
+

+
#>   seeblau5 seeblau4 seeblau3 seeblau2 seeblau1 seegrau1 seegrau2 seegrau3
+#> 1  #008ECE  #00A9E0  #59C7EB  #A6E1F4  #CCEEF9  #E5E5E5  #CCCCCC  #999999
+#>   seegrau4
+#> 1  #666666
+grepal("blau", pal_unikn_pref, plot = FALSE)  # finding "blau" in pal_unikn_pref
+#>   Seeblau Karpfenblau
+#> 1 #59C7EB     #3E5496
+
+
+
+

Auxiliary color functions +

+
+

Adjusting transparency with ac() +

+

The ac() function provides a flexible wrapper around the +adjustcolor() function of the grDevices +package. Its key functionality is that it allows for +vectorized col and alpha +arguments:

+
+my_cols <- c("black", "firebrick", "forestgreen", "gold", "steelblue")
+seecol(ac(my_cols, alpha = c(rep(.25, 5), rep(.75, 5))))
+

+

The name ac is an abbreviation of “adjust color”, but +also a mnemonic aid for providing “air conditioning”.

+
+
+

Creating color gradients with shades_of() +

+

We have seen that the main usecol() function allows +stretching and squeezing color palettes and thus creating complex color +gradients. An even simpler way for creating linear color gradients is +provided by the shades_of() function:

+
+seecol(shades_of(n = 5, col_1 = Karpfenblau), main = "5 shades of Karpfenblau")
+

+

Internally, shades_of() is just a convenient wrapper for +a special usecol() function. The limitation of +shades_of() is that it only allows creating bi-polar color +palettes (i.e., gradients between two colors). When the final color +col_n is unspecified, its default of “white” is used (as in +the example). By contrast, the usecol() function allows +creating color gradients between an arbitrary number of colors. Thus, +the following two expressions define the same bi-polar color +palette:

+
+pg_1 <- usecol(c("deeppink", "gold"), 5)
+pg_2 <- shades_of(5, "deeppink", "gold")
+all.equal(pg_1, pg_2)
+#> [1] TRUE
+
+seecol(pg_2, main = "A bi-polar color gradient")
+

+
+
+

Defining color palettes with newpal() +

+

Having created, combined or found all those beautiful colors, we may +wish to define a new color palette. Defining a new named color palette +allows to consistently access and apply colors (e.g., to a series of +visualizations in a report or publication). The newpal() +function makes it easy to define color palettes:

+
+col_flag <- c("#000000", "#dd0000", "#ffce00")  # source: www.schemecolor.com
+
+flag_de  <- newpal(col = col_flag,
+                   names = c("black", "red", "gold"))
+
+seecol(flag_de, main = "Defining a flag_de color palette")
+

+

By default, newpal() returns the new color palette as a +(named) vector. Setting as_df = TRUE returns a data +frame.

+
+
+

Illustrating color palettes with demopal() +

+

After choosing, creating or modifying a color palette, we usually +inspect the result with seecol(). Alternatively, we can use +the demopal() function to use a color +palette pal in a visualization. Currently, the +type argument supports the following visualizations:

+
    +
  1. “bar”: A bar plot
    2. +
  2. “curve”: A plot of normal distribution curves (with +transparency)
    3. +
  3. “mosaic”: A mosaic/table plot
    4. +
  4. “polygon”: An area/polygon plot
    5. +
  5. “scatter”: A scatter plot of points (with transparency)
    6. +
+

All types of demopal() invisibly return their (randomly +generated) data and accept some graphical arguments (e.g., +col_par and alpha), a scaling n +and a seed value (for reproducible results), as well as +main and sub arguments (for setting plot +titles). Some functions additionally accept type-specific arguments +(e.g., logical beside, horiz, and +as_prop arguments for plot type = "bar").

+
+demopal(pal = pg_2, type = 3)
+

+ +

This concludes our quick tour through the colors and color functions +of the unikn package. We hope that they enable you to +find, design, and use beautiful color palettes — and spice up your +visualizations by vivid and flamboyant colors!

+
+
+
+

Resources +

+

The following versions of unikn and corresponding +resources are currently available:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type:Version:URL:
A. unikn (R package):Release versionhttps://CRAN.R-project.org/package=unikn
 Development +versionhttps://github.com/hneth/unikn/
B. Online documentation:Release +versionhttps://hneth.github.io/unikn/
 Development versionhttps://hneth.github.io/unikn/dev/
+
+
+

Vignettes +

+ +

+unikn::

+

The following vignettes provide instructions and examples for using +the unikn colors, color palettes, and color +functions:

+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Nr.VignetteContent
1.ColorsColors and color functions
2.Color recipesRecipes for color-related tasks
3.Institutional colorsCreating color palettes for other institutions
4.TextText boxes and decorations
+ +
+
+ + + +
+ + + + +
+ + + + + + + + diff --git a/docs/dev/articles/institutional_colors.html b/docs/dev/articles/institutional_colors.html new file mode 100644 index 00000000..462a1e7a --- /dev/null +++ b/docs/dev/articles/institutional_colors.html @@ -0,0 +1,577 @@ + + + + + + + +Institutional colors • unikn + + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Institutional colors

+

SPDS, +uni.kn

+ +

2023 08 16

+ + Source: vignettes/institutional_colors.Rmd + + +
+ + + + +

+unikn::

+

The color palettes included in the unikn package are +based on the CD manual of the University of Konstanz. However, +the functionality provided by the package makes it easy and +straightforward to define and use your own colors.

+

Version 0.8.0 of unikn (released in 2023-01-06) +contained 52 additional color palettes from other institutions (mostly +universities).

+ +

As the number of color palettes has been growing beyond the scope of +this package, the color palettes from other institutions are now being +collected in a separate R package unicol.

+

Installing unicol +currently provides access to a diverse range of over 200 color +palettes from over 80 institutions.

+ +

+unicol::

+ +

The rest of this vignette explains how the color-related tools of +unikn can be used for creating new color +palettes. If you do so, please consider submitting it to be +included in future versions of the unicol +package. (For a general introduction of the +unikn colors, color palettes, and color functions, see +the vignettes on Colors and color functions +and Color recipes. The vignette on Text boxes and decorations provides information on +plotting slides and text elements.)

+

We install or load the unikn package to get +started:

+
+# install.packages('unikn')  # install unikn from CRAN client
+library('unikn')             # load the package
+
+

Creating new color palettes +

+

A color palette is an ordered collection of color objects. Creating +new color palettes in R is simple and only requires two steps:

+
    +

  1. Define the palette’s elementary colors as R objects.

    2. +

  2. Combine colors into a color palette.

    3. +
+

In the following, we illustrate both steps. As we will see, Step 1 +can either be omitted (when the to-be-combined colors exist as R +objects) or can be included in Step 2.

+

As an example, we will re-create the color palette of the German Max Planck Society (that +unikn exports as mpg_pal) from the color +definitions in its Corporate Design manual (available here).

+
+

1. Defining colors +

+

Before we can a create new color palette in R, its elementary colors +need to exist as R objects. (If all colors to-be-combined into a new +palette exist as R objects, we can skip this step and directly proceed +to 2. Combining colors into a palette.) Defining new +colors in R requires a basic understanding of their underlying +representation.

+

How colors are represented and perceived is a wide-ranging topic that +has fascinated scholars and practitioners for centuries. Essentially, +there are many alternative ways to analyze or synthesize colors, and the +most appropriate representational way depends on the specific context of +a particular use case (see Wikipedia: Color +model for an introduction).

+

In R, the grDevices package (included in any default +installation) provides colors and color-related functions. Although R +supports many color models (including HCL, HSV, Lab, Luv, and RGB +variants), the three most common ways of expressing colors in R are:

+
    +

  1. by R color name: R includes 657 named colors, whose names are +provided (as a character vector) by evaluating the colors() +function of grDevices.

    2. +

  2. by RGB values: Every color (or hue) is expressed by a triple of +numeric values on three dimensions that denote the additive primary +colors (red, green, blue). The range of values is either expressed on a +scale from 0 to 1, or — more typically — on a scale from 0 to 255 (i.e., +on an 8 bit scale allowing for \(2^8 = +256\) different values).

    3. +

  3. by HEX values: Every color (or hue) is expressed by a character +string (with the prefix #), followed by a triple of +hexadecimal values (each ranging from 00 +to FF) that correspond to the triple of decimal RGB values +(in the range from 0 to 255).

    4. +
+

Importantly, the same color (or hue) can be denoted by its +name, its RGB values, and its HEX values. Thus, the three different +systems (i.e., color name, RGB values, or HEX values) can be +alternative representations of the same object. However, just +as the properties of an alphabet or numeral notation system constraints +the words or numbers that can be expressed by it, the universe of +possible colors is limited by their representation. For instance, +whereas the RGB and HEX systems usually distinguish between more than +16 million (i.e., \((2^8)^3 = 256^3 = +16.777.216\)) possible colors, only a limited number of them are +named. Similarly, when multiple names refer to the same triple of RGB or +HEX values, they denote the same color.1

+ + +

An example helps clarifying these abstract terms. When viewing an +existing color or color palette with the seecol() function +of unikn, the name, HEX and RGB values of the +individual colors are being shown. For instance, the following color +palette mpg_pal provides the colors of the Max Planck Society:

+

+

As the middle color of mpg_pal is one of the 657 named +colors of colors(), R will recognize it as a color when we +type its name (as a character object "white") in a context +that expects color inputs. However, the two other colors of +mpg_pal have specifically been defined by the Max Planck Society and thus are +not pre-defined colors of R (i.e., not contained in +colors()). To use such colors in R, we first need to define +them as color objects.

+ +

So how can we define new colors in R? Most institutions will provide +definitions of their corporate colors or instructions how they can be +defined in some standard color system. Unfortunately, some definitions +(such as those using the subtractive CMYK model) are aimed at printing +(as opposed to computer screens) and other standards (such as numeric +PANTONE™ PMS codes) are proprietary. But as most institutions have an +interest in widely disseminating their colors, they typically include +translations or approximations for alternative color models in their +definitions.

+

+MPG

+

The Max Planck Society defines +two main colors in its CD manual (available here):

+
    +

  • A dark shade of green is defined as Pantone 328, and approximated +by CMYK 100/0/57/30 or RGB 17/102/86.

    • +

  • A light shade of grey is Pantone 427, and approximated by +CMYK 0/0/6/15 or RGB 221/222/214.

    • +
+

In the following, we will first use the RGB values to define both +colors (as these are provided in the definition). However, we then show +that we alternatively could have used the colors’ HEX values (had they +been provided) to define the same color objects.

+
+

Defining colors from their RGB values +

+

As our two colors of interest are given in RGB values, we can use the +rgb() function of the grDevices package to +define corresponding objects:

+
+mpg_green <- grDevices::rgb( 17, 102,  86, maxColorValue = 255)
+mpg_grey  <- grDevices::rgb(221, 222, 214, maxColorValue = 255)
+

The first three arguments specify values on the red, +green, and blue dimension, respectively. +Importantly, the values must be in the range \([0, max]\), where \(max\) is provided by +maxColorValue = 255. Whereas the sRGB standard expresses +all values in a normalized range of \([0, +1]\), most color definitions use the traditional 8-bit +representation that distinguish between \(2^8 += 256\) levels in the range \([0, +255]\). The rgb() function additionally allows for +adding names and a transparency level alpha, +but as we can modify these aspects later, we do not need to use them at +this point.

+

What do we obtain when we evaluate our new color objects? Let’s +see:

+
+mpg_green
+#> [1] "#116656"
+mpg_grey
+#> [1] "#DDDED6"
+

When evaluating an object created by rgb(), R returns a +character sequence of the form "#rrggbb". In this string, +the sequence rrggbb expresses the three RGB values (for the +red, green, and blue dimension, +respectively) in hexadecimal (HEX) notation (in the range \([0, 255]\)). In HEX notation, the ten +numeral symbols (i.e., the digits from 0 to 9) or the decimal system are +extended by the first six letters of the alphabet (i.e., A to F) to turn +our familiar base-10 notation into an analogous place-value notation +with a base of 16. Thus, the HEX values of "#116656" is +merely a more compact way of expressing

+
    +
  • +red: \(1 \cdot 16 + 1 = +17\) +
    • +
  • +green: \(6 \cdot 16 + 6 = +102\) +
    • +
  • +blue: \(5 \cdot 16 + 6 = +86\) +
    • +
+

Thus, the HEX values "#116656" provide an alternative +way of expressing the RGB values 17/102/86 — and both refer to the color +“MPG green” (shown as mpg_pal[1] above).

+
+
+

Defining colors from their HEX values +

+

The equivalence of the RGB and HEX notations can be illustrated by +defining the same colors a second time, but this time specifying their +HEX values (returned above):

+
+mpg_green_2 <- "#116656"
+mpg_grey_2  <- "#DDDED6"
+

If both definitions really yield identical R objects, the following +checks must evaluate to TRUE:

+
+all.equal(mpg_green, mpg_green_2)
+#> [1] TRUE
+all.equal(mpg_grey,  mpg_grey_2)
+#> [1] TRUE
+

Thus, we can define colors from both their RGB or HEX values — and +the two notations are really just two alternative ways of representing +the same colors.

+
+
+
+

2. Combining colors into a palette +

+

Having defined two new colors, we can easily combine them into a new +color palette. A color palette is simply a sequence of colors +that are stored in some sequential data structure. The two simplest data +structures in R that are suited for this purpose are vectors or data +frames. Thus, the following two expressions both define valid color +palettes:

+
+c(mpg_green, mpg_grey)
+#> [1] "#116656" "#DDDED6"
+data.frame(mpg_green, mpg_grey)
+#>   mpg_green mpg_grey
+#> 1   #116656  #DDDED6
+

As it often is easier to remember and access colors by their names, +it usually makes sense to name the elements of a color palette (e.g., by +using the name() function).

+ +

The newpal() function of unikn provides +a convenient wrapper for defining color palettes. Its main argument +col uses a vector of color objects that make up the new +palette, whereas names and as_df allow +specifying color names and switching between returning the new palette +as a vector or data base.
+Importantly, the color objects of col can be provided as +RGB values, as R color names, or as HEX values:

+
+mpg_pal_3 <- newpal(col = c(rgb( 17, 102,  86, maxColorValue = 255), "white", "#DDDED6"),
+                    names = c("MPG green", "white", "MPG grey"),
+                    as_df = FALSE)
+

The new color palette mpg_pal_3 contains the three basic +colors of mpg_pal (shown above):

+
+seecol(mpg_pal_3, 
+       main = "My new color palette", col_brd = "black", lwd_brd = .5)
+

+

The 5-color palette provided as mpg_pal includes two +intermediate colors (at positions mpg_pal[2] and +mpg_pal[4]) that are extrapolated by mixing the two main +MPG colors with “white” in a balanced (50:50) fashion. The +usecol() function of unikn automatically +performs these extrapolations when extending a 3-element color palette +(e.g., mpg_pal_3) to n = 5 colors:

+
+my_mpg_pal <- usecol(mpg_pal_3, n = 5)
+

The resulting color palette my_mpg_pal recreates the +colors of the unikn color palette mpg_pal +(shown above):

+
+seecol(my_mpg_pal, main = "My new MPG color palette", 
+       col_brd = "black", lwd_brd = .5)
+

+

Technically, the two color palettes differ in some names and the way +in which its middle color (“white”) was specified (by its R color name +or HEX values). However, when using col2rgb() for +converting both palettes into their RGB values, we see that they contain +the same colors:

+
+all.equal(col2rgb(mpg_pal), col2rgb(my_mpg_pal), check.attributes = FALSE)
+#> [1] "Numeric: lengths (9, 15) differ"
+

This concludes our illustration of defining a new colors and color +palettes.

+
+
+
+

Comparing color palettes +

+

Once a new palette has been defined (and is available in your current +R environment), the seecol() and usecol() +functions allow comparing, scaling, and using them in the same fashion +as the native unikn color palettes:

+
+# Scaled palettes: 
+seecol(list(mpg_pal, pal_unikn), n = 7,
+       pal_names = c("Max Planck", "Uni Konstanz"),
+       main = "Comparing scaled color palettes")
+

+

See the vignette on Color recipes +for additional examples of using unikn functions for +solving color-related tasks.

+ +
+
+

Call for contributions +

+

We are still expanding the range of color palettes from other +institutions in a dedicated R package unicol.

+

Collecting color palettes

+ +

+unicol::

+
    +
  • Are you using the unikn color functions to create +your own color palettes?
    • +
+

If so, please let us know (e.g., by posting on this +GitHub +issue)!

+

We collect color palettes from other institutions to make them +available to R users in future versions of unicol.

+

To enable us to verify and provide credit to your contributions, +please send us the following information:

+
    +
  1. your code (e.g., the newpal() command creating your +color palette),
    +
    2. +
  2. your reference or source information (e.g., some URL with color +definitions),
    +
    3. +
  3. your name and some contact information (e.g., an Email +address).
    4. +
+

We’re looking forward to your inputs and contributions (at this GitHub issue)!

+
+
+

Resources +

+

The following versions of unikn and corresponding +resources are currently available:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type:Version:URL:
A. unikn (R package):Release versionhttps://CRAN.R-project.org/package=unikn
 Development +versionhttps://github.com/hneth/unikn/
B. Online documentation:Release +versionhttps://hneth.github.io/unikn/
 Development versionhttps://hneth.github.io/unikn/dev/
+
+
+

Vignettes +

+ +

+unikn::

+

The following vignettes provide instructions and examples for using +the unikn colors, color palettes, and functions:

+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Nr.VignetteContent
1.ColorsColors and color functions
2.Color recipesRecipes for color-related tasks
3.Institutional colorsCreating color palettes for other institutions
4.TextText boxes and decorations
+ +
+
+
+
    +

  1. Strictly speaking, different shades of a given color can +be further distinguished by different opacity or +transparency levels (typically denoted by an alpha +value). However, the visual appearance of a transparent color can be +mimicked by mixing the color with the background color (usually +“white”). Hence, transparent shades of a color are usually not counted +as different colors.↩︎

    2. +
+
+
+ + + +
+ + + + +
+ + + + + + + + diff --git a/docs/dev/articles/text_boxes_and_decorations.html b/docs/dev/articles/text_boxes_and_decorations.html new file mode 100644 index 00000000..9dad47f4 --- /dev/null +++ b/docs/dev/articles/text_boxes_and_decorations.html @@ -0,0 +1,632 @@ + + + + + + + +Text boxes and decorations • unikn + + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+
+
+

Text boxes and decorations

+

SPDS, +uni.kn

+ +

2023 01 01

+ + Source: vignettes/text_boxes_and_decorations.Rmd + + +
+ + + + +

+unikn::

+

This vignette explains the unikn functions for +plotting graphical elements and text decorations. (See the vignette on +colors for general information on colors, +color palettes, and corresponding functions, or the more specialized +vignettes on color recipes and institutional colors.)

+

Please install and/or load the unikn package to get +started:

+
+# install.packages('unikn')  # install unikn from CRAN client
+library('unikn')             # loads the package
+
+

Overview +

+

Beyond providing support for colors, +unikn provides functions for plotting graphical +elements (like boxes) and text decorations (with colored backgrounds or +underlining). Before illustrating these functions, please note some +caveats:

+
    +

  • Plotting text (i.e., graphically rendering characters) is rarely +a 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, or +scraped). Hence, the following functions should only be used when no +better solutions are available (e.g., for adding text to graphs, or for +obstructing automatic text recognition).

    • +

  • Like all other templates, our renderings are subject to +constraints and limitations. For instance, as any standard installation +of R lacks the prescribed +“Theinhardt” fonts, we only mimic the official design specifications (in +Arial, sans serif).

    • +
+

That said, digital decorations can be useful to emphasize or +structure information, provided that they can be produced easily and +flexibly. The unikn package helps preventing common +mistakes by novices (e.g., boxes or lines extending beyond text, or +step-functions in multi-line headings) and can be customized and +improved by expert users. Hence, we hope that the following functions +are useful for plotting graphical elements (e.g., boxes, logos, etc.) +and help you achieve a uniform look when styling presentations or +visualizations.

+

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 an +existing plot, we must first create a plot to which we can add text. +unikn provides 2 basic functions for creating new +plots:

+
    +
  1. +slide plots an empty canvass (a rectangular box or +frame);
    2. +
  2. +xbox plots a colored box with an X in its top right +corner.
    3. +
+

Here are both commands with their default settings:

+
+slide()  # plot default slide
+

+
+xbox()  # plot default xbox
+

+

Both functions accept additional arguments to customize their +appearance.

+
+

Colors +

+

The background and border colors of slides can be changed by setting +their 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 the +col argument:

+
+xbox(col = Pinky)  # set background color of xbox
+

+
+
+

Dimensions +

+

By default, both slide and xbox fill the +entire plotting region (i.e., all margins are set to 0).

+

The width of a slide is set to 4/3 of its height (of 1). To change +this default, use the dim argument for specifying the +slide’s x- and y-dimensions, respectively:

+
+slide(dim = c(3, 1))  # a slide 3x wider than high
+

+

Note that changes in slide dimensions are invisible when viewing +images interactively, as R automatically scales images to the size of +the canvass. They mostly affect the relation between metrics when adding +elements to an object.

+

Similarly, an xbox has the default dimensions of a unit square (i.e., +dim = c(1, 1)). To change this default, use the +dim argument for specifying the xbox’s x- and +y-dimensions, respectively:

+
+xbox(col = Petrol, dim  = c(1, 2))  # an xbox 2 times higher than wide
+

+

The two strokes of the X (in the top right corner) are orthogonal +when viewing the xbox at the aspect ratio indicated by +dim (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 to +be distorted. Hence, viewing and printing plots at the desired aspect +ratio helps when creating an xbox.

+
+
+
+

Plotting styled text +

+

There are three main functions for plotting text with +decorations:

+
    +
  • +mark() allows highlighting text with colored background +boxes;
    • +
  • +uline() allows underlining text with colored +lines;
    • +
  • +post() allows posting text in rectangular +xbox elements.
    • +
+

In addition, there are 2 auxiliary functions:

+
    +
  • +headline() allows plotting headlines with colored +background boxes;
    • +
  • +url_unikn() allows formatting URLs the uni.kn way.
    • +
+

The following sections illustrate the functions and their main +options in turn.

+
+

Mark text +

+

The mark() function allows highlighting text by plotting +it with colored background boxes (to provide the functionality of +“Markieren”):

+

+

By default, mark() assumes that we want to add +highlighted text to an existing plot. The text labels to be added are +provided (as a character vector) by the labels argument, +their coordinates as the corresponding x and y +arguments. Various text decorations (i.e., text and background colors, +text sizes, and font types) can be set by specifying additional +arguments (i.e., col, col_bg, +cex, and font, respectively):

+
+# Some pre-existing plot: 
+n <- 20
+set.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 the +new_plot argument to either "blank" +or "slide" will generate a new default plot (by calling the +slide() 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 and +y coordinates for all text elements in labels, +the calls above defined an initial coordinate and used a numeric +y_layout argument to fix the distance between consecutive +text labels (to a value of .03).

+

As an alternative to numeric coordinates and position values, +x_layout and y_layout also accept some special +values (as character strings):

+
    +
  1. +

    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 first +label or the middle), and
      +
      • +
    • +x_layout = "right" right-justifies labels (on the first +label or the middle).
      • +
    +
    2. +
  2. +

    y_layout accepts:

    +
      +
    • +y_layout = "even" for an even distribution of labels +across the available y-space, and
      +
      • +
    • +y_layout = "flush" to omit space between adjacent +labels (as in y_layout = 0).
      • +
    +
    3. +
+

Thus, the position and orientation of the text labels can be +controlled by using the x_layout and y_layout +options:

+ + +

+

See ?mark for details.

+
+
+

Underline text +

+

The uline() function allows emphasizing text by plotting +it with colored underlining (to provide the functionality of +“Unterstreichen”):

+

+

As with mark() above, the uline() command +distinguishes between creating a new plot (by setting +new_plot to either "blank" or +“slide”) or adding to a pre-existing plot (by using the +default 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 plot
+uline(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 text +properties and decorations (col, col_bg, +cex, and font) work as they do for +mark(). For instance, shorter vectors are recycled to match +the 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 by +using the x_layout and y_layout options:

+ + +
+
+

Post text +

+

The post() function allows adding text to a +rectangular xbox (to provide the functionality of +“Merken”):

+

+

By default, post() assumes a pre-existing +xbox to which the text elements of labels are +to be added.
+For square boxes, setting new_plot to "xbox" +creates a new xbox with its default dimensions of +dim = c(1, 1).
+By adjusting its color and text arguments, post() allows +creating 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 images +providing 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 be +controlled by using the x_layout and y_layout +options:

+ + +

+
+
+

Headings +

+

The heading() function makes it easy to create +recognizable headings:

+

+

By default, the function creates a new slide (i.e., +new_plot = "slide") and positions the text elements +of labels on its left edge (i.e., x = 0, +y = .8 and y_layout = "flush"). When headings +violate 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 the +CD manual):

+
+# 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() selects +colors that are appropriate for the number of elements in +labels (i.e., shades of Seeblau for +col_bg = "default"). However, default colors can be +overwritten by setting the col and col_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) concerns +the rendering of URLs, in which typical web patterns (like “http” or +“www”) are to be omitted and replaced by a typographical dash (which is +longer than a hyphen). The url_unikn utility function +allows formatting URLs the uni.kn way:

+
+my_url <- url_unikn("https://www.uni-konstanz.de/")  # input URL
+my_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 corresponding +resources are currently available:

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type:Version:URL:
A. unikn (R package):Release versionhttps://CRAN.R-project.org/package=unikn
 Development +versionhttps://github.com/hneth/unikn/
B. Online documentation:Release +versionhttps://hneth.github.io/unikn/
 Development versionhttps://hneth.github.io/unikn/dev/
+
+
+

Vignettes +

+ +

+unikn::

+

The following vignettes provide instructions and examples for using +the unikn colors, color palettes, and functions:

+ + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Nr.VignetteContent
1.ColorsColors and color functions
2.Color recipesRecipes for color-related tasks
3.Institutional colorsCreating color palettes for other institutions
4.TextText boxes and decorations
+ +
+
+ + + +
+ + + + +
+ + + + + + + + diff --git a/docs/dev/reference/get_col_names.html b/docs/dev/reference/get_col_names.html new file mode 100644 index 00000000..1cc5570c --- /dev/null +++ b/docs/dev/reference/get_col_names.html @@ -0,0 +1,125 @@ + +Get color names — get_col_names • unikn + + +
+
+ + + +
+
+
+

Get color names

+ Source: R/util_color.R + +
+ +
+

get_col_names gets color names from color palettes.

+
+ +
+ 
get_col_names(col, custom_pals = all_pals)
+
+ +
+

Arguments

+
col
+

A vector of colors.

+ + +
custom_pals
+

A vector of color palettes.

+ +
+
+

Value

+ + +

A vector of color names.

+
+ +
+ +
+ + +
+ + + + + + + + diff --git a/docs/reference/get_col_names.html b/docs/reference/get_col_names.html new file mode 100644 index 00000000..4a516be1 --- /dev/null +++ b/docs/reference/get_col_names.html @@ -0,0 +1,125 @@ + +Get color names — get_col_names • unikn + + +
+
+ + + +
+
+
+

Get color names

+ Source: R/util_color.R + +
+ +
+

get_col_names gets color names from color palettes.

+
+ +
+ 
get_col_names(col, custom_pals = all_pals)
+
+ +
+

Arguments

+
col
+

A vector of colors.

+ + +
custom_pals
+

A vector of color palettes.

+ +
+
+

Value

+ + +

A vector of color names.

+
+ +
+ +
+ + +
+ + + + + + + +