# dispRity: Calculates disparity from a matrix. In dispRity: Measuring Disparity

 dispRity R Documentation

## Calculates disparity from a matrix.

### Description

Calculates disparity from a matrix, a list of matrices or subsets of a matrix, where the disparity metric can be user specified.

### Usage

``````dispRity(
data,
metric,
dimensions = NULL,
...,
between.groups = FALSE,
verbose = FALSE,
tree = NULL
)
``````

### Arguments

 `data` A matrix or a `dispRity` object (see details). `metric` A vector containing one to three functions. At least of must be a dimension-level 1 or 2 function (see details). `dimensions` Optional, a vector of `numeric` value(s) or the proportion of the dimensions to keep. `...` Optional arguments to be passed to the metric. `between.groups` A `logical` value indicating whether to run the calculations between groups (`TRUE`) or not (`FALSE` - default) or a `numeric` list of pairs of groups to run (see details). `verbose` A `logical` value indicating whether to be verbose or not. `tree` `NULL` (default) or an optional `phylo` or `multiPhylo` object to be attached to the data. If this argument is not null, it will be recycled by `metric` when possible.

### Details

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 dimension-level from 3 to 1 (see `dispRity.metric` and `make.metric`). Typically dimension-level 3 functions take a `matrix` and output a `matrix`; dimension-level 2 functions take a `matrix` and output a `vector` and dimension-level 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 dimension-level (i.e. 3, 2 and finally 1). Note that the functions can only take one metric of each dimension-level 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 dimension-level 3 functions - the correlation of the variance-covariance 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).

### Value

This function outputs a `dispRity` object containing at least the following:

 `matrix` the multidimensional space (a list of `matrix`). `call` A `list` containing the called arguments. `subsets` A `list` containing matrices pointing to the elements present in each subsets. `disparity` A `list` containing the disparity in each subsets.

Use summary.dispRity to summarise the `dispRity` object.

### Author(s)

Thomas Guillerme

`custom.subsets`, `chrono.subsets`, `boot.matrix`, `dispRity.metric`, `summary.dispRity`, `plot.dispRity`.

### Examples

``````## 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 dimension-levels
## 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 dimension-level 1 has no quantiles
summary(disparity_level2)
summary(disparity_level1)

``````

dispRity documentation built on May 29, 2024, 9:40 a.m.