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 [aut, cre], Ilya Kashnitsky [aut]
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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Validate Shared Parameters

Description

Validate parameters shared across tricolore functions.

Usage

ValidateParametersShared(pars)

Arguments

Validate Tricolore Parameters

Description

Validate parameters of Tricolore function.

Usage

ValidateParametersTricolore(pars)

Arguments

Validate TricoloreSextant Parameters

Description

Validate parameters of TricoloreSextant function.

Usage

ValidateParametersTricoloreSextant(pars)

Arguments

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".