dispRity  R Documentation 
Calculates disparity from a matrix, a list of matrices or subsets of a matrix, where the disparity metric can be user specified.
dispRity(
data,
metric,
dimensions = NULL,
...,
between.groups = FALSE,
verbose = FALSE,
tree = NULL
)
data 
A matrix or a 
metric 
A vector containing one to three functions. At least of must be a dimensionlevel 1 or 2 function (see details). 
dimensions 
Optional, a vector of 
... 
Optional arguments to be passed to the metric. 
between.groups 
A 
verbose 
A 
tree 

The dispRity
object given to the data
argument can be: a list of matrices (typically output from the functions chrono.subsets
or custom.subsets
), a bootstrapped matrix output from boot.matrix
, a list of disparity measurements calculated from the dispRity
function or a matrix
object with rows as elements and columns as dimensions. In any of these cases, the data is considered as the multidimensional space and is not transformed (e.g. if ordinated with negative eigen values, no correction is applied to the matrix).
metric
should be input as a vector of functions.
The functions are sorted and used by dimensionlevel from 3 to 1 (see dispRity.metric
and make.metric
).
Typically dimensionlevel 3 functions take a matrix
and output a matrix
; dimensionlevel 2 functions take a matrix
and output a vector
and dimensionlevel 1 functions take a matrix
or a vector
and output a single value.
When more than one function is input, they are treated first by dimensionlevel (i.e. 3, 2 and finally 1).
Note that the functions can only take one metric of each dimensionlevel and thus can only take a maximum of three arguments!
Some metric functions are built into the dispRity
package: see dispRity.metric
For user specified metrics, please use make.metric
to ensure that the metric will work.
HINT: if using more than three functions you can always create your own function that uses more than one function (e.g. my_function < function(matrix) cor(var(matrix))
is perfectly valid and allows one to use two dimensionlevel 3 functions  the correlation of the variancecovariance matrix in this case).
The between.groups
argument runs the disparity between groups rather within groups. If between.groups = TRUE
, the disparity will be calculated using the following inputs:
if the input is an output from custom.subsets
, the series are run in a pairwise manner using metric(matrix, matrix2)
. For example for a custom.subset
contains 3 subsets m1, m2 and m3, the code loops through: metric(m1, m2)
, metric(m2, m3)
and metric(m1, m3)
(looping through list(c(1,2), c(2,3), c(3,1))
).
if the input is an output from chrono.subsets
, the series are run in a paired series manner using metric(matrix, matrix2)
. For example for a chrono.subsets
contains 3 subsets m1, m2, m3 and m4, the code loops through: metric(m1, m2)
and metric(m2, m3)
(looping through list(c(1,2), c(2,3), c(3,4))
).
In both cases it is also possible to specify the input directly by providing the list to loop through. For example using between.groups = list(c(1,2), c(2,1), c(4,8))
will apply the metric
to the 1st and 2nd subsets, the 2nd and first and the 4th and 8th (in that specific order).
This function outputs a dispRity
object containing at least the following:
matrix 
the multidimensional space (a list of 
call 
A 
subsets 
A 
disparity 
A 
Use summary.dispRity to summarise the dispRity
object.
Thomas Guillerme
custom.subsets
, chrono.subsets
, boot.matrix
, dispRity.metric
, summary.dispRity
, plot.dispRity
.
## Load the Beck & Lee 2014 data
data(BeckLee_mat50)
## Calculating the disparity as the sum of variances from a single matrix
sum_of_variances < dispRity(BeckLee_mat50, metric = c(sum, variances))
summary(sum_of_variances)
## Bootstrapping this value
bootstrapped_data < boot.matrix(BeckLee_mat50, bootstraps = 100)
dispRity(bootstrapped_data, metric = c(sum, variances))
## Calculating the disparity from a customised subset
## Generating the subsets
customised_subsets < custom.subsets(BeckLee_mat50,
list(group1 = 1:(nrow(BeckLee_mat50)/2),
group2 = (nrow(BeckLee_mat50)/2):nrow(BeckLee_mat50)))
## Bootstrapping the data
bootstrapped_data < boot.matrix(customised_subsets, bootstraps = 100)
## Calculating the sum of variances
sum_of_variances < dispRity(bootstrapped_data, metric = c(sum, variances))
summary(sum_of_variances)
## Calculating disparity with different metrics of different dimensionlevels
## Disparity is calculated as the distribution of the variances in each
## dimension (output are distributions)
disparity_level2 < dispRity(BeckLee_mat50, metric = variances)
## Disparity is calculated as the mean of the variances in each dimension
## (output are single values)
disparity_level1 < dispRity(disparity_level2, metric = mean)
## Both disparities have the same means but dimensionlevel 1 has no quantiles
summary(disparity_level2)
summary(disparity_level1)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.