R: Clustering of components for the performances of assemblages

fit_ftree

R Documentation

Clustering of components for the performances of assemblages

Description

The function checks the inputs, then switch on different methods of component clustering according to the option opt.method. Three methods (opt.method = c("sort", "divisive", "agglomerative")) generate a hierarchical tree. The last method (opt.method = "cluster") generates a non-hierarchical tree of clustering.

Usage

fit_ftree(fobs, mOccur,
         xpr = stats::setNames(rep(1, length(fobs)),rep("a", length(fobs))),
         affectElt  = rep(1, dim(mOccur)[2]),
         opt.method = "divisive",
         opt.mean   = "amean",
         opt.model  = "byelt",
         opt.nbMax  = dim(mOccur)[2] )

Arguments

`fobs`	a numeric vector. The vector `fobs` contains the quantitative performances of assemblages.
`mOccur`	a matrix of occurrence (occurrence of elements). Its first dimension equals to `length(fobs)`. Its second dimension equals to the number of elements.
`xpr`	a vector of numerics of `length(fobs)`. The vector `xpr` contains the weight of each experiment, and the labels (in `names(xpr)`) of different experiments. The weigth of each experiment is used in the computation of the Residual Sum of Squares in the function `rss_clustering`. The used formula is `rss` if each experiment has the same weight. The used formula is `wrss` (barycenter of RSS for each experiment) if each experiment has different weights. All assemblages that belong to a given experiment should then have a same weigth. Each experiment is identified by its names (`names(xpr)`) and the RSS of each experiment is weighted by values of `xpr`. The vector `xpr` is generated by the function `stats::setNames`.
`affectElt`	a vector of integers of `length(affectElt) == dim(mOccur)[1]`, that is the number of components. The vector contains the labels of different functional clusters to which each component belongs. Each functional cluster is labelled as an integer, and each component must be identified by its name in `names(affectElt)`. The number of functional clusters defined in `affectElt` determines an a priori level of component clustering (`level <- length(unique(affectElt))`). If `affectElt = NULL` (value by default), the option `opt.method` must be filled out. A tree is built, from a unique trunk to as many leaves as components by using the specified method. If `affectElt` is specified, the option `opt.method` does not need to be filled out. `affectElt` determines an a priori level of component clustering, and a tree is built: (i) by using `opt.method = "divisive"` from the a priori defined level in tree towards as many leaves as components; (ii) by using `opt.method = "agglomerative"` from the a priori defined level in tree towards the tree trunk (all components are together withi a trivial singleton).
`opt.method`	a string that specifies the method to use. `opt.method = c("divisive", "agglomerative", "complete")`. All the methods generate a hierarchical tree. Each tree is complete, running from a unique trunk to as many leaves as components. If `opt.method = "divisive"`, the components are clustered according to a hierarchical process by using a divisive method, from the trivial cluster where all components are together, towards the clustering where each component is a cluster. If `opt.method = "agglomerative"`, the components are clustered according to a hierarchical process by using an agglomerative method, from the trivial clustering where each component is a clsuter, towards the cluster where all components are together. The method that gives the best result is `opt.method = "divisive"`. If `opt.method = "complete"`, `affectElt` must be specified. `affectElt` determines a level of component clustering, and a tree is built: (i) by using `opt.method = "divisive"` from the defined level in tree towards as many leaves as components; (ii) by using `opt.method = "agglomerative"` from the defined level in tree towards the trunk of tree.
`opt.mean`	a character equals to `"amean"` or `"gmean"`. Switchs to arithmetic formula if `opt.mean = "amean"`. Switchs to geometric formula if `opt.mean = "gmean"`. Modelled performances are computed using arithmetic mean (`opt.mean = "amean"`) or geometric mean (`opt.mean = "gmean"`) according to `opt.model`.
`opt.model`	a character equals to `"bymot"` or `"byelt"`. Switchs to simple mean by assembly motif if `opt.model = "bymot"`. Switchs to linear model with assembly motif if `opt.model = "byelt"`. If `opt.model = "bymot"`, modelled performances are means of performances of assemblages that share a same assembly motif by including all assemblages that belong to a same assembly motif. If `opt.model = "byelt"`, modelled performances are the average of mean performances of assemblages that share a same assembly motif and that contain the same components as the assemblage to predict. This procedure corresponds to a linear model within each assembly motif based on the component occurrence in each assemblage. If no assemblage contains component belonging to assemblage to predict, performance is the mean performance of all assemblages as in `opt.model = "bymot"`.
`opt.nbMax`	an integer, comprizes between 1 and nbElt, that indicates the last level of hierarchical tree to compute. This option is very useful to shorten computing-time in the test-functions `ftest_components`, `ftest_assemblages`, `ftest_performances`, `fboot_assemblages`, `fboot_performances` or `ftest` where the function `fit_ftree` is run very numerous times.

Details

None.

Value

Return a primary tree of clustering of components for their effect on the performances of component assemblages.