# - - - T x n y . _ _ a p p e n d T a x o n def __appendTaxon ( self, scan, rawTaxon ): '''Try to add a new Taxon to the tree. [ (scan is a Scan instance) and (rawTaxon is a RawTaxon instance) -> if rawTaxon can be appended to self.taxaTree -> self.taxaTree +:= a new Taxon instance made from rawTaxon as its root node return that new Taxon else -> Log() +:= error message(s) raise SyntaxError ] '''
There are two main cases.
If the tree is empty, the new taxon becomes the tree's root. The taxon's rank must be the first rank in the hierarchy, the rank with zero depth.
If the tree is not empty, we must test to see if the
new taxon can be appended to the tree. First we must
find the parent under which the new taxon is to be added;
see Section 7.9, “
rank-parent: What taxon is the parent
of a new taxon of a given rank?”. Assuming that we
can find an appropriate parent, we must also perform
the tests discussed in Section 7.3, “
can-add-child: Can a given parent have a
First, handle the special case when the tree is empty. For
the logic that checks whether the new taxon can be a root, and
sets it if so, see Section 18.2, “
TaxaTree.setRoot(): Store the root
#-- 1 -- # [ if self.taxaTree is empty -> # if rawTaxon represents a valid root node -> # self.taxaTree := self.taxaTree with that root node # else -> # Log() +:= error message(s) # raise SyntaxError # else -> I ] if self.taxaTree.root is None: #-- 1.1 -- # [ newRoot := a new Taxon instance with hierarchy # (self.hier), no parent, and attributes from # rawTaxon ] newRoot = self.taxaTree.addTaxon ( None, rawTaxon ) #-- 1.2 -- # [ if newRoot's depth is 0 -> # self.taxaTree := self.TaxaTree with a new # root Taxon (newRoot) # return that Taxon # else -> # Log() +:= error message(s) # raise SyntaxError ] try: self.taxaTree.setRoot ( newRoot ) return newRoot except ValueError, detail: scan.syntax ( "Can't set the root taxon: %s" % detail )
At this point we know that the tree is not empty. First try
to find an appropriate parent node for the new taxon; see
Section 18.3, “
TaxaTree.rankParent(): Under what parent
does a new taxon go?”.
#-- 2 -- # [ if a taxon of rank (rawTaxon.rankCode) can be added as # self.taxaTree as its last node in preorder -> # parent := rank-parent ( self.taxaTree, # rawTaxon.rankCode ) # else -> # Log() +:= error message(s) # raise SyntaxError ] try: parent = self.taxaTree.rankParent ( rawTaxon.rankCode ) except ValueError, detail: scan.syntax ( detail )
parent has the right rank does not
imply that the new taxon can be added. For example, if the
parent is a family and has subfamily children, a new genus
cannot be added to that family. See Section 18.4, “
#-- 3 -- # [ if can-add-child ( self.hier, parent, Rank for # rawTaxon.rankCode) -> # I # else -> # Log() +:= error message(s) # raise SyntaxError ] try: self.taxaTree.canAddChild ( parent, rawTaxon.rankCode ) except ValueError, detail: scan.syntax ( detail )
Everything is now ready for the addition of the new taxon to
the tree. See Section 18.5, “
#-- 4 -- # [ parent := parent with a new Taxon child made from # rawTaxon # taxon := that new Taxon ] taxon = self.taxaTree.addTaxon ( parent, rawTaxon ) #-- 5 -- return taxon