Visualize Balances of Compositional Data

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, described in [Quinn (2018) ]. This package also provides a method for principal balance analysis.


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
#>   http://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 = {http://f1000research.com/articles/7-1278/},
#>   }

News

balance 0.1.6


  • Update balance methods
    • balance now returns an S4 object called bplot
    • bplot has [[ method for backwards compatibility
    • balance.fromContrast now 2x faster
  • Update documentation
    • An example is now provided for each function

balance 0.1.5


  • Update pba methods
    • pba.plot no longer prints variance when y is provided
    • vlr now uses less peak RAM

balance 0.1.4


  • Extend zero handling
    • vlr will now replace 0s with next smallest value
    • balance.fromSBP will now replace 0s with next smallest value
  • Extend pba methods
    • New pba.show method shows object structure
    • New pba.plot method plots balances in 2D

balance 0.1.3


  • Add functions to perform a principal balance analysis
    • New vlr function calculates log-ratio variance using matrix algebra
    • New sbp.fromPBA function builds an SBP of principal balances
    • New pba object
      • New pba function constructs pba object
      • New predict method deploys pba model

balance 0.1.2


  • Add functions to create an SBP matrix
    • New sbp.fromHclust creates SBP matrix from hclust object
    • New sbp.sort sorts an SBP matrix predictably

balance 0.1.1


  • Modify balance.plot function
    • All points now overlap with their boxplot when boxplot.split = TRUE
  • Revise vignette and README
    • Use balance.plot() instead of balance()

balance 0.1.0


  • Modify function names
    • Rename balance() to balance.plot()
    • Create balance() wrapper for backwards compatibility
    • Rename balance.compute() to balance.fromContrast()
    • Rename balances() to balance.fromSBP()

balance 0.0.9


  • Add CITATION to package and DESCRIPTION

balance 0.0.8


  • Update balance method
    • Remove size.line argument and do not set size for !weigh.var

balance 0.0.7


  • Update balance method
    • Fix bug caused by using n.group in presence of unique rownames

balance 0.0.6


  • Update balance method
    • Use weigh.var argument to weigh line width by explained variance
    • Use size.line argument to alter line width factor

balance 0.0.5


  • Update balance method
    • Compute balances using exp(mean(log(x))) to prevent overflow
    • Remove "linetype" aesthetic from partition figure

balance 0.0.4


  • Update balance method
    • Re-write robCompositions::balances call as balances function
    • Re-write reshape2::melt call as wide2long function

balance 0.0.3


  • Update balance method
    • Coerce input as data.frame to prevent errors

balance 0.0.2


  • Update balance method
    • Fix the automatic sorting of serial binary partition matrix
    • Add test that sorting does not alter results

balance 0.0.1


  • Create package skeleton
    • Add balance.combine function to merge figures
    • Add balance function to visualize balances
    • Complete package DESCRIPTION
    • Create README

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("balance")

0.1.9 by Thomas Quinn, 2 hours ago


http://github.com/tpq/balance


Report a bug at http://github.com/tpq/balance/issues


Browse source code at https://github.com/cran/balance


Authors: Thomas Quinn [aut, cre]


Documentation:   PDF Manual  


GPL-2 license


Imports methods, ggplot2, grid

Suggests ape, ggthemes, knitr, philr, propr, reshape2, rmarkdown, robCompositions, testthat


See at CRAN