ecodive (version 2.2.2)

list_metrics: Find and Browse Available Metrics

Description

Programmatic access to the lists of available metrics, and their associated functions.

Usage

list_metrics(
  div = c(NA, "alpha", "beta"),
  val = c("data.frame", "list", "func", "id", "name", "div", "phylo", "weighted",
    "int_only", "true_metric"),
  nm = c(NA, "id", "name"),
  phylo = NULL,
  weighted = NULL,
  int_only = NULL,
  true_metric = NULL
)
match_metric(
  metric,
  div = NULL,
  phylo = NULL,
  weighted = NULL,
  int_only = NULL,
  true_metric = NULL
)

Value

match_metric()

A list with the following elements.

• name : Metric name, e.g. "Faith's Phylogenetic Diversity"

• id : Metric ID - also the name of the function, e.g. "faith"

• div : Either "alpha" or "beta".

• phylo : TRUE if metric requires a phylogenetic tree; FALSE otherwise.

• weighted : TRUE if metric takes relative abundance into account; FALSE if it only uses presence/absence.

• int_only : TRUE if metric requires integer counts; FALSE otherwise.

• true_metric : TRUE if metric is a true metric and satisfies the triangle inequality; FALSE if it is a non-metric dissimilarity; NA for alpha diversity metrics.

• func : The function for this metric, e.g. ecodive::faith

• params : Formal args for func, e.g. c("counts", "tree", "cpus")

list_metrics()

The returned object's type and values are controlled with the val and nm arguments.

• val = "data.frame" : The data.frame from which the below options are sourced.

• val = "list" : A list of objects as returned by match_metric() (above).

• val = "func" : A list of functions.

• val = "id" : A character vector of metric IDs.

• val = "name" : A character vector of metric names.

• val = "div" : A character vector "alpha" and/or "beta".

• val = "phylo" : A logical vector indicating which metrics require a tree.

• val = "weighted" : A logical vector indicating which metrics take relative abundance into account (as opposed to just presence/absence).

• val = "int_only" : A logical vector indicating which metrics require integer counts.

• val = "true_metric" : A logical vector indicating which metrics are true metrics and satisfy the triangle inequality, which work better for ordinations such as PCoA.

If nm is set, then the names of the vector or list will be the metric ID (nm="id") or name (nm="name"). When val="data.frame", the names will be applied to the rownames() property of the data.table.

Arguments

div, phylo, weighted, int_only, true_metric

Consider only metrics matching specific criteria. For example, div = "alpha" will only return alpha diversity metrics. Default: NULL

val

Sets the return value for this function call. See "Value" section below. Default: "data.frame"

nm

What value to use for the names of the returned object. Default is "id" when val is "list" or "func", otherwise the default is NA (no name).

metric

The name of an alpha/beta diversity metric to search for. Supports partial matching. All non-alpha characters are ignored.

Examples

    # A data.frame of all available metrics.
    head(list_metrics())
    
    # All alpha diversity function names.
    list_metrics('alpha', val = 'id')
    
    # Try to find a metric named 'otus'.
    m <- match_metric('otus')
    
    # The result is a list that includes the function.
    str(m)