Package MVPARTwrap. February 15, 2013

Transcription

1 Package MVPARTwrap February 15, 2013 Version Date Title MVPARTwrap: Additional functionnalities for package mvpart. Author Marie-Helene Ouellette with contributions from Pierre Legendre Maintainer Marie-Helene Ouellette Depends Hmisc, mvpart, labdsv, vegan, fbasics, ade4 The main function of this package, MRT, provides to the following information : the proper cluster membership allocation in the tree, the discriminant species for each cluster, the tree nodes at the proper level of R2 (1-relative error), the total species variance partitionned by species, by the tree, and by the splits of the tree, plus a different graphic representation of the final model in the form of a tree. Moreover, the CascadeMRT function allows a cascade MRT analysis and the CasMRTR2 function allows to illustrate the (unadjusted) variation explained by each wave/drops. Last but not least, the R2aGDF function permits the calculation of an adjusted R^2 for an MRT model. License GPL (>= 2) URL Repository CRAN Date/Publication :52:41 NeedsCompilation no 1

2 2 CascadeMRT R topics documented: CascadeMRT CasMRTR code.tree mat_labels_fct MRT ORDER_NODES plot.mrt plot_tree R2aGDF summary.mrt svaluecol Index 19 CascadeMRT Cascade of Multivariate Regression Trees Analysis Function CascadeMRT performs a cascade multivariate regression tree analysis using mvpart as a basic function to persue the multivariate tree analyses. The first model is at the top of the cascade and is called the first drop. All models built on the leafs of the first drop are called subsequent drops and consist the second wave. See Ouellette, Legendre & Borcard (accepted) for further informations and details. CascadeMRT(Y, VSG, VA, xv1= min, xvsub= min, minbucket1=5, minbucketsub=2, cp1=0.1, cpsub=0.01,...) Y VSG VA xv1 xvsub minbucket1 minbucketsub cp1 cpsub Response matrix Explanatory variables used for second wave Explanatory variables used for first wave xv argument for the first wave xv argument for second wave minbucket argument for the first wave minbucket argument for second wave cp argument for the first wave cp argument for second wave... further arguments given to mvpart. See rpart.control and mvpart for further details. These controls will be used for both the first wave and second wave of models.

3 CascadeMRT 3 Details Value cp1 and cpsub arguments are used to specify the complexity parameter of each wave (cp1 for the principal, and cpsub for the subsequent wave). The complexity parameter of an MRT model is the minimum contribution to the R 2 of the tree for a split to be considered. As the main explanatory set is set to explain the largest response composition variation, the complexity parameter cp1 could be set to be higher than the usual 0.01 value (by default 0.1). An object of class CascadeMRT, basically a list including the following elements drops part1 where1 Y List of mvpart models built, the first drop follow by the subsequent drops given in the order of where1. Unique leaf numbers of the first drop Partition membership of the first drop Original response matrix. Useful for use of CasMRTR2 function. References Dea th, G Multivariate regression tree : a new technique for modeling species-environment relationships. Ecology 83: Ouellette, M.-H. & P. Legendre. An adjusted R 2 statistic for multivariate regression tree analysis. Manuscript. Ouellette, M.-H., P. Legendre and D. Borcard Cascade Multivariate Regression Tree: a novel approach for modelling nested explanatory sets. Methods in Ecology & Evolution 3: See Also mvpart,casmrtr2 Examples # Initialisation require(vegan) require(mvpart) require(mvpartwrap) require(ade4) ### -- Doubs example --- ### # # # Note that we modify the data found in ade4 to match the data # set provided with Numerical Ecology in R (Borcard et al 2011), # the data set used in the paper Ouellette, Legendre & Borcard # (2012). data(doubs)

4 4 CasMRTR2 # Data importation # spe<-doubs$fish envmod<-doubs$env envmod[,1]<-envmod[,1]/10 envmod[7,1]<-36.8 envmod[,3]<-round((exp(envmod[,3])-1)/10,1) envmod[,4]<-envmod[,4]/100 envmod[,5]<-envmod[,5]/10 envmod[,7]<-envmod[,7]/100 envmod[,8]<-envmod[,8]/100 envmod[,9]<-envmod[,9]/100 envmod[,10]<-envmod[,10]/10 envmod[,11]<-envmod[,11]/10 envmod_nodas<-envmod[,-1] spe.hel <- decostand(spe, "hellinger") POISSON<-CascadeMRT(Y=spe.hel, VSG=envmod_nodas, VA=as.data.frame(envmod[,1]), xvmult=100) CasMRTR2(POISSON,NodeADMIT=3) ### -- Oribatid mite example --- ### # # data(mite) data(mite.env) mite.hel <- decostand(mite, "hellinger") W<-mite.env[,4] MITE<-CascadeMRT(Y=mite.hel, VSG=mite.env[,-4], VA=data.frame(W), xvmult=500,xvsub= pick,cp1=0.1) CasMRTR2(MITE,NodeADMIT=c(3,2)) CasMRTR2 Diagram of explained variation for a cascade MRT analysis Diagram of explained variation for a cascade MRT analysis. See details for more precisions. CasMRTR2(obj,NodeADMIT=obj$where1) obj NodeADMIT Object of class CascadeMRT Vector with numbers corresponding to the group membership of the first drop to be admitted in the diagram. Default is all are included.

5 CasMRTR2 5 Details Value This diagram represents the percentage of variation explained by each drop. Explained variance of the original response is in greyed area, unexplained in is white. The rectangle representing the explained variation of the first drop MRT model is annoted VA and is placed to the left. The area is proportional to the explained percentage which is written under the VA annotation. The other greyed areas each represent a model from the second wave. Each area has a height equal to the explained variance of the model build on the node objects and a width equal to the variance unexplained in that node by the first drop. This provides a proportional area to the variation explained of the original response. Graphical output of explained variation. References Dea th, G Multivariate regression tree : a new technique for modeling species-environment relationships. Ecology 83: Ouellette, M.-H. & P. Legendre. An adjusted R^2 statistic for multivariate regression tree analysis (Manuscript). Ouellette, M.-H., P. Legendre and D. Borcard Cascade Multivariate Regression Tree: a novel approach for modelling nested explanatory sets. Methods in Ecology & Evolution 3: See Also mvpart,cascademrt Examples # Initialisation require(vegan) require(mvpart) require(mvpartwrap) require(ade4) ### -- Doubs example --- ### # # # Note that we modify the data found in ade4 to match the data # set provided with Numerical Ecology in R (Borcard et al 2011), # the data set used in the paper Ouellette, Legendre & Borcard # (2012). data(doubs) # Data importation # spe<-doubs$fish envmod<-doubs$env envmod[,1]<-envmod[,1]/10

6 6 code.tree envmod[7,1]<-36.8 envmod[,3]<-round((exp(envmod[,3])-1)/10,1) envmod[,4]<-envmod[,4]/100 envmod[,5]<-envmod[,5]/10 envmod[,7]<-envmod[,7]/100 envmod[,8]<-envmod[,8]/100 envmod[,9]<-envmod[,9]/100 envmod[,10]<-envmod[,10]/10 envmod[,11]<-envmod[,11]/10 envmod_nodas<-envmod[,-1] spe.hel <- decostand(spe, "hellinger") POISSON<-CascadeMRT(Y=spe.hel, VSG=envmod_nodas, VA=as.data.frame(envmod[,1]), xvmult=100) CasMRTR2(POISSON,NodeADMIT=3) ### -- Oribatid mite example --- ### # # data(mite) data(mite.env) mite.hel <- decostand(mite, "hellinger") W<-mite.env[,4] MITE<-CascadeMRT(Y=mite.hel, VSG=mite.env[,-4], VA=data.frame(W), xvmult=500,xvsub= pick,cp1=0.1) CasMRTR2(MITE,NodeADMIT=c(3,2)) code.tree Multivariate regression tree analysis dummy coding This function dummy codes an mvpart tree code.tree(obj,lwhere,rwhere,labels) obj LWHERE RWHERE LABELS obj of class mvpart list of left objects in every node list of right objects in every node mat_lables object

7 mat_labels_fct 7 Details This function is used internally by the plot.mrt generic function and is not intended for external use. Either way, each coded variable in matrix code represents one of the splits of the MRT. The objects on the left and right of the split have weights corresponding to the inverse of the number of observations in each group. The left objects get positive weights and the right objects get negative weights. The objects not concerned with a split have a weight of zero. As a consequence, each column sums to 0. Coded by Marie-Helene Ouellette, August 2009, modified from Pierre Legendre, August 2009 Value code Matrix representing the coded tree mat_labels_fct Builds a matrix of labels for an mvpart tree Builds a matrix of labels for an mvpart tree mat_labels_fct(obj) obj an mvpart object Value Labels Matrix with pretty labels for an mvpart tree See Also mvpart MRT

8 8 MRT MRT Modified Output of Multivariate Regression Tree Analysis Wraper function of mvpart that grant easy access to the following information : the proper cluster membership of the objects, the discriminant species of each cluster, the tree nodes at the proper level of R 2 (1 minus relative error) in the tree representation, the total species variance partitionned by species, by the tree, and by the splits of the tree. MRT(obj,percent,species=NULL,LABELS = FALSE,...) obj Details percent species LABELS An object of class mvpart The contribution level to the explained variance at a particular node for a sepcies to be considered discriminant, in percent. A vector of species names assignated to some columns of the table showing the partitioned explained variance (see TABLE1 in value). If NULL, the colnames of obj$y will be used. A matrix of labels for the tree.... further arguments given to mvpart. See rpart.control and mvpart for further details. This function provides extra outputs based on an mvpart object Value An object of class MRT, basically a list including the following elements nodes pourct R2 obj percent vector of node numbers given in increasing order of their contribution to the explained variance. These numbers correspond to the ones used in the new tree output (see argument typeplot for more details) nodes by species matrix providing the species contribution to the explained variation in percent at each node. nodes by species matrix giving the species contribution to the explained variation at each node mvpart function original object percentage of explained variation perceived as large enough for a species to be dsicriminant at a particular node

9 ORDER_NODES 9 RWHERE LWHERE TABLE1 NodeMarking List of vectors containing the row numbers of the objects on the right side of each node List of vectors containing the row numbers of the objects on the left side of each node Matrix giving the total species variation partitionned by species, by the tree, and by the splits of the tree Argument needed to build labels for plots (see plot.mrt for more details on these plots) References Dea th, G Multivariate regression tree : a new technique for modeling species-environment relationships. Ecology 83: See Also summary.mrt Examples ## MRT analysis of the spider data of the mvpart library ## # # library(mvpart) data(spider) result<-mvpart(data.matrix(spider[,1:12]) ~ herbs + reft + moss + sand + twigs + water, spider, xv= 1se, xval=10, xvmult=100) ## Format the object of class "mvpart" into "MRT" ## res<-mrt(result,10) ORDER_NODES Order mvpart nodes in terms of R^2 Order mvpart nodes in terms of R^2 for better tree output ORDER_NODES(obj,R2,splits) obj R2 splits mvpart object matrix of explained variation (objects x splits) contains the line numbers of table frame of the mvpart object that are nodes, not leafs

10 10 plot.mrt Value Vector of modes ordering in terms of R^2 See Also mvpart MRT plot.mrt Returns a graphical representation of a fitted MRT object. Two different graphical representations of the Multivariate regression tree build with MRT function: a tree or an ordination triplot (last option not available). ## S3 method for class MRT plot(x, NodeMarking=TRUE, typeplot=c( tree ), Cex=0.5, widthtree=7, heighttree=9, R2A=FALSE, X=NULL, T=NULL,...) x NodeMarking typeplot Cex widthtree heighttree R2A X T Details fitted model object of class MRT If TRUE (default), used to show proper labels in tree representation. Only option available for now. tree shows the final model in a tree shape; if NULL, none is shown Scale of character to be used in the plots Width in inches to be used in the tree plot Height in inches to be used in the tree plot logical, should the adjusted R 2 (see references) be plotted under the tree explanatory matrix, must be provided if R2A=TRUE Number of runs for GDF estimation, must be provided if R2A=TRUE... Further arguments to be passed to the plotting devices or functions. See Details for more details. This function is a method for the generic function plot for class MRT. It can be invoked by calling plot for an object of the appropriate class, or directly by calling plot.mrt regardless of the class of the object. If typeplot is tree, the model is depicted in a binary tree manner. Each node and leaf is numbered according to the information provided in the summary. See?summary.MRT for details. Under each numbered node, we find the complexity parameter or the contribution to the R 2. At the bottom of the tree, at each leaf, we find its size and a number which corresponds to the group

11 plot_tree 11 association found in MRT$where. Each node is plotted at its corresponding contribution to the global R 2. ### NOT AVAILABLE YET, COMING SOON ### The second graphical representation is one of ordination biplot or triplot. Each node is dummy coded (see code.tree) and used as explanatory variables in an redundancy analysis (RDA). The groups are numbered as in the MRT tree. The default scaling is 1, thus the eucidian distances between groups are respected as much as possible. The nodes are represented by arrows, at which is associated the name of the explanatory variable and the value at which the split is performed. References Ye, J. (1998). "On Measuring and Correcting the Effects of Data Mining and Model Selection." Journal of the American Statistical Association 93(441): Ouellette, M.-H. and Legendre, P. "An adjusted R 2 statistic for multivariate regression tree analysis". Manuscript. See Also plot,mrt,summary.mrt Examples ## MRT analysis of the Bryce Canyon vegetation data ## # # library(mvpart) data(spider) result<-mvpart(data.matrix(spider[,1:12]) ~ herbs + reft + moss + sand + twigs + water, spider, xv= 1se, xval=10, xvmult=100) ## Format the object of class "mvpart" into "MRT" ## res<-mrt(result,10) ## Summary of this object ## summary(res) plot(res) plot_tree Plot Multivariate Regression Tree Plot mvpart tree according to the relative error plot_tree(obj, NodeMarking, R2, Cex, widthtree, heighttree, LABELS, R2A=FALSE, X=NULL, T=NULL,...)

12 12 R2aGDF obj NodeMarking R2 Cex widthtree heighttree LABELS R2A X T Value mvpart object TRUE or FALSE, should the level of R 2 be printed Matrix of contribution to R 2 (object x splits) see par(cex) width of plot window height of plot window Given labels for plotting. Used in partial analysis. logical, should the adjusted R 2 (see references) be plotted under the tree explanatory matrix, must be provided if R2A=TRUE Number of runs for GDF estimation, must be provided if R2A=TRUE... Further arguments to be passed to the plotting devices or functions. See Details for more details. plotted tree (no value returned) R2aGDF Adjustment for Rˆ2 of Multivariate regression tree analysis (MRT) based on general degrees of freedom (GDF) estimation This function returns the adjusted R 2 for an MRT model R2aGDF(TREE,T,tau_const,X=NULL,...) TREE T tau_const X Details object of class MRT. The number of times the algorithm should run. constant for tuner parameter multiplicative value. explanatory matrix (must be provided when TREE is an MRT object)... further options to provided to mvpart This function performs the adjustment of the coefficient of determination for an MRT model. The adjustment is based on Ye s algorithm 1 used to estimate the number of general degrees of freedom. The adjustement itself is defined in Ouellette & Legendre (Manuscript)

13 R2aGDF 13 Value R2a Adjusted R 2 for the provided TREE References Ye, J. (1998). "On Measuring and Correcting the Effects of Data Mining and Model Selection." Journal of the American Statistical Association 93(441): Dea th, G Multivariate regression tree : a new technique for modeling species-environment relationships. Ecology 83: Ouellette, M.-H. & P. Legendre. An adjusted R 2 statistic for multivariate regression tree analysis. (Manuscript) See Also mvpart, MRT Examples # # # - MRT analysis - # # # # # require(vegan) require(labdsv) data(mite) data(mite.env) mite.hell<-decostand(mite,method= h ) # Polynomial water content WaterCont.poly = poly(mite.env[,2], 3) # All polynomial of water content are retained # (according to forward selection) mite.tree<-mvpart(data.matrix(mite.hell) ~ data.matrix(mite.env[,-2]) + WaterCont.poly, data=as.data.frame(cbind(mite.env,watercont.poly)), xv= min,xvmult=1000) # Get graphic window ready # dev.new(width=10, height=7.5) par(cex=0.4) # Get prettier tree # res<-mrt(mite.tree,10) # Make prettier lables LABELS<-res$mat_labels LABELS[1,2]<- Water.p1>= LABELS[1,3]<- Water.p1< LABELS[2,2]<- SubsDens>=51.8 LABELS[2,3]<- SubsDens<51.8

14 14 summary.mrt LABELS[3,2]<- Water.p1>= LABELS[3,3]<- Water.p1< LABELS[4,2]<- SubsDens < LABELS[4,3]<- SubsDens >=36.38 LABELS[5,2]<- Topo< 1.5 LABELS[5,3]<- Topo>= 1.5 LABELS[6,2]<- Shrub< 1.5 LABELS[6,3]<- Shrub>= 1.5 MRT.mite.tree<-MRT(mite.tree,10,LABELS=LABELS) summary(mrt.mite.tree) plot(mrt.mite.tree,type= tree ) # Show summary of results summary(mrt.mite.tree) # Calculate R2a R2aGDF(MRT.mite.tree, T=100, tau_const=0.6, X=cbind(mite.env[,-2], WaterCont.poly)) summary.mrt Returns a detailed listing of a fitted MRT object. Gives a summary of the results contained in an MRT object : output shows an overview of the information available for each node. ## S3 method for class MRT summary(object,indvalpart=true,indvalnode=true,...) object fitted model object of class MRT IndvalPART Logical. Print IndVal species for the final partition IndvalNODE Logical. Print IndVal species for each node... arguments to be passed to or from other methods.

15 summary.mrt 15 Details This function is a method for the generic function summary for class MRT. It can be invoked by calling summary for an object of the appropriate class. Dicriminant species (who contribute the most to the deviance), their mean at each subgroup formed by the split (left and right), Indval species at the node level and at the full partition level, and the complexity (contribution to R 2 ) is available. See Also summary, MRT Examples ## MRT of the spider data available in the mvpart package. ## # # require(mvpart) data(spider) result<-mvpart(data.matrix(spider[,1:12]) ~ herbs + reft + moss + sand + twigs + water, spider, xv= 1se, xval=10, xvmult=100) ## Format the object of class mvpart into MRT ## res<-mrt(result,10) ## Summary of this MRT object ## summary(res) ## This summary has the following structure ## # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # # --- Node # --- : # # corresponds to the number given on the tree plot # Complexity (r2) ## # left child right child # ~ Discriminant species : # sp1 sp2... # % of expl. deviance of## # Mean value on the left # Mean value on the right # ~ INDVAL species for this node: : left is 1, right is 2 # cluster indicator_value probability # SPA # SPB # SPC # SPD # # Note : the output will only show the species which have a higher # percent value than the one specified by the user when the MRT object # was created. See?MRT for more details

16 16 svaluecol svaluecol Representation of a value and its corresponding partition in a graph performs the scatter diagram with the representation of a value for a variable colored according to a partition given by the user svaluecol(dfxy, z, xax = 1, yax = 2, method = c("squaresize", "greylevel"), zmax=null, csize = 1, cpoint = 0, pch = 20, clegend = 0.75, neig = NULL, cneig = 1, xlim = NULL, ylim = NULL, grid = TRUE, addaxes = TRUE, cgrid = 0.75, include.origin = TRUE, origin = c(0,0), sub = "", csub = 1, possub = "topleft", pixmap = NULL, contour = NULL, area = NULL, add.plot = FALSE,col= black ) dfxy z xax yax method zmax csize cpoint pch clegend neig cneig xlim ylim grid a data frame with two coordinates a vector of the values corresponding to the rows of dfxy column for the x axis column for the y axis a string of characters "squaresize" gives black squares for positive values and white for negative values with a proportional area equal to the absolute value. "greylevel" gives squares of equal size with a grey level proportional to the value. By default the first choice a numeric value, equal by default to max(abs(z)), can be used to impose a common scale of the size of the squares to several drawings in the same device a size coefficient for symbols a character size for plotting the points, used with par("cex")*cpoint. If zero, no points are drawn if cpoint > 0, an integer specifying the symbol or the single character to be used in plotting points a character size for the legend used by par("cex")*clegend a neighbouring graph a size for the neighbouring graph lines used with par("lwd")*cneig the ranges to be encompassed by the x, if NULL they are computed the ranges to be encompassed by the y, if NULL they are computed a logical value indicating whether a grid in the background of the plot should be drawn

17 svaluecol 17 addaxes cgrid a logical value indicating whether the axes should be plotted a character size, parameter used with par("cex")*cgrid to indicate the mesh of the grid include.origin a logical value indicating whether the point "origin" should be belonged to the graph space origin sub csub possub pixmap contour area add.plot col Details Value the fixed point in the graph space, for example c(0,0) the origin axes a string of characters to be inserted as legend a character size for the legend, used with par("cex")*csub a string of characters indicating the sub-title position ("topleft", "topright", "bottomleft", "bottomright") an object pixmap displayed in the map background a data frame with 4 columns to plot the contour of the map : each row gives a segment (x1,y1,x2,y2) a data frame of class area to plot a set of surface units in contour if TRUE uses the current graphics window vector of colors to be given to each object. If black (default), performs the scatter plot without color, thus equivalent to s.value. The main difference between s.value(ade4) and svaluecol(mvpartwrap) is the possibility to color the squares representing the value of a variable according to a partition provided by the user. The argument col controls the color of each points in the scatter diagram. When this argument is a vector of colors (numbers or color names, see colors() for a complete list), each point is colored as stated by the vector. It also overrides the method options greylevel, thus only squaresize is available in this setting. In this case, squares with grey contour have a positive value and squares with black contour have a negative value. The matched call. Author(s) Marie-Helene Ouellette, modified from s.value (ade4) of Daniel Chessel Examples # Required packages # require(vegan) require(mvpart) require(mvpartwrap) # Data importation and preparation # data(mite) data(mite.env) data(mite.xy)

18 18 svaluecol mite.hel<-decostand(mite, method= h ) # Analyses and plots # kmeans.mite<-cascadekm(data.matrix(mite.hel),inf.gr=6,sup.gr=6,criterion = "calinski") # Plot of the kmeans partition on species composition (color). # # Size of square represents the water content measured at the site. # svaluecol(mite.xy,mite.env[,2],col=kmeans.mite$partition,csize=0.3)

19 Index Topic Cascade CascadeMRT, 2 CasMRTR2, 4 Topic Multivariate regression tree code.tree, 6 mat_labels_fct, 7 ORDER_NODES, 9 plot_tree, 11 R2aGDF, 12 Topic dummy coding code.tree, 6 Topic hplot svaluecol, 16 Topic multivariate CascadeMRT, 2 CasMRTR2, 4 MRT, 8 plot.mrt, 10 summary.mrt, 14 Topic partition svaluecol, 16 Topic tree CascadeMRT, 2 CasMRTR2, 4 MRT, 8 plot.mrt, 10 summary.mrt, 14 plot_tree, 11 R2aGDF, 12 summary.mrt, 9, 11, 14 svaluecol, 16 CascadeMRT, 2, 5 CasMRTR2, 3, 4 code.tree, 6 mat_labels_fct, 7 MRT, 7, 8, 10, 11, 13 mvpart, 3, 5, 7, 10, 13 ORDER_NODES, 9 plot, 11 plot.mrt, 10 19