Skip to contents

Run statistics on a distance matrix vs a categorical or numeric variable.

Source: R/distmat_stats.r
distmat_stats.Rd

Run statistics on a distance matrix vs a categorical or numeric variable.

Usage

distmat_stats(dm, groups, test = "adonis2", seed = 0, permutations = 999)

Arguments

dm

A dist-class distance matrix, as returned from bdiv_distmat() or stats::dist(). Required.

groups

A named vector of grouping values. The names should correspond to attr(dm, 'Labels'). Values can be either categorical or numeric. Required.

test

Permutational test for accessing significance. Options are:

  • "adonis2" - Permutational MANOVA; vegan::adonis2().

  • "mrpp" - Multiple response permutation procedure; vegan::mrpp().

  • "none" - Don't run any statistics.

Default: "adonis2"

Abbreviations are allowed.

seed

Random seed for permutations. Default: 0

permutations

Number of random permutations to use. Default: 999

Value

A data.frame with summary statistics from vegan::permustats(). The columns are:

  • .n - The size of the distance matrix.

  • .stat - The observed statistic. For mrpp, this is the overall weighted mean of group mean distances.

  • .z - The difference of observed statistic and mean of permutations divided by the standard deviation of permutations (also known as z-values). Evaluated from permuted values without observed statistic.

  • .p.val - Probability calculated by test.


R commands for reproducing the results are in $code.

See also

Other beta_diversity: bdiv_boxplot(), bdiv_corrplot(), bdiv_heatmap(), bdiv_ord_plot(), bdiv_ord_table(), bdiv_stats(), bdiv_table()

Other stats_tables: adiv_stats(), bdiv_stats(), stats_table(), taxa_stats()

Examples

    library(rbiom)
    
    hmp10        <- hmp50$clone()
    hmp10$counts <- hmp10$counts[,1:10]
    
    dm <- bdiv_distmat(hmp10, 'unifrac')
    
    distmat_stats(dm, groups = pull(hmp10, 'Body Site'))
#> # A tibble: 1 × 4
#>      .n .stat    .z .p.val
#>   <int> <dbl> <dbl>  <dbl>
#> 1    10  9.27  11.0  0.001
    
    distmat_stats(dm, groups = pull(hmp10, 'Age'))
#> # A tibble: 1 × 4
#>      .n .stat    .z .p.val
#>   <int> <dbl> <dbl>  <dbl>
#> 1    10  4.13  3.56  0.012
    
    # See the R code used to calculate these statistics:
    stats <- distmat_stats(dm, groups = pull(hmp10, 'Age'))
    stats$code
#> grouping <- groups[attr(dm, 'Labels')]
#> set.seed(0)
#> 
#> vegan::adonis2(formula = dm ~ grouping, permutations = 999) %>%
#>   vegan::permustats() %>%
#>   summary() %>%
#>   with(data.frame(.stat = statistic, .z = z, .p.val = p)) %>%
#>   tryCatch(
#>     error   = function (e) data.frame(.stat=NA, .z=NA, .p.val=NA), 
#>     warning = function (w) data.frame(.stat=NA, .z=NA, .p.val=NA) ) %>%
#>   data.frame(row.names = NULL, .n = attr(dm, 'Size'), .)