Package 'paco'

Principal Coordinates analysis of phylogenetic distance matrices

Description

Translates the distance matrices of 'host' and 'parasite' phylogenies into Principal Coordinates, as needed for Procrustes superimposition.

Usage

add_pcoord(D, correction = "none")

Arguments

D

A list with objects H, P, and HP, as returned by paco::prepare_paco_data.

correction

In some cases, phylogenetic distance matrices are non-Euclidean which generates negative eigenvalues when those matrices are translated into Principal Coordinates. There are several methods to correct negative eigenvalues. Correction options available here are "cailliez", "lingoes", and "none". The "cailliez" and "lingoes" corrections add a constant to the eigenvalues to make them non-negative. Default is "none".

Value

The list that was input as the argument ‘D’ with four new elements; the Principal Coordinates of the ‘host’ distance matrix and the Principal Coordinates of the ‘parasite’ distance matrix, as well as, a ‘correction’ object stating the correction used for negative eigenvalues and a ‘note’ object stating whether or not negative eigenvalues were present and therefore corrected.

Note

To find the Principal Coordinates of each distance matrix, we internally a modified version of the function ape::pcoa that uses vegan::eigenvals and zapsmall

Examples

data(gopherlice)
library(ape)
gdist <- cophenetic(gophertree)
ldist <- cophenetic(licetree)
D <- prepare_paco_data(gdist, ldist, gl_links)
D <- add_pcoord(D)

---

Gopher-lice interactions

Description

One part of example data. The associations between pocket gophers and their chewing lice ectoparasites.

Usage

data(gopherlice)

---

Gopher phylogeny

Description

One part of example data. The phylogeny of pocket gophers.

Usage

data(gopherlice)

---

Lice phylogeny

Description

One part of example data. The phylogeny of chewing lice.

Usage

data(gopherlice)

---

Performs PACo analysis.

Description

Two sets of Principal Coordinates are superimposed by Procrustes superimposition. The sum of squared residuals of this superimposition give an indication of how congruent the two datasets are. For example, in a biological system the two sets of Principal Coordinates can be composed from the phylogenetic distance matrices of two interacting groups. The congruence measured by PACo indicates how concordant the two phylogenies are based on observed ecological interactions between them.

Usage

PACo(
  D,
  nperm = 1000,
  seed = NA,
  method = "r0",
  symmetric = FALSE,
  proc.warnings = TRUE,
  shuffled = FALSE
)

Arguments

D	A list of class paco as returned by paco::add_pcoord which includes Principal Coordinates for both phylogenetic distance matrices.
nperm	The number of permutations to run. In each permutation, the network is randomized following the method argument and phylogenetic congruence between phylogenies is reassessed.
seed	An integer with which to begin the randomizations. If the same seed is used the randomizations will be the same and results reproducible. If NA a random seed is chosen.
method	The method with which to permute association matrices: "r0", "r1", "r2", "c0", "swap", "quasiswap", "backtrack", "tswap", "r00". Briefly, "r00" produces the least conservative null model as it only maintains total fill (i.e., total number of interactions). "r0" and "c0" maintain the row sums and column sums, respectively, as well as the total number of interactions. "backtracking" and any of the "swap" algorithms conserve the total number of interactions in the matrix, as well as both row and column sums. Finally, "r1" and "r2" conserve the row sums, the total number of interactions, and randomize based on observed interaction frequency. See vegan::commsim for more details.
symmetric	Logical. Whether or not to use the symmetric Procrustes statistic, or not. When TRUE, the symmetric statistic is used. When FALSE, the asymmetric is used. A decision on which to use is based on whether one group is assumed to track the evolution of the other, or not.
proc.warnings	Logical. Make any warnings from the Procrustes superimposition callable. If TRUE, any warnings are viewable with the warnings() command. If FALSE, warnings are internally suppressed. Default is TRUE
shuffled	Logical. Return the Procrustes sum of squared residuals for every permutation of the network. When TRUE, the Procrustes statistic of all permutations is returned as a vector. When FALSE, they are not returned.

Value

A paco object that now includes (alongside the Principal Coordinates and input distance matrices) the PACo sum of sqaured residuals, a p-value for this statistic, and the PACo statistics for each randomisation of the network if shuffled=TRUE in the PACo call.

Note

Any call of PACo in which the distance matrices have differing dimensions (i.e., different numbers of tips of the two phylogenies) will produce warnings from the vegan::procrustes function. These warnings require no action by the user but are merely letting the user know that, as the distance matrices had differing dimensions, their Principal Coordinates have differing numbers of columns. vegan::procrustes deals with this internally by adding columns of zeros to the smaller of the two until the are the same size.

Examples

data(gopherlice)
require(ape)
gdist <- cophenetic(gophertree)
ldist <- cophenetic(licetree)
D <- prepare_paco_data(gdist, ldist, gl_links)
D <- add_pcoord(D)
D <- PACo(D, nperm=10, seed=42, method="r0")
print(D$gof)

---

Contribution of individual links

Description

Uses a jackknife procedure to perform bias correction on procrustes residuals (i.e. interactions) that are indicative of the degree to which individual interactions are more supportive of a hypothesis of phylogenetic congruence than others. Interactions are iteratively removed, the global fit of the two phylogenies is reassessed and bias in observed residuals calculated and corrected.

Usage

paco_links(D, .parallel = FALSE, proc.warnings = TRUE)

Arguments

D	A list of class paco as returned by paco::PACo.
.parallel	If TRUE, calculate the jackknife contribution in parallel using the backend provided by foreach.
proc.warnings	As in PACo. If TRUE, any warnings produced by internal calls of paco::PACo will be available for the user to view. If FALSE, warnings are internally suppressed.

Value

The input list of class paco with the added object jackknife which contains the bias-corrected residual for each link.

Examples

data(gopherlice)
require(ape)
gdist <- cophenetic(gophertree)
ldist <- cophenetic(licetree)
D <- prepare_paco_data(gdist, ldist, gl_links)
D <- add_pcoord(D)
D <- PACo(D, nperm=10, seed=42, method="r0")
D <- paco_links(D)

---

Prepares the data (distance matrices and association matrix) for PACo analysis

Description

Simple wrapper to make sure that the matrices are sorted accordingly and to group them together into a paco object (effectively a list) that is then passed to the remaining steps of PACo analysis.

Usage

prepare_paco_data(H, P, HP)

Arguments

H	Host distance matrix. This is the distance matrix upon which the other will be superimposed. We term this the host matrix in reference to the original cophylogeny studies between parasites and their hosts, where parasite evolution was thought to track host evolution hence why the parasite matrix is superimposed on the host.
P	Parasite distance matrix. The distance matrix that will be superimposed on the host matrix. As mentioned above, this is the group that is assumed to track the evolution of the other.
HP	Host-parasite association matrix, hosts in rows. This should be a binary matrix. If host species aren't in the rows, the matrix will be translated internally.

Value

A list with objects H, P, HP to be passed to further functions for PACo analysis.

Examples

data(gopherlice)
library(ape)
gdist <- cophenetic(gophertree)
ldist <- cophenetic(licetree)
D <- prepare_paco_data(gdist, ldist, gl_links)

---

Return Procrustes residuals from a paco object

Description

Takes the Procrustes object from vegan::procrustes of the global superimpostion and pulls out either the residual matrix of superimposition or the residual of each individual interaction (link between host and parasite).

Usage

residuals_paco(object, type = "interaction")

Arguments

object	An obejct of class procrustes as returned from PACo (and internally the vegan::procrustes function). In a PACo output this is D\$proc.
type	Character string. Whether the whole residual matrix (matrix) or the residuals per interaction (interaction) is desired.

Value

If type=interaction, a named vector of the Procrustes residuals is returned where names are the interactions. If type=matrix, a matrix of residuals from Procrustes superimposition is returned.

Examples

data(gopherlice)
library(ape)
gdist <- cophenetic(gophertree)
ldist <- cophenetic(licetree)
D <- prepare_paco_data(gdist, ldist, gl_links)
D <- add_pcoord(D, correction='cailliez')
D <- PACo(D, nperm=100, seed=42, method='r0')
residuals_paco(D$proc)

---