distance: Calculate distance, dissimilarity

In phyloseq: Handling and analysis of high-throughput microbiome census data

Description

Takes a phyloseq-class object and method option, and returns a distance object suitable for certain ordination methods and other distance-based analyses. Only sample-wise distances are currently supported (the type argument), but eventually species-wise (OTU-wise) distances may be supported as well.

Usage

distance(physeq, method, type = "samples", ...)

## S4 method for signature 'phyloseq,ANY'
distance(physeq, method)

## S4 method for signature 'otu_table,character'
distance(physeq, method,
  type = "samples", ...)

## S4 method for signature 'phyloseq,character'
distance(physeq, method, type = "samples",
  ...)

Arguments

physeq	(Required). A phyloseq-class or an otu_table-class object. The latter is only appropriate for methods that do not require any additional data (one-table). For example, the “wunifrac” option (UniFrac) requires phyloseq-class that contains both an otu_table and a phylogenetic tree (phylo).
method	(Required). A character string. Provide one of the currently supported options. See distanceMethodList for a detailed list of the supported options here, and links to accompanying documentation. Note that for the common definition of Jaccard distance using the vegan-package implementation, an additional argument is needed, with the full call having the form: distance(physeq, method = "jaccard", binary = TRUE) The following methods are implemented explicitly within the phyloseq-package, and accessed by the following method options: "unifrac" Original (unweighted) UniFrac distance, UniFrac "wunifrac" weighted-UniFrac distance, UniFrac "dpcoa" sample-wise distance used in Double Principle Coordinate Analysis, DPCoA "jsd" Jensen-Shannon Divergence, JSD Alternatively, you can provide a character string that defines a custom distance method, if it has the form described in designdist.
type	(Optional). A character string. The type of pairwise comparisons being calculated: sample-wise or taxa-wise. The default is c("samples").
...	Additional arguments passed on to the appropriate distance function, determined by the method argument.

Details

Depending on the method argument, distance() wraps one of UniFrac, DPCoA, JSD, vegdist, betadiver, designdist, or dist.

Value

An object of class “dist” suitable for certain ordination methods and other distance-based analyses.

See Also

plot_ordination, UniFrac, DPCoA, JSD, vegdist, betadiver, designdist, dist.

Examples

data(esophagus)
distance(esophagus, "uunifrac") # Unweighted UniFrac
distance(esophagus, "wunifrac") # weighted UniFrac
distance(esophagus, "jaccard", binary = TRUE) # vegdist jaccard
distance(esophagus, "gower") # vegdist option "gower"
distance(esophagus, "g") # designdist method option "g"
distance(esophagus, "minkowski") # invokes a method from the base dist() function.
distance(esophagus, "(A+B-2*J)/(A+B)") # designdist custom distance
distanceMethodList
help("distance")

Example output

          B         C
C 0.5175550          
D 0.5182284 0.5422394
          B         C
C 0.2035424          
D 0.2603371 0.2477016
          B         C
C 0.6136364          
D 0.6250000 0.6078431
          B         C
C 0.6405552          
D 0.5947623 0.7301998
          B         C
C 0.6136364          
D 0.6250000 0.6078431
         B        C
C 50.21952         
D 88.26098 96.81942
          B         C
C 0.4426230          
D 0.4545455 0.4366197
$UniFrac
[1] "unifrac"  "wunifrac"

$DPCoA
[1] "dpcoa"

$JSD
[1] "jsd"

$vegdist
 [1] "manhattan"  "euclidean"  "canberra"   "bray"       "kulczynski"
 [6] "jaccard"    "gower"      "altGower"   "morisita"   "horn"      
[11] "mountford"  "raup"       "binomial"   "chao"       "cao"       

$betadiver
 [1] "w"   "-1"  "c"   "wb"  "r"   "I"   "e"   "t"   "me"  "j"   "sor" "m"  
[13] "-2"  "co"  "cc"  "g"   "-3"  "l"   "19"  "hk"  "rlb" "sim" "gl"  "z"  

$dist
[1] "maximum"   "binary"    "minkowski"

$designdist
[1] "ANY"

Help on topic 'distance' was found in the following packages:

  Package               Library
  phyloseq              /usr/local/lib/R/site-library
  IRanges               /usr/local/lib/R/site-library


Using the first match ...
distance               package:phyloseq                R Documentation

_C_a_l_c_u_l_a_t_e _d_i_s_t_a_n_c_e, _d_i_s_s_i_m_i_l_a_r_i_t_y

_D_e_s_c_r_i_p_t_i_o_n:

     Takes a 'phyloseq-class' object and method option, and returns a
     'dist'ance object suitable for certain ordination methods and
     other distance-based analyses.  Only sample-wise distances are
     currently supported (the 'type' argument), but eventually
     species-wise (OTU-wise) distances may be supported as well.

_U_s_a_g_e:

     distance(physeq, method, type = "samples", ...)
     
     ## S4 method for signature 'phyloseq,ANY'
     distance(physeq, method)
     
     ## S4 method for signature 'otu_table,character'
     distance(physeq, method, type = "samples",
       ...)
     
     ## S4 method for signature 'phyloseq,character'
     distance(physeq, method, type = "samples", ...)
     
_A_r_g_u_m_e_n_t_s:

  physeq: (Required).  A 'phyloseq-class' or an 'otu_table-class'
          object. The latter is only appropriate for methods that do
          not require any additional data (one-table).  For example,
          the ``wunifrac'' option ('UniFrac') requires 'phyloseq-class'
          that contains both an 'otu_table' and a phylogenetic tree
          ('phylo').

  method: (Required). A character string.  Provide one of the currently
          supported options.  See 'distanceMethodList' for a detailed
          list of the supported options here, and links to accompanying
          documentation.

          Note that for the common definition of 'Jaccard' distance
          using the 'vegan-package' implementation, an additional
          argument is needed, with the full call having the form:
          'distance(physeq, method = "jaccard", binary = TRUE)'

          The following methods are implemented explicitly within the
          'phyloseq-package', and accessed by the following 'method'
          options:

          '"unifrac"' Original (unweighted) UniFrac distance, 'UniFrac'

          '"wunifrac"' weighted-UniFrac distance, 'UniFrac'

          '"dpcoa"' sample-wise distance used in Double Principle
              Coordinate Analysis, 'DPCoA'

          '"jsd"' Jensen-Shannon Divergence, 'JSD'

          Alternatively, you can provide a character string that
          defines a custom distance method, if it has the form
          described in 'designdist'.

    type: (Optional). A character string. The type of pairwise
          comparisons being calculated: sample-wise or taxa-wise. The
          default is 'c("samples")'.

     ...: Additional arguments passed on to the appropriate distance
          function, determined by the 'method' argument.

_D_e_t_a_i_l_s:

     Depending on the 'method' argument, 'distance()' wraps one of
     'UniFrac', 'DPCoA', 'JSD', 'vegdist', 'betadiver', 'designdist',
     or 'dist'.

_V_a_l_u_e:

     An object of class ``'dist''' suitable for certain ordination
     methods and other distance-based analyses.

_S_e_e _A_l_s_o:

     'plot_ordination', 'UniFrac', 'DPCoA', 'JSD', 'vegdist',
     'betadiver', 'designdist', 'dist'.

_E_x_a_m_p_l_e_s:

     data(esophagus)
     distance(esophagus, "uunifrac") # Unweighted UniFrac
     distance(esophagus, "wunifrac") # weighted UniFrac
     distance(esophagus, "jaccard", binary = TRUE) # vegdist jaccard
     distance(esophagus, "gower") # vegdist option "gower"
     distance(esophagus, "g") # designdist method option "g"
     distance(esophagus, "minkowski") # invokes a method from the base dist() function.
     distance(esophagus, "(A+B-2*J)/(A+B)") # designdist custom distance
     distanceMethodList
     help("distance")
     

phyloseq documentation built on Nov. 8, 2020, 6:41 p.m.