# make.metric: Creating disparity metrics In dispRity: Measuring Disparity

 make.metric R Documentation

## Creating disparity metrics

### Description

Testing the dimension-level of disparity metrics

### Usage

``````make.metric(
fun,
...,
silent = FALSE,
check.between.groups = FALSE,
data.dim,
tree = NULL,
covar = FALSE
)
``````

### Arguments

 `fun` A `function`. `...` Some arguments to be passed to `fun`. `silent` `logical`; if `FALSE` (default), the function will be verbose and give no output; if `TRUE`, the function will only output the function's dimension-level. `check.between.groups` `logical`; if `TRUE`, the function will output a named list containing the metric level and a logical indicating whether the metric can be used between groups or not. If `FALSE` (default) the function only outputs the metric level. `data.dim` optional, two `numeric` values for the dimensions of the matrix to run the test function testing. If missing, a default 5 rows by 4 columns matrix is used. `tree` optional, a `phylo` object. `covar` `logical`, whether to treat the metric as applied the a `data\$covar` component (`TRUE`) or not (`FALSE`; default).

### Details

This function tests:

• 1: if your function can deal with a matrix as an `input`.

• 2: which dimension-level is your function (1, 2 or 3, see `dispRity.metric`).

• 3: whether the function can properly be implemented in the `dispRity` function.

The three different metric levels correspond to the dimensions of the output and are:

• "dimension-level 1": for functions that decompose a `matrix` into a single value.

• "dimension-level 2": for functions that decompose a `matrix` into a `vector`.

• "dimension-level 3": for functions that transform the `matrix` into another `matrix`.

For example, the disparity metric `sum` of `variances` is composed of two metric dimension-levels:

• The `variances` (dimension-level 2) that calculates the variances for each column in a matrix (aggregates a `matrix` into a `vector`).

• The `sum` (dimension-level 1) that transforms the `vector` of variances into a single value.

See function example for a concrete illustration (three different dimension-levels of the function `sum`).

HINT: it is better practice to name the first argument of `fun` `matrix` to avoid potential argument conflicts down the line (the `dispRity` function assumes the `matrix` argument for the parsing the metrics).

The input `fun` can be a "normal" metric function (i.e. that takes a matrix as first argument) or a "between.groups" metric (i.e. that takes two matrix as arguments). If the arguments are named `matrix` and `matrix2`, the metric will be assumed to be "between.groups" and be run in a `for` loop rather than a `apply` loop in `dispRity`.

### Author(s)

Thomas Guillerme

`dispRity`, `dispRity.metric`.

### Examples

``````## A dimension-level 1 function
my_fun <- function(matrix) sum(matrix)
make.metric(my_fun)

## A dimension-level 2 function
my_fun <- function(matrix) apply(matrix, 2, sum)
make.metric(my_fun)

## A dimension-level 3 function
my_fun <- function(matrix) (matrix + sum(matrix))
make.metric(my_fun)

``````

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