select (phytree)

Select tree branches and leaves in phytree object

Syntax

```S = select(Tree, N) [S, Selleaves, Selbranches] = select(...) select(..., 'Reference', ReferenceValue, ...) select(..., 'Criteria', CriteriaValue, ...) select(..., 'Threshold', ThresholdValue, ...) select(..., 'Exclude', ExcludeValue, ...) select(..., 'Propagate', PropagateValue, ...) ```

Arguments

 `Tree` Phylogenetic tree (`phytree` object) created with the function `phytree`. `N` Number of closest nodes to the root node. `ReferenceValue` Property to select a reference point for measuring distance. `CriteriaValue` Property to select a criteria for measuring distance. `ThresholdValue` Property to select a distance value. Nodes with distances below this value are selected. `ExcludeValue` Property to remove (exclude) branch or leaf nodes from the output. Enter `'none'`, `'branches'`, or `'leaves'`. The default value is `'none'`. `PropagateValue` Property to select propagating nodes toward the leaves or the root. `S` Logical vector for all selected nodes. `Selleaves` Logical vector for selected leaves. `Selbranches` Logical vector for selected branches.

Description

`S = select(Tree, N)` returns a logical vector (`S`) of size ```[NumNodes x 1]``` indicating the `N` closest nodes to the root node of a `phytree` object (`Tree`) where `NumNodes = NumLeaves + NumBranches`. The first criterion used is branch levels, then patristic distance (also known as tree distance). By default, `select` uses `Inf` as the value of `N`, and `select(Tree)` returns a vector with values of `true`.

```[S, Selleaves, Selbranches] = select(...)``` returns two additional logical vectors, one for the selected leaves and one for the selected branches.

```select(..., 'PropertyName', PropertyValue, ...)``` uses additional options specified as one or more name-value pair arguments. Each `PropertyName` must be enclosed in single quotation marks and is case insensitive. These name-value pairs are as follows:

``` select(..., 'Reference', ReferenceValue, ...)``` changes the reference point(s) to measure the closeness. `ReferenceValue` can be `'root'` (default) or `'leaves'` or an index that points to any node of the tree. When using `'leaves'`, a node can have multiple distances to its descendant leaves (nonultrametric tree). If so, `select` considers the minimum distance to any descendant leaf.

```select(..., 'Criteria', CriteriaValue, ...)``` changes the criteria used to measure closeness. If ```CriteriaValue = 'levels'``` (default), the first criterion is branch levels and then patristic distance. If ```CriteriaValue = 'distance'```, the first criterion is patristic distance and then branch levels.

```select(..., 'Threshold', ThresholdValue, ...)``` selects all the nodes where closeness is less than or equal to the threshold value `(ThresholdValue)`. You can use either `'Criteria'` or `'Reference'` in conjunction with this name-value pair. If `N` is not specified, then `N = Inf`. Otherwise you can limit the number of selected nodes by `N`.

```select(..., 'Exclude', ExcludeValue, ...)``` sets a postfilter which excludes all the branch nodes from `S` when ```ExcludeValue = 'branches'``` or excludes all the leave nodes when ```ExcludeValue = 'leaves'```. The default is `'none'`.

```select(..., 'Propagate', PropagateValue, ...)``` activates a postfunctionality that propagates the selected nodes to the leaves when `PropagateValue` is set to `'toleaves'` or toward the root finding a common ancestor when `PropagateValue` is set to `'toroot'`. The default value is `'none'`. `PropagateValue` may also be` 'both'`. The `'Propagate'` property acts after the `'Exclude'` name-value pair.

Examples

```% Load a phylogenetic tree created from a protein family: tr = phytreeread('pf00002.tree'); % To find close products for a given protein (e.g. vipr2_human): ind = getbyname(tr,'vipr2_human'); [sel,sel_leaves] = select(tr,'criteria','distance',... 'threshold',0.6,'reference',ind); view(tr,sel_leaves) % To find potential outliers in the tree, use [sel,sel_leaves] = select(tr,'criteria','distance',... 'threshold',.3,... 'reference','leaves',... 'exclude','leaves',... 'propagate','toleaves'); view(tr,~sel_leaves)```

Version History

Introduced before R2006a