# pdist (phytree)

Calculate pairwise patristic distances in phytree object

## Syntax

```D = pdist(Tree) [D, C] = pdist(Tree) pdist(..., 'Nodes', NodesValue, ...) pdist(..., 'Squareform', SquareformValue, ...) pdist(..., 'Criteria', CriteriaValue, ...) ```

## Arguments

 `Tree` phytree object created by `phytree` function (object constructor) or `phytreeread` function. `NodesValue` Character vector or string specifying the nodes included in the computation. Choices are `'leaves'` (default) or `'all'`. `SquareformValue` Controls the creation of a square matrix. Choices are `true` or `false` (default). `CriteriaValue` Character vector or string specifying the criteria used to relate pairs. Choices are `'distance'` (default) or `'levels'`.

## Description

`D = pdist(Tree)` returns `D`, a vector containing the patristic distances between every possible pair of leaf nodes of `Tree`, a phylogenetic tree object. The patristic distances are computed by following paths through the branches of the tree and adding the patristic branch distances originally created with the `seqlinkage` function.

The output vector `D` is arranged in the order ```((2,1), (3,1), ..., (M,1), (3,2), ..., (M,2), ..., (M,M-1))``` (the lower-left triangle of the full `M`-by-`M` distance matrix). To get the distance between the `I`th and `J`th nodes `(I > J)`, use the formula `D((J-1)*(M-J/2)+I-J)`. `M` is the number of leaves.

```[D, C] = pdist(Tree)``` returns in `C`, the index of the closest common parent nodes for every possible pair of query nodes.

```pdist(..., 'PropertyName', PropertyValue, ...)``` calls `pdist` with optional properties that use property name/property value pairs. You can specify one or more properties in any order. Each `PropertyName` must be enclosed in single quotation marks and is case insensitive. These property name/property value pairs are as follows:

``` pdist(..., 'Nodes', NodesValue, ...)``` specifies the nodes included in the computation. Choices are `'leaves'` (default) or `'all'`. When `NodesValue` is `'leaves'`, the output is ordered as before, but `M` is the total number of nodes in the tree (`NumLeaves+NumBranches`).

```pdist(..., 'Squareform', SquareformValue, ...)``` controls the creation of a square matrix. Choices are `true` or `false` (default). When `SquareformValue` is `true`, `pdist` converts the output into a square-formatted matrix, so that `D(I,J)` denotes the distance between the `I`th and the `J`th nodes. The output matrix is symmetric and has a zero diagonal.

```pdist(..., 'Criteria', CriteriaValue, ...)``` changes the criteria used to relate pairs. `CriteriaValue` can be `'distance'` (default) or `'levels'`.

## Examples

1. Read a phylogenetic tree file into a phytree object.

`tr = phytreeread('pf00002.tree')`
2. Calculate the tree distances between pairs of leaves.

`dist = pdist(tr,'nodes','leaves','squareform',true)`