Type: | Package |
Title: | A Flexible Color Scale for Ternary Compositions |
Version: | 1.2.4 |
Description: | Compositional data consisting of three-parts can be color mapped with a ternary color scale. Such a scale is provided by the tricolore packages with options for discrete and continuous colors, mean-centering and scaling. See Jonas Schöley (2021) "The centered ternary balance scheme. A technique to visualize surfaces of unbalanced three-part compositions" <doi:10.4054/DemRes.2021.44.19>, Jonas Schöley, Frans Willekens (2017) "Visualizing compositional data on the Lexis surface" <doi:10.4054/DemRes.2017.36.21>, and Ilya Kashnitsky, Jonas Schöley (2018) "Regional population structures at a glance" <doi:10.1016/S0140-6736(18)31194-2>. |
License: | GPL-3 |
URL: | https://github.com/jschoeley/tricolore |
Encoding: | UTF-8 |
LazyData: | true |
Depends: | R (≥ 4.0) |
Imports: | grDevices, ggplot2 (≥ 3.4.0), ggtern (≥ 3.4.0), rlang (≥ 1.1.0), shiny, assertthat |
RoxygenNote: | 7.3.1 |
Suggests: | testthat, knitr, rmarkdown, sf, leaflet, httpuv, dplyr |
VignetteBuilder: | knitr |
NeedsCompilation: | no |
Packaged: | 2024-05-14 13:32:29 UTC; jon |
Author: | Jonas Schöley |
Maintainer: | Jonas Schöley <jschoeley@gmail.com> |
Repository: | CRAN |
Date/Publication: | 2024-05-15 15:00:02 UTC |
Template for Ternary Key
Description
Return various types of breaks and labels for ternary color keys.
Usage
BasicKey(legend_surface, limits, brklab, show_center, center, lwd)
Arguments
legend_surface |
A data frame with numeric 'id', 'p1', 'p2', 'p3' and character column 'rgb'. |
limits |
A 2 by 3 matrix of lower and upper limits for p1, p2 and p3. |
brklab |
Breaks and labels as returned by |
show_center |
Should the center be marked on the legend? (logical) |
center |
Ternary coordinates of the grey-point. |
lwd |
A numeric scalar giving the linewidth of the legend surface polygons. |
Value
A ggtern grob.
Breaks and Labels for Ternary Color Key
Description
Return various types of breaks and labels for ternary color keys.
Usage
BreaksAndLabels(type, center = NULL, breaks = NULL)
Arguments
type |
An integer 1, 2, or 3. |
center |
Ternary coordinates of the grey-point. |
breaks |
Number of breaks in the discrete color scale. An integer >1. Values above 99 imply no discretization. |
Value
A list of lists containing breaks and labels for each of the 3 ternary axes.
Examples
# NOTE: only intended for internal use and not part of the API
tricolore:::BreaksAndLabels(1, breaks = 3)
tricolore:::BreaksAndLabels(2)
tricolore:::BreaksAndLabels(3, center = c(1/3, 1/3, 1/3))
Compositional Centre
Description
Calculate the centre of a compositional data set.
Usage
Centre(P)
Arguments
P |
n by m matrix of compositions [p1, ..., pm]_i for i=1,...,n. |
Value
The centre of P as an m element numeric vector.
References
Von Eynatten, H., Pawlowsky-Glahn, V., & Egozcue, J. J. (2002). Understanding perturbation on the simplex: A simple method to better visualize and interpret compositional data in ternary diagrams. Mathematical Geology, 34(3), 249-257.
Pawlowsky-Glahn, V., Egozcue, J. J., & Tolosana-Delgado, R. (2007). Lecture Notes on Compositional Data Analysis. Retrieved from https://dugi-doc.udg.edu/bitstream/handle/10256/297/CoDa-book.pdf
Examples
# NOTE: only intended for internal use and not part of the API
P <- prop.table(matrix(runif(300), 100), margin = 1)
tricolore:::Centre(P)
Sextant Scheme Legend
Description
Plot a sextant scheme legend.
Usage
ColorKeySextant(
center,
values,
label_as,
show_center,
limits = matrix(0:1, nrow = 2, ncol = 3)
)
Arguments
center |
Ternary coordinates of the sextant meeting point. |
values |
6 element character vector of rgb-codes. |
label_as |
"pct" for percent-share labels or "pct_diff" for percent-point-difference from center labels. |
show_center |
Should the center be marked on the legend? (logical) |
limits |
A 2 by 3 matrix of lower and upper limits for p1, p2 and p3. |
Value
A ggtern grob.
Examples
# NOTE: only intended for internal use and not part of the API
tricolore:::ColorKeySextant(center = prop.table(runif(3)),
values = c('#01A0C6', '#B8B3D8', '#F11D8C',
'#FFB3B3', '#FFFF00', '#B3DCC3'),
label_as = 'pct_diff', show_center = TRUE)
Ternary Balance Scheme Legend
Description
Plot a ternary balance scheme legend.
Usage
ColorKeyTricolore(
center,
breaks,
h_,
c_,
l_,
contrast,
spread,
label_as,
show_center,
limits = matrix(0:1, nrow = 2, ncol = 3)
)
Arguments
center |
Ternary coordinates of the grey-point. |
breaks |
Number of breaks in the discrete color scale. An integer >1. Values above 99 imply no discretization. |
h_ |
Primary hue of the first ternary element in angular degrees [0, 360]. |
c_ |
Maximum possible chroma of mixed colors [0, 200]. |
l_ |
Lightness of mixed colors [0, 100]. |
contrast |
Lightness contrast of the color scale [0, 1). |
spread |
Spread of the color scale around center > 0. |
label_as |
"pct" for percent-share labels or "pct_diff" for percent-point-difference from center labels. |
show_center |
Should the center be marked on the legend? (logical) |
limits |
A 2 by 3 matrix of lower and upper limits for p1, p2 and p3. |
Value
A ggtern grob.
Examples
# NOTE: only intended for internal use and not part of the API
tricolore:::ColorKeyTricolore(center = rep(1/3, 3), breaks = 4,
h_ = 80, c_ = 140, l_ = 80,
contrast = 0.4, spread = 1,
label_as = "pct", show_center = FALSE)
Sextant Encoding of Ternary Composition
Description
Return the sextant scheme colors for a matrix of ternary compositions.
Usage
ColorMapSextant(P, center, values)
Arguments
P |
n by 3 matrix of ternary compositions [p1, p2, p3](i) for i=1, ..., n. |
center |
Ternary coordinates of the sextant meeting point. |
values |
6 element character vector of rgb-codes. |
Value
An n row data frame giving, for each row of the input P, the input proportions [p1, p2, p3], sextant id (sextant) and the hex-rgb string of the mixed colors (rgb).
Examples
# NOTE: only intended for internal use and not part of the API
P <- prop.table(matrix(runif(9), ncol = 3), 1)
tricolore:::ColorMapSextant(P, c(1/3, 1/3, 1/3),
c('#01A0C6', '#B8B3D8', '#F11D8C', '#FFB3B3',
'#FFFF00', '#B3DCC3'))
CIE-Lch Mixture of Ternary Composition
Description
Return the ternary balance scheme colors for a matrix of ternary compositions.
Usage
ColorMapTricolore(P, center, breaks, h_, c_, l_, contrast, spread)
Arguments
P |
n by 3 matrix of ternary compositions [p1, p2, p3](i) for i=1, ..., n. |
center |
Ternary coordinates of the grey-point. |
breaks |
Number of breaks in the discrete color scale. An integer >1. Values above 99 imply no discretization. |
h_ |
Primary hue of the first ternary element in angular degrees [0, 360]. |
c_ |
Maximum possible chroma of mixed colors [0, 200]. |
l_ |
Lightness of mixed colors [0, 100]. |
contrast |
Lightness contrast of the color scale [0, 1). |
spread |
Spread of the color scale around center > 0. |
Value
An n row data frame giving, for each row of the input P, the input proportions [p1, p2, p3], parameters of the color mixture (h, c, l) and the hex-rgb string of the mixed colors (rgb).
Examples
# NOTE: only intended for internal use and not part of the API
P <- prop.table(matrix(runif(9), ncol = 3), 1)
tricolore:::ColorMapTricolore(P, center = rep(1/3, 3), breaks = 4,
h_ = 80, c_ = 140, l_ = 80,
contrast = 0.4, spread = 1)
Interactive Tricolore Demonstration
Description
An interactive demonstration of the tricolore color scale inspired by the colorbrewer2.org application. Helps in picking the right color scale for your data.
Usage
DemoTricolore()
Value
Opens a shiny app session.
Geometric Mean
Description
Calculate the geometric mean for a numeric vector.
Usage
GeometricMean(x, na.rm = TRUE, zero.rm = TRUE)
Arguments
x |
Numeric vector. |
na.rm |
Should NAs be removed? (default=TRUE) |
zero.rm |
Should zeros be removed? (default=TRUE) |
Value
The geometric mean as numeric scalar.
Examples
# NOTE: only intended for internal use and not part of the API
tricolore:::GeometricMean(0:100)
tricolore:::GeometricMean(0:100, zero.rm = FALSE)
Compositional Pertubation
Description
Pertubate a compositional data set by a compositional vector.
Usage
Pertube(P, c = rep(1/3, 3))
Arguments
P |
n by m matrix of compositions [p1, ..., pm]_i for i=1,...,n. |
c |
Compositional pertubation vector [c1, ..., cm]. |
Value
n by m matrix of pertubated compositions.
References
Von Eynatten, H., Pawlowsky-Glahn, V., & Egozcue, J. J. (2002). Understanding perturbation on the simplex: A simple method to better visualize and interpret compositional data in ternary diagrams. Mathematical Geology, 34(3), 249-257.
Pawlowsky-Glahn, V., Egozcue, J. J., & Tolosana-Delgado, R. (2007). Lecture Notes on Compositional Data Analysis. Retrieved from https://dugi-doc.udg.edu/bitstream/handle/10256/297/CoDa-book.pdf
Examples
# NOTE: only intended for internal use and not part of the API
P <- prop.table(matrix(runif(12), 4), margin = 1)
cP <- tricolore:::Pertube(P, 1/tricolore:::Centre(P))
tricolore:::Centre(cP)
Compositional Powering
Description
Raise a compositional data-set to a given power.
Usage
PowerScale(P, scale = 1)
Arguments
P |
n by m matrix of compositions [p1, ..., pm]_i for i=1,...,n. |
scale |
Power scalar. |
Value
n by m numeric matrix of powered compositions.
References
Pawlowsky-Glahn, V., Egozcue, J. J., & Tolosana-Delgado, R. (2007). Lecture Notes on Compositional Data Analysis. Retrieved from https://dugi-doc.udg.edu/bitstream/handle/10256/297/CoDa-book.pdf
Examples
# NOTE: only intended for internal use and not part of the API
P <- prop.table(matrix(runif(12), 4), margin = 1)
tricolore:::PowerScale(P, 2)
Return Ternary Gridlines Centered Around Some Composition
Description
Return Ternary Gridlines Centered Around Some Composition
Usage
TernaryCenterGrid(center, spacing)
Arguments
center |
The center of the grid. A vector of ternary coordinates [p1, p2, p3]. |
spacing |
The spacing of the grid in percent-point increments. A numeric > 0. |
Value
A list of lists.
Examples
# NOTE: only intended for internal use and not part of the API
tricolore:::TernaryCenterGrid(c(1/6, 2/6, 3/6), 10)
Distance Between Points in Ternary Coordinates
Description
The distances between ternary coordinate p and a set of ternary coordinates C.
Usage
TernaryDistance(p, C)
Arguments
p |
A vector of ternary coordinates [p1, p2, p3]. |
C |
n by 3 matrix of ternary coordinates [p1, p2, p3](i) for i=1,...,n. |
Value
A numeric vector of distances between coordinate p and all coordinates in C.
References
https://en.wikipedia.org/wiki/Barycentric_coordinate_system#Distance_between_points
Examples
# NOTE: only intended for internal use and not part of the API
p <- c(0.5, 0.2, 0.3)
C <- prop.table(matrix(runif(3*10), ncol = 3), 1)
tricolore:::TernaryDistance(p, C)
Return the Limits of Ternary Coordinates
Description
Return the Limits of Ternary Coordinates
Usage
TernaryLimits(P, na.rm = TRUE)
Arguments
P |
n by 3 matrix of ternary coordinates [p1, p2, p3](i) for i=1,...,n. |
na.rm |
Should NAs be removed? (default=TRUE) |
Value
A 2 by 3 matrix of lower and upper limits for p1, p2 and p3.
Examples
# NOTE: only intended for internal use and not part of the API
P <- prop.table(matrix(runif(9), ncol = 3), 1)
tricolore:::TernaryLimits(P)
Centroid Coordinates of Sub-Triangles in Segmented Equilateral Triangle
Description
Segment an equilateral triangle into k^2 equilateral sub-triangles and return the barycentric centroid coordinates of each sub-triangle.
Usage
TernaryMeshCentroids(k)
Arguments
k |
Number of rows in the segmented equilateral triangle. |
Value
A numeric matrix of with index and barycentric centroid coordinates of regions id=1,...,k^2.
References
S. H. Derakhshan and C. V. Deutsch (2009): A Color Scale for Ternary Mixtures.
Examples
# NOTE: only intended for internal use and not part of the API
tricolore:::TernaryMeshCentroids(1)
tricolore:::TernaryMeshCentroids(2)
tricolore:::TernaryMeshCentroids(3)
Vertex Coordinates of Sub-Triangles in Segmented Equilateral Triangle
Description
Given the barycentric centroid coordinates of the sub-triangles in an equilateral triangle subdivided into k^2 equilateral sub-triangles, return the barycentric vertex coordinates of each sub-triangle.
Usage
TernaryMeshVertices(C)
Arguments
C |
n by 4 matrix of barycentric centroid coordinates of n=k^2 sub-triangles. Column order: id, p1, p2, p3 with id=1,...,k^2. |
Value
A numeric matrix with index, vertex id and barycentric vertex coordinates for each of the k^2 sub-triangles.
References
S. H. Derakhshan and C. V. Deutsch (2009): A Color Scale for Ternary Mixtures.
Examples
# NOTE: only intended for internal use and not part of the API
k = 2
C <- tricolore:::TernaryMeshCentroids(k)
tricolore:::TernaryMeshVertices(C)
For Ternary Coordinates P Return the Nearest Coordinate in Set C
Description
For Ternary Coordinates P Return the Nearest Coordinate in Set C
Usage
TernaryNearest(P, C)
Arguments
P , C |
n by 3 matrix of ternary coordinates [p1, p2, p3](i) for i=1,...,n. n may be different for P and C. |
Value
n by 3 matrix of ternary coordinates in C.
Examples
# NOTE: only intended for internal use and not part of the API
P <- prop.table(matrix(runif(9), ncol = 3), 1)
C <- tricolore:::TernaryMeshCentroids(2)[,-1]
tricolore:::TernaryNearest(P, C)
Vertex Coordinates of Sextants in Equilateral Triangle
Description
Given a barycentric center coordinate return the vertex coordinates of the of the sextant regions.
Usage
TernarySextantVertices(center)
Arguments
center |
The sextant center. A vector of ternary coordinates [p1, p2, p3]. |
Value
Index, vertex id and barycentric vertex coordinates for each of the 6 sextants.
Examples
# NOTE: only intended for internal use and not part of the API
tricolore:::TernarySextantVertices(rep(1/3, 3))
Return Surrounding Sextant of Barycentric Coordinates
Description
Given barycentric coordinates return the id of the surrounding sextant.
Usage
TernarySurroundingSextant(P, center)
Arguments
P |
n by 3 matrix of ternary coordinates [p1, p2, p3](i) for i=1,...,n. |
center |
The sextant center. A vector of ternary coordinates [p1, p2, p3]. |
Value
An n element character vector of sextant id's 1 to 6.
Examples
# NOTE: only intended for internal use and not part of the API
P <- prop.table(matrix(runif(9), ncol = 3), 1)
tricolore:::TernarySurroundingSextant(P, rep(1/3, 3))
Ternary Balance Color Scale
Description
Color-code three-part compositions with a ternary balance color scale and return a color key.
Usage
Tricolore(
df,
p1,
p2,
p3,
center = rep(1/3, 3),
breaks = ifelse(identical(center, rep(1/3, 3)), 4, Inf),
hue = 0.2,
chroma = 0.7,
lightness = 0.8,
contrast = 0.4,
spread = 1,
legend = TRUE,
show_data = TRUE,
show_center = ifelse(identical(center, rep(1/3, 3)), FALSE, TRUE),
label_as = ifelse(identical(center, rep(1/3, 3)), "pct", "pct_diff"),
crop = FALSE,
input_validation = TRUE
)
Arguments
df |
Data frame of compositional data. |
p1 |
Column name for variable in df giving first proportion of ternary composition (string). |
p2 |
Column name for variable in df giving second proportion of ternary composition (string). |
p3 |
Column name for variable in df giving third proportion of ternary composition (string). |
center |
Ternary coordinates of the color scale center. (default = 1/3,1/3,1/3). NA puts center over the compositional mean of the data. |
breaks |
Number of per-axis breaks in the discrete color scale. An integer >1. Values above 99 imply no discretization. |
hue |
Primary hue of the first ternary element (0 to 1). |
chroma |
Maximum possible chroma of mixed colors (0 to 1). |
lightness |
Lightness of mixed colors (0 to 1). |
contrast |
Lightness contrast of the color scale (0 to 1). |
spread |
The spread of the color scale. Choose values > 1 to focus the color scale on the center. |
legend |
Should a legend be returned along with the colors? (default=TRUE) |
show_data |
Should the data be shown on the legend? (default=TRUE) |
show_center |
Should the center be shown on the legend? (default=FALSE if center is at c(1/3, 1/3, 1/3), otherwise TRUE) |
label_as |
"pct" for percent-share labels or "pct_diff" for percent-point-difference from center labels. (default='pct' if center is at c(1/3, 1/3, 1/3), otherwise 'pct_diff') |
crop |
Should the legend be cropped to the data? (default=FALSE) |
input_validation |
Should the function arguments be validated? (default=TRUE) |
Value
legend=FALSE: A vector of rgbs hex-codes representing the ternary balance scheme colors.
legend=TRUE: A list with elements "rgb" and "key".
Examples
P <- as.data.frame(prop.table(matrix(runif(3^6), ncol = 3), 1))
Tricolore(P, 'V1', 'V2', 'V3')
Ternary Sextant Color Scale
Description
Color-code three-part compositions with a ternary sextant color scale and return a color key.
Usage
TricoloreSextant(
df,
p1,
p2,
p3,
center = rep(1/3, 3),
values = c("#FFFF00", "#B3DCC3", "#01A0C6", "#B8B3D8", "#F11D8C", "#FFB3B3"),
legend = TRUE,
show_data = TRUE,
show_center = TRUE,
label_as = ifelse(identical(center, rep(1/3, 3)), "pct", "pct_diff"),
crop = FALSE,
input_validation = TRUE
)
Arguments
df |
Data frame of compositional data. |
p1 |
Column name for variable in df giving first proportion of ternary composition (string). |
p2 |
Column name for variable in df giving second proportion of ternary composition (string). |
p3 |
Column name for variable in df giving third proportion of ternary composition (string). |
center |
Ternary coordinates of the color scale center. (default = 1/3,1/3,1/3). NA puts center over the compositional mean of the data. |
values |
6 element character vector of rgb-codes. |
legend |
Should a legend be returned along with the colors? (default=TRUE) |
show_data |
Should the data be shown on the legend? (default=TRUE) |
show_center |
Should the center be shown on the legend? (default=FALSE if center is at c(1/3, 1/3, 1/3), otherwise TRUE) |
label_as |
"pct" for percent-share labels or "pct_diff" for percent-point-difference from center labels. (default='pct' if center is at c(1/3, 1/3, 1/3), otherwise 'pct_diff') |
crop |
Should the legend be cropped to the data? (default=FALSE) |
input_validation |
Should the function arguments be validated? (default=TRUE) |
Value
legend=FALSE: A vector of rgbs hex-codes representing the ternary balance scheme colors.
legend=TRUE: A list with elements "rgb" and "key".
Examples
P <- as.data.frame(prop.table(matrix(runif(3^6), ncol = 3), 1))
TricoloreSextant(P, 'V1', 'V2', 'V3')
Validate Main Arguments
Description
Validate main arguments of tricolore function.
Usage
ValidateMainArguments(df, p1, p2, p3)
Arguments
df |
Data frame of compositions. |
p1 |
Column name for variable in df giving first proportion of ternary composition (string). |
p2 |
Column name for variable in df giving second proportion of ternary composition (string. |
p3 |
Column name for variable in df giving third proportion of ternary composition (string). |
Validate Shared Parameters
Description
Validate parameters shared across tricolore functions.
Usage
ValidateParametersShared(pars)
Arguments
pars |
A named list of parameters. |
Validate Tricolore Parameters
Description
Validate parameters of Tricolore function.
Usage
ValidateParametersTricolore(pars)
Arguments
pars |
A named list of parameters. |
Validate TricoloreSextant Parameters
Description
Validate parameters of TricoloreSextant function.
Usage
ValidateParametersTricoloreSextant(pars)
Arguments
pars |
A named list of parameters. |
Flat Map of European Continent
Description
A ggplot object rendering a flat background map of the European continent.
Usage
euro_basemap
Format
An object of class gg
(inherits from ggplot
) of length 9.
Source
Derived from Eurostats European Geodata. (c) EuroGeographics for the administrative boundaries. https://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/administrative-units-statistical-units/
NUTS-2 Level Geodata and Compositional Data for Europe
Description
A simple-features dataframe containing the NUTS-2 level polygons of European regions along with regional compositional data on education and labor-force.
Usage
euro_example
Format
A data frame with 312 rows and 9 variables:
- id
NUTS-2 code.
- name
Name of NUTS-2 region.
- ed_0to2
Share of population with highest attained education "lower secondary or less".
- ed_3to4
Share of population with highest attained education "upper secondary".
- ed_5to8
Share of population with highest attained education "tertiary".
- lf_pri
Share of labor-force in primary sector.
- lf_sec
Share of labor-force in secondary sector.
- lf_ter
Share of labor-force in tertiary sector.
- geometry
Polygon outlines for regions in sf package format.
Details
Variables starting with "ed" refer to the relative share of population ages 25 to 64 by educational attainment in the European NUTS-2 regions 2016.
Variables starting with "lf" refer to the relative share of workers by labor-force sector in the European NUTS-2 regions 2016. The original NACE (rev. 2) codes have been recoded into the three sectors "primary" (A), "secondary" (B-E & F) and "tertiary" (all other NACE codes).
Source
Derived from Eurostats European Geodata. (c) EuroGeographics for the administrative boundaries. https://ec.europa.eu/eurostat/web/gisco/geodata/reference-data/administrative-units-statistical-units/
Education data derived from Eurostats table "edat_lfse_04".
Labor-force data derived from Eurostats table "lfst_r_lfe2en2".