Updated documentation with examples.

README.md

@@ -68,7 +68,7 @@ or the command
 Documentation
 -------------
 
-Generated documentation is found [here](http://AlexSafatli.github.io/Pylogeny "Pylogeny API").
+Generated documentation is found [here](http://AlexSafatli.github.io/Pylogeny "Pylogeny API"). Tutorials and additional code examples are present in the [wiki](https://github.com/AlexSafatli/Pylogeny/wiki) on GitHub for this project.
 
 Dependencies
 -------------

pylogeny/__version__.py

@@ -1 +1 @@
-VERSION = '0.3.6'
+VERSION = '0.3.6.1'

pylogeny/executable.py

@@ -115,6 +115,7 @@ def __init__(self,treeset,alignment,name):
         self.treeset   = treeset
         self.name      = name
         self.alignment = alignment
+        self._out      = None
         self.sitelh    = None
         self.raw       = None
         self.rmt       = None
@@ -174,11 +175,24 @@ def _getAU(self):
             else: self.rejected.addTree(self.treeset[it[0]])    
         self._out = pvout
 
+    def getRejected(self):
+
+        ''' If an AU test has already been performed, return the set of trees
+        that were rejected by the test. 
+        
+        :return: a :class:`.tree.treeSet` object or None if no test was done yet
+        
+        '''
+
+        if (self._out != None):
+            return self.rejected
+        return None
+
     def getInterval(self):
 
-        ''' Compute the AU test. Return the interval of trees.
+        ''' Compute the AU test. Return the interval of trees as a tree set.
         
-        :return: a list of :class:`.tree.tree` objects
+        :return: a :class:`.tree.treeSet` object
         
         '''
 

pylogeny/heuristic.py

@@ -46,7 +46,8 @@ def getBestTree(self): return self.bestTree
 
 class parsimonyGreedy(phylogeneticLinearHeuristic):
 
-    ''' Greedy (hill-climbing) landscape exploration by comparsion of parsimony. '''
+    ''' Greedy (hill-climbing) landscape exploration by comparsion of parsimony.
+    '''
 
     def __init__(self,ls,startNode):
 
@@ -148,7 +149,8 @@ def explore(self):
             nodes = landscape.getNeighborsFor(cursor['index'])
             nodes = [landscape.getNode(x) for x in nodes]
             nodes = [it for it in nodes if not it in self.path]
-            map(lambda d: landscape.getVertex(d['index']).scoreLikelihood(),nodes)
+            map(lambda d: landscape.getVertex(d['index']).scoreLikelihood(),
+                nodes)
             nodes = sorted(nodes,key=lambda d: d['tree'].score[0])
 
             # Get best likelihood tree.

pylogeny/rearrangement.py

@@ -440,7 +440,11 @@ def lockBranch(self,branch):
     def move(self,branch,destination,returnStruct=True):
 
         ''' Move a branch and attach to a destination branch. Return new
-        structure, or return merely the resultant Newick string. '''
+        structure, or return merely the resultant Newick string.
+
+        :return: a :class:`.topology` object or a Newick string
+        
+        '''
 
         # Cannot move to these.
         forbidden = self.forbidden[branch]
@@ -511,7 +515,11 @@ def SPR(self,branch,destination):
         ''' Perform an SPR move of a branch to a destination branch, creating a
         new node there. Returns a rearrangement structure (not the actual new
         structure) that can then be polled for the actual move; this is in order
-        to save memory. '''
+        to save memory.
+                
+        :return: a :class:`.rearrangement` object
+        
+        '''
 
         return rearrangement(self,TYPE_SPR,branch,destination)
 
@@ -520,7 +528,11 @@ def NNI(self,branch,destination):
         ''' Perform an NNI move of a branch to a destination, only if that
         destination branch is a parent's parent or a parent's sibling. Returns a
         rearrangement structure (not the actual new structure) that can then be
-        polled for the actual move; this is in order to save memory. '''
+        polled for the actual move; this is in order to save memory.
+        
+        :return: a :class:`.rearrangement` object        
+        
+        '''
 
         if newick.isSibling(branch.parent,destination) or \
            (branch.parent and destination == branch.parent.parent):
@@ -531,7 +543,11 @@ def iterSPRForBranch(self,br,flip=True):
 
         ''' Consider all valid SPR moves for a given branch 
         in the topology and yield all possible rearrangements
-        as a generator. '''    
+        as a generator.
+
+        :return: a generator of :class:`.rearrangement` objects
+        
+        '''    
 
         # Go through possible moves.
         partition = self._getPartition(br)
@@ -553,14 +569,22 @@ def iterSPRForBranch(self,br,flip=True):
     def allSPRForBranch(self,br,flip=True):
 
         ''' Consider all valid SPR moves for a given branch in the topology and
-        return all possible rearrangements. '''
+        return all possible rearrangements.
+        
+        :return: a list of :class:`.rearrangement` objects        
+        
+        '''
 
         return [x for x in self.iterSPRForBranch(br,flip)]
 
     def allSPR(self):
 
         ''' Consider all valid SPR moves for a given topology and return all
-        possible rearrangements. '''
+        possible rearrangements.
+        
+        :return: a list of :class:`.rearrangement` objects
+        
+        '''
 
         # Output list of structures.
         li = []        
@@ -572,7 +596,11 @@ def allSPR(self):
     def iterNNIForBranch(self,br,flip=True):
 
         ''' Consider all valid NNI moves for a given branch in the topology and
-        and yield all possible rearrangements as a generator. '''
+        and yield all possible rearrangements as a generator.
+        
+        :return: a generator of :class:`.rearrangement` objects        
+        
+        '''
 
         # Go through possible moves.
         partition = self._getPartition(br)
@@ -596,14 +624,22 @@ def iterNNIForBranch(self,br,flip=True):
     def allNNIForBranch(self,br,flip=True):
 
         ''' Consider all valid NNI moves for a given branch in the topology and
-        return all possible rearrangements. '''
+        return all possible rearrangements.
+        
+        :return: a list of :class:`.rearrangement` objects
+        
+        '''
 
         return [x for x in self.iterNNIForBranch(br,flip)]
 
     def allNNI(self):
 
         ''' Consider all valid NNI moves for a given topology and return all
-        possible rearrangements. '''
+        possible rearrangements.
+        
+        :return: a list of :class:`.rearrangement` objects        
+        
+        '''
 
         # Output list of structures.
         li,nni = [],self.allNNIForBranch        
@@ -616,7 +652,11 @@ def allType(self,type=TYPE_SPR):
         given topology. Uses a given rearrangement operator type defined in this
         module. For example, calling this function by providing TYPE_NNI as the
         type will iterate over all NNI operations. By default, the type is
-        TYPE_SPR. '''
+        TYPE_SPR.
+        
+        :return: a list of :class:`.rearrangement` objects
+        
+        '''
 
         if (type == TYPE_SPR): return self.allSPR()
         elif (type == TYPE_NNI): return self.allNNI()

pylogeny/tree.py

@@ -29,8 +29,9 @@ def median(lst):
 
 class tree(object): # TODO: Integrate with P4 Tree class (?).
 
-    ''' Defines a single (phylogenetic) tree by Newick string;
-    can possess other metadata. '''
+    ''' Represents a single (phylogenetic) tree by Newick string;
+    can possess other metadata. For manipulation of tree structure, such
+    as rerooting and unrooting, convert this object to a topology. '''
 
     def __init__(self,newi='',check=False,structure=None):
 
@@ -41,9 +42,9 @@ def __init__(self,newi='',check=False,structure=None):
         all parsing routines are bypassed and the Newick and Structure
         fields of this tree are overriden by the appropriate arguments. 
 
-        :param newi: A Newick or New Hampshire string for a tree.
+        :param newi: a Newick or New Hampshire string for a tree
         :type newi: a string
-        :param check: Perform parsing checks on the string input.
+        :param check: perform parsing checks on the string input
         :type check: a boolean
 
         '''
@@ -118,7 +119,7 @@ def setOrigin(self,o):
         ''' Set the "origin" or specification of where this tree
         was acquired or constructed from.
 
-        :param o: A string indicating where the tree came from.
+        :param o: a string indicating where the tree came from
         :type o: string or None
 
         '''
@@ -144,6 +145,23 @@ def toNewick(self):
         '''
 
         return self.newick
+
+    def toDendroPy(self):
+
+        ''' Convert the tree object to a DendroPy tree object. Requires DendroPy
+        to be installed on the system.
+        
+        :return: a DendroPy Tree object or None if DendroPy not on system
+        
+        '''
+
+        try:
+            from dendropy import Tree as dendropyTree
+        except ImportError:
+            return None
+        t = dendropyTree()
+        t.read_from_string(self.toNewick(),'newick')
+        return t
 
     def _setNewick(self,n):