CoDaDendrogram         package:compositions         R Documentation

_D_e_n_d_r_o_g_r_a_m _r_e_p_r_e_s_e_n_t_a_t_i_o_n _o_f _a_c_o_m_p _o_r _r_c_o_m_p _o_b_j_e_c_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     Function for plotting CoDa-dendrograms of acomp or rcomp objects.

_U_s_a_g_e:

     CoDaDendrogram(X,V=NULL,mergetree=NULL,signary=NULL,range=c(-4,4),...,
             xlim=NULL, ylim=NULL,yaxt=NULL, box.pos=0, box.space=0.25,
             col.tree="black", lty.tree=1, lwd.tree=1,
             col.leaf="black", lty.leaf=1, lwd.leaf=1,
             add=FALSE,type="boxplot")
               

_A_r_g_u_m_e_n_t_s:

       X: data set to plot (an rcomp or acomp object) 

       V: basis to use, described as an ilr matrix 

mergetree: basis to use, described as a merging tree (as in 'hclust') 

 signary: basis to use, described as a sign matrix (as in the example
          below)

   range: minimum and maximum value for all coordinates (horizontal
          axes) 

     ...: further parameters to pass to any function, be it a plotting
          function or one related to the "type" parameter below; likely
          to produce lots of warnings

    xlim: minimum and maximum values for the horizontal direction of
          the plot (related to number of parts) 

    ylim: minimum and maximum values for the vertical direction of the
          plot (related to variance of coordinates) 

    yaxt: axis type for the vertical direction of the plot (see 'par')

 box.pos: if type="boxplot", this is the relative position of the box
          in the vertical direction: 0 means centered on the axis, -1
          aligned below the axis and +1 aligned above the axis 

box.space: if type="boxplot", size of the box in the vertical direction
          as a portion of the minimal variance of the coordinates 

col.tree: color for the horizontal axes 

lty.tree: line type for the horizontal axes 

lwd.tree: line width for the horizontal axes 

col.leaf: color for the vertical conections between an axis and a part
          (leaf) 

lty.leaf: line type for the leaves 

lwd.leaf: line width for the leaves 

     add: should a new plot be triggered, or is the material to be
          added to an existing CoDa-dendrogram? 

    type: what to represent? one of
          "boxplot","density","histogram","lines","nothing" or
          "points", or an univocal abbreviation 

_D_e_t_a_i_l_s:

     The object _and an isometric basis_ are represented in a
     CoDa-dendrogram, as defined by Egozcue and Pawlowsky-Glahn (2005).
     This is a representation of the following elements:

   _a a hierarchical partition (which can be specified either through an
        ilrBase matrix (see 'ilrBase'), a merging tree structure (see
        'hclust') or a signary matrix (see 'gsi.merge2signary'))

   _b the sample mean of each coordinate of the ilr basis associated to
        that partition

   _c the sample variance of each coordinate of the ilr basis associated
        to that partition

   _d optionally (potentially!), any graphical representation of each
        coordinate, as long as this representation is suitable for a
        univariate data set (box-plot, histogram, dispersion and kernel
        density are programmed or intended to, but any other may be
        added with little work).

     Each coordinate is represented in a horizontal axis, which limits
     correspond to the values given in the parameter 'range'. The
     vertical bar going up from each one of these coordinate axes
     represent the variance of that specific coordinate, and the
     contact point the coordinate mean. Note that to be able to
     represent an initial dendrogram, the first call to this function
     must be given a full data set, as means and variances must be
     computed. This information is afterwards stored in a global list,
     to add any sort of new material to all coordinates. 
      The default option is 'type="boxplot"', which produces a box-plot
     for each coordinate, customizable using 'box.pos' and 'box.space',
     as well as typical 'par' parameters (col, border, lty, lwd, etc.).
     To obtain only the first three aspects, the function must be
     called with 'type="lines"'. As extensions, one might represent a
     single datum/few data (e.g., a mean or a random subsample of the
     data set) calling the function with 'add=TRUE' and
     'type="points"'. Other options (calling functions 'histogram' or
     code{density}, and admitting their parameters) will be  also soon
     available. 
      Note that the original coda-dendrogram as defined by Egozcue and
     Pawlowsky-Glahn (2005) works with acomp objects and ilr bases.
     Functionality is extended to rcomp objects using calls to 'idt'.

_A_u_t_h_o_r(_s):

     Raimon Tolosana-Delgado, K.Gerald v.d. Boogaart <URL:
     http://www.stat.boogaart.de>

_R_e_f_e_r_e_n_c_e_s:

     Egozcue J.J., V. Pawlowsky-Glahn, G. Mateu-Figueras and C.
     Barcel'o-Vidal (2003) Isometric logratio transformations for
     compositional data analysis. _Mathematical Geology_, *35*(3)
     279-300

     Egozcue, J.J. and V. Pawlowsky-Glahn (2005). CoDa-Dendrogram: a
     new exploratory tool. In: Mateu-Figueras, G. and Barcel\'o-Vidal,
     C. (Eds.) _Proceedings of the 2nd International Workshop on
     Compositional Data Analysis_, Universitat de Girona, {ISBN}
     84-8458-222-1, <URL: http://ima.udg.es/Activitats/CoDaWork05>

_S_e_e _A_l_s_o:

     'ilrBase','rcomp', 'acomp',

_E_x_a_m_p_l_e_s:

     # first example: take the data set from the example, select only
     # compositional parts
     data(Hydrochem)
     x = acomp(Hydrochem[,-c(1:5)])
     gr = Hydrochem[,4] # river groups (useful afterwards)
     # use an ilr basis coming from a clustering of parts
     dd = dist(t(clr(x)))
     hc1 = hclust(dd,method="ward")
     plot(hc1)
     mergetree=hc1$merge
     CoDaDendrogram(X=acomp(x),mergetree=mergetree,col="red",range=c(-8,8),box.space=1)
     # add the mean of each river
     color=c("green3","red","blue","darkviolet")
     aux = clr.inv(t(sapply(split(clr(x),gr),mean)))
     CoDaDendrogram(X=aux,add=TRUE,col=color,type="points",pch=4)

     # second example: box-plots by rivers (filled)
     CoDaDendrogram(X=acomp(x),mergetree=mergetree,col="black",range=c(-8,8),type="l")
     xsplit = split(x,gr)
     for(i in 1:4){
       CoDaDendrogram(X=acomp(xsplit[[i]]),col=color[i],type="box",box.pos=i-2.5,box.space=0.5,add=TRUE)
     }

     # third example: fewer parts, partition defined by a signary, and empty box-plots
     x = acomp(Hydrochem[,c("Na","K","Mg","Ca","Sr","Ba","NH4")])
     signary = t(matrix(  c(1,   1,   1,  1,   1,   1,  -1,
                            1,   1,  -1, -1,  -1,  -1,   0,
                            1,  -1,   0,  0,   0,   0,   0,
                            0,   0,  -1,  1,  -1,  -1,   0,
                            0,   0,   1,  0,  -1,   1,   0,
                            0,   0,   1,  0,   0,  -1,   0),ncol=7,nrow=6,byrow=TRUE))

     CoDaDendrogram(X=acomp(x),signary=signary,col="black",range=c(-8,8),type="l")
     xsplit = split(x,gr)
     for(i in 1:4){
       CoDaDendrogram(X=acomp(xsplit[[i]]),border=color[i],
            type="box",box.pos=i-2.5,box.space=1.5,add=TRUE)
       CoDaDendrogram(X=acomp(xsplit[[i]]),col=color[i],
            type="line",add=TRUE)
     }
     # see how easy are warnings produced ;-)
     warnings()

