MGT::TaxaTree::TaxaNode Class Reference

List of all members.

Public Member Functions
def	setDebugOnUpdate
def	unsetDebugOnUpdate
def	__init__
def	__getstate__
def	setParent
def	removeChild
def	lineage
def	lineageWhile
def	findLeftRankInLineage
def	visitDepthTop
def	iterDepthTop
def	iterDepthTwice
def	iterFillUp
def	visitDepthBottom
def	visitDepthTwice
def	getDepth
def	setDepth
def	setIndex
def	makePropArrayZeros
def	setPropArrayFromAttrib
def	setPropArrayFromFunc
def	setTotal
def	setReduction
def	setMaxSubtreeRank
def	setAttribute
def	isSubnode
def	isUnder
def	whichSupernode
def	lcsNode
def	lcsNodeMany
def	setIsUnderUnclass

---

Detailed Description

Node of a taxonomy tree.

---

Constructor & Destructor Documentation

def MGT::TaxaTree::TaxaNode::__init__	(		self,
			kw
	)

Ctor.
All parameters are optional keyword arguments, which will be assigned w/o any further processing.
Currently valid arguments:
@param id Node unique id
@param rank Rank of this node. Describes vertical division of the tree such as with "species,genus,order,class,..."
@param divid NCBI division id. Groups nodes, typically horizontally (bacterial, phage,...)
@param name official name of the node
@param names dict for other names "name type" -> "name"

This constructor can be used w/o any arguments to create an empty object, which is then initialized by a
data loading procedure and linked into the tree with self.setParent(). Alternatively, it can be initialized
by the caling code by supplying keyword arguments, and then linked by self.setParent()

---

Member Function Documentation

def MGT::TaxaTree::TaxaNode::__getstate__

(

self )

Pickling support - exclude node cross references to improve memory and performance 100x.
The TaxaTree constructor can restore the internal tree structure from remaining data.
The TaxaTreeIO.NodeStoragePickle relies on this.

def MGT::TaxaTree::TaxaNode::findLeftRankInLineage	(		self,
			ranks,
			topNode = None
	)

Return a node corresponding to the left-most element from 'ranks' found in the lineage

def MGT::TaxaTree::TaxaNode::getDepth

(

self )

Return distance to the top of the tree.
Depth must be precalculated for each node by a call to TaxaTree.setDepth().

def MGT::TaxaTree::TaxaNode::isSubnode	(		self,
			other
	)

Return true if this node is a descendant of the other node.
Uses pre-computed nested sets indexes, which must be up-to-date.
@note A node is not considered a subnode of itself - see isUnder() for this.

def MGT::TaxaTree::TaxaNode::isUnder	(		self,
			other,
			withSelf = False
	)

Return true if this node is a descendant of the other node or the other node itself.
Uses pre-computed nested sets indexes, which must be up-to-date.

def MGT::TaxaTree::TaxaNode::iterDepthTop

(

self )

Return depth-first top-to-bottom iterator.

def MGT::TaxaTree::TaxaNode::iterDepthTwice

(

self )

Return depth-first on-entry+on-exit iterator (modified preorder).
Dereferencing the iterator yields (node,visit) tuple, where visit is either 1 or 2 according to the time that we visit this node.
See setNestedSetsIndex() method for application example.

def MGT::TaxaTree::TaxaNode::iterFillUp	(		self,
			topNode = None,
			topFirst = False
	)

Iterate as though we were pouring water into this node until it fills a given super-tree above it.
@param topNode - "fill up" up to this super-node (inclusive), None means up to root node.
@param topFirst - if True, the top node of each super-tree will be iterated before its sub-nodes, otherwise - after ("self" is always iterated first).

def MGT::TaxaTree::TaxaNode::lcsNode	(		self,
			other
	)

Return the Lowest Common SuperNode of self and other

def MGT::TaxaTree::TaxaNode::lcsNodeMany	(		self,
			others
	)

Return the Lowest Common SuperNode of self and a sequence other nodes

def MGT::TaxaTree::TaxaNode::lineage	(		self,
			topNode = None
	)

Return a list of nodes comprising this nodes' lineage (from bottom to top, including this node).
Setting the value of 'topNode' to some existing node allows to stop the lineage construction
at the root of some sub-tree. If some node that is not in the lineage of this node is 
provided as 'topNode', the function will raise an AttributeError when it reaches the root node
and tries to access its parent.

def MGT::TaxaTree::TaxaNode::lineageWhile	(		self,
			condition
	)

Return lineage that is cut as soon as an attempt is made to look above the root note or condition(node) returns False.
Can possibly return an empty list.
Condition is always called with a valid node argument.

def MGT::TaxaTree::TaxaNode::makePropArrayZeros	(		self,
			dtype
	)

Return (self.lind,numpy.zeros(number of nodes in subtree)).

def MGT::TaxaTree::TaxaNode::removeChild	(		self,
			child
	)

Remove a child by clearing both parent and child links

def MGT::TaxaTree::TaxaNode::setAttribute	(		self,
			name,
			value,
			doCopy = False
	)

Assign an attribute to every node in a subtree.
@param name Name of attribute
@param value Value, the same for every node
@param doCopy If True, assign copy.copy(value) to every node - 
in case we assigning an empty list that we later want to modify independently for every node

def MGT::TaxaTree::TaxaNode::setDebugOnUpdate

(

hook )

Sets new debugging hook to call on attribute update.
@param hook - unbound function with signature f(node,name,value) where
name is attribute name and value is its new value.
@return previous hook function (or None), which can be stored by the caller and
used later to restore the original behavior.

def MGT::TaxaTree::TaxaNode::setDepth	(		self,
			depth
	)

Recursively set depth for this node and its subtree.

def MGT::TaxaTree::TaxaNode::setIndex	(		self,
			startIndex = 0
	)

Index nodes in a subtree in a depth first traversal order.
For each node in a subtree, set attribute lind is the index of the node itself, 
attribute rind is the maximum plus one
index of all nodes in a subtree, including the top node. Index starts at startIndex
and only incremented when node is entered the first time in depth first traversal.
Thus, for any subtree starting at some node, it is easy to create an attribute map as
a dense (Numpy) array: a = numpy.zeros(top.rind - top.lind); a[node.lind-top.lind] = value.
It also makes it easy and fast to work with any subtree below the node:
sub_a = a[sub_top.lind-top.lind:sub_top.rind-top.lind]
sub_a will densely list all values for nodes below the sub_top, with elements accessed as
sub_a[node.lind-sub_top.lind].

def MGT::TaxaTree::TaxaNode::setIsUnderUnclass

(

self )

Set an attribute 'isUnderUnclass' for the nodes in this branch.
It flags all nodes that have "unclassified" super-node somewhere in their lineage
up to this node including. This node will be marked only if it isUnclassifed().

def MGT::TaxaTree::TaxaNode::setMaxSubtreeRank

(

self )

Set an attribute "rank_max" in every node of this subtree that is a highest standard rank of any node in a subtree.
unclassRank and noRank nodes are both considered as noRank in comparisons.
Thus, if and only if all subtree nodes are unclassRank or noRank, "rank_max" is set to noRank.

def MGT::TaxaTree::TaxaNode::setParent	(		self,
			par
	)

Double-link this node and the parent node.
For speed, we do not check that 'par' is not a parent of this node already,
so this method should not be called twice.

def MGT::TaxaTree::TaxaNode::setPropArrayFromAttrib	(		self,
			prop,
			name,
			base = None
	)

Assign values of subtree node attributes to numpy property array.
@param prop - Numpy array
@param name - node attribute name
@param base - indexing will be done as prop[subnode.lind-base]. If 
base is None, the lind of this node will be used.

def MGT::TaxaTree::TaxaNode::setPropArrayFromFunc	(		self,
			prop,
			func,
			base = None
	)

Assign return value of a func(subnode) to numpy property array.
@param prop - Numpy array
@param func - unary function acting on the subtree node
@param base - indexing will be done as prop[subnode.lind-base]. If 
base is None, the lind of this node will be used.

def MGT::TaxaTree::TaxaNode::setReduction	(		self,
			extractor,
			dstAttr,
			reduction = None,
			condition = None,
			childExtractor = None
	)

Assign to 'dstAttr' attribute the result of applying 'reduce(func,...)' to this node and its children.
Example: setTotal() that sums only for non "unclassified" children could be implemented as:
setReduction(srcAttr,dstAttr,operator.add,lambda node: not node.isUnclassified()).
Note: extractor(node) is called unconditionally; condition is only applied to decide whether to extract the value
with childExtractor() from each child sub-node.
Example: collectLeafIds() that assigns to dstAttr a list of all leaf node IDs under each node:
setReduction(lambda node: [ node.id ],dstAttr,operator.add)
Example: same as above, but propagates only a max 'n' elements from a list accumulated for each child node
(can be viewed as a balanced sampling of the tree):
boundedSample = lambda l,n: random.sample(l,min(len(l),n))
setReduction(lambda node: [ node.id ],dstAttr,operator.add,
childExtractor=lambda child: boundedSample(getattr(child,dstAttr),n).
@param extractor - unary function object that is applied to each node to extract the value that is accumulated.
The result is passed as a third argument to 'reduce' built-in.
As a convenient exception, if 'extractor' is a string, it is considered to be a node attribute name.
@param dstAttr - name of destination attribute to set in each node with accumulated result
@param reduction - binary function object that is passed as a first argument to 'reduce' built-in, defaults
to operator.add
@param condition - apply this condition to each child node to decide if it should contribute to the 'dstAttr'
of the parent.
@param childExtractor - unary function object that is applied to each child node of a given node to extract the 
value that is accumulated. The list of results is passed as a second argument to 'reduce' built-in.
As a convenient exception, if 'chilExtractor' is a string, it is considered to be a node attribute name.
Alternatively, if it is None (default), the value of 'dstAttr' of the child node will be extracted.
An example of a non-trivial use of this argument is when we are accumulating a list into 'dstAttr' and want to
extract only a random subset of this list from each child node.

def MGT::TaxaTree::TaxaNode::setTotal	(		self,
			srcAttr,
			dstAttr
	)

Set total as 'dstAttr' attribute as a sum of 'srcAttr' attribute of this node and all its subnodes.

def MGT::TaxaTree::TaxaNode::unsetDebugOnUpdate

(

)

Remove checks for debugging on attribute update previously set by setDebugOnUpdate().
This removes any run-time penalty for the debugging hook.

def MGT::TaxaTree::TaxaNode::visitDepthBottom	(		self,
			func
	)

Apply function 'func' to each node traversing the subtree depth-first, applying 'func' after visiting the children.

def MGT::TaxaTree::TaxaNode::visitDepthTop	(		self,
			func
	)

Apply function 'func' to each node traversing the subtree depth-first, applying 'func' before visiting the children.
If function 'func' returns anything when applied to this node, stop the iteration and return w/o proceeding to the children.

def MGT::TaxaTree::TaxaNode::visitDepthTwice	(		self,
			func
	)

Apply function 'func' to each node twice traversing the subtree depth-first. This is also called modified pre-order traverse.
'func' is applied first time when coming to the node, in which case it is called as func(node,visit=1),
and second time before returning from the node, in which case  it is called as func(node,visit=2).

def MGT::TaxaTree::TaxaNode::whichSupernode	(		self,
			others
	)

Return node from others that is a supernode of self, or None

---

The documentation for this class was generated from the following file:

• mgtaxa/MGT/TaxaTree.py