make.metric: Creating disparity metrics
In TGuillerme/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,
  get.help = 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).
`get.help`	`logical`, whether to also output the `dist.helper` if the metric has a `dist.help` argument (`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

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)

TGuillerme/dispRity documentation built on Dec. 21, 2024, 4:05 a.m.