dispRity.covar.projections: Covar projection analyses wrapper

In TGuillerme/dispRity: Measuring Disparity

Covar projection analyses wrapper

Description

Wrapper function for a covar projection analyses on dispRity objects

Usage

dispRity.covar.projections(
  data,
  type,
  base,
  sample,
  n,
  major.axis = 1,
  level = 0.95,
  output = c("position", "distance", "degree"),
  inc.base = FALSE,
  ...,
  verbose = FALSE
)

Arguments

data	a dispRity object containing a $covar component(e.g. from MCMCglmm.subsets)
type	either "groups" for the projections between groups or "elements" for the projections of elements onto groups.
base	optional, a specific group to project the elements or the groups onto or a list of pairs of groups to compare (see between.groups argument in dispRity). If left empty, the groups are projected onto each other in a pairwise manner and the elements are projected onto their respective groups.
sample	optional, one or more specific posterior sample IDs (is ignored if n is used) or a function to summarise all axes.
n	optional, a random number of covariance matrices to sample (if left empty, all are used).
major.axis	which major axis to use (default is 1; see axis.covar for more details).
level	the confidence interval to estimate the major axis (default is 0.95; see axis.covar for more details)).
output	which values to output from the projection. By default, the three values c("position", "distance", "degree") are used to respectively output the projection, rejection and angle values (see projections for more details). The argument "orthogonality" can also be added to this vector.
inc.base	logical, when using type = "elements" with a supplied base argument, whether to also calculate the projections for the base group (TRUE) or not (FALSE; default).
...	any optional arguments to pass to projections (such as centre or abs). NOTE that this function uses by default centre = TRUE and abs = TRUE which are not the defaults for projections.
verbose	logical, whether to be verbose (TRUE) or not (FALSE, default).

Details

Effectively, the wrapper runs either of the following function (simplified here):

• if type = "groups": dispRity(data, metric = as.covar(projections.between), between.groups = TRUE, ) for the projections group in data onto each other.

• if type = "elements": dispRity(data, metric = as.covar(projections), ...) for the projections of each element in data onto their main axis.

If base is specified:

• type = "groups" will run pairs elements each subset and base (instead of the full pairwise analyses).

• type = "elements" will run the projection of each subset onto the major axis from base rather than its own.

Value

A list of class "dispRity" and "projection" which contains dispRity objects corresponding to each projection value from output. The elements of the list can be accessed and analysed individually by selecting them by name (e.g. output$position) or by ID (e.g. output[[1]]). Alternatively, the list can be summarised and plotted using summary.dispRity plot.dispRity.

Author(s)

Thomas Guillerme

References

Guillerme T, Bright JA, Cooney CR, Hughes EC, Varley ZK, Cooper N, Beckerman AP, Thomas GH. 2023. Innovation and elaboration on the avian tree of life. Science Advances. 9(43):eadg1641.

See Also

projections projections.between axis.covar dispRity MCMCglmm.subsets

Examples

data(charadriiformes)

## Creating a dispRity object with a covar component
my_covar <-MCMCglmm.subsets(
                 data       = charadriiformes$data,
                 posteriors = charadriiformes$posteriors,
                 tree       = charadriiformes$tree,
                 group      = MCMCglmm.levels(
                                 charadriiformes$posteriors)[1:4],
                 rename.groups = c("gulls", "plovers", "sandpipers", "phylo"))

## Running a projection analyses between groups (on 100 random samples)
between_groups <- dispRity.covar.projections(my_covar, type = "groups", base = "phylo", n = 100)
## Summarising the results
summary(between_groups)

## Measuring the projection of the elements on their own average major axis
elements_proj <- dispRity.covar.projections(my_covar, type = "elements", sample = mean,
                                            output = c("position", "distance"))
## Visualising the results
plot(elements_proj)

## Visualising the correlation
plot(elements_proj, speicfic.args = list(correlation.plot = c("position", "distance")))

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