select

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