Quick start

Welcome to the balance GitHub page!

Balances have become a cornerstone of compositional data analysis. However, conceptualizing balances is difficult, especially for high-dimensional data. Most often, investigators visualize balances with "balance dendrograms". However, this visualization tool does not scale well for large data. This package provides an alternative scheme for visualizing balances.

library(devtools)
devtools::install_github("tpq/balance")
library(balance)
?balance

Generating balance figures

We will demonstrate this package using an example from the robCompositions package. The "expenditures" matrix contains 20 compositions (row), each measuring 5 components (columns). As compositional data, the abundances are irrelevant and each composition sums to unity. The "y1" matrix is a serial binary partition (SBP) matrix that describes how to partition the 5 components into 4 balances.

data(expenditures, package = "robCompositions")
y1 <- data.frame(c(1, 1, 1, -1, -1), c(1, -1, -1, 0, 0),
                 c(0, +1, -1, 0, 0), c(0, 0, 0, +1, -1))
colnames(y1) <- paste0("z", 1:4)

With the data loaded, we can calculate and visualize the balances.

res <- balance.plot(expenditures, y1, size.text = 8)

Optionally, users can color components (in left figure) or samples (in right figure) based on a user-defined grouping. To do this, users must provide a vector of group labels for each component via the d.groupargument (or for each sample via the n.group argument). Here, we color components and samples by user-defined groupings.

res <- balance.plot(expenditures, y1,
                    d.group = c("A", "B", "A", "B", "C"),
                    n.group = c(rep("A", 10), rep("B", 10)),
                    size.text = 8)

Further reading

To learn more about balance, please see the vignette and relevant literature.

citation("balance")
#> 
#> To cite balance in publications use:
#> 
#>   Quinn T. 2018. Visualizing balances of compositional data: A new
#>   alternative to balance dendrograms. F1000Research, 7:1278. URL
#>   https://f1000research.com/articles/7-1278.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Article{,
#>     title = {Visualizing balances of compositional data: A new alternative to balance dendrograms},
#>     author = {Thomas Quinn},
#>     journal = {F1000Research},
#>     year = {2018},
#>     volume = {7},
#>     number = {1278},
#>     url = {https://f1000research.com/articles/7-1278},
#>   }