Next / Previous / Contents / TCC Help System / NM Tech homepage

11. class TaxonPhotoSet: The taxonomic tree node

Each instance of this class is a container for all the photos that depict members of a specific taxon. Instances are arranged in the form of a tree. The root node is a container for the entire catalog, and represents the root taxon of birds, Class Aves.

Here is the interface. The constructor takes one argument: the taxon related to this node.

# - - - - -   c l a s s   T a x o n P h o t o S e t

class TaxonPhotoSet:
    '''Represents all photos contained in a specific taxon.

          [ taxon is a txny.Taxon instance ->
              return a new, empty TaxonPhotoSet for that taxon ]
        .taxon:       [ as passed to constructor; read-only ]
        .nContained:  [ number of photos in self's subtree ]
        .nReferred:   [ number of photos referred to self's taxon ]

The .addArchImage() method is used to load catalog entries into the tree. For each photo, this method is called once for each kind of bird in the photo.

Note the precondition that the specified birdId must be referred to a taxon that is either self or a descendant of self. It simplifies the logic of adding a new photo to know that the photo goes somewhere in the correct subtree. It is no burden on the caller who adds the photo to the root of the tree, since all birds are in class Aves. See Section 11.2, “TaxonPhotoSet.addArchImage(): Add one photo”.

        .addArchImage(birdId, archImage):
          [ birdId is referred to a taxon contained in self.taxon ->
              (birdId is a composite bird form code as an
              abbr.BirdId object) and
              (archImage is an image catalog entry as a
              archindex.ArchImage instance) ->
                self  :=  self with archImage added under birdId ]

The .walk() method walks the tree, starting at the given node, and then recursively visiting its descendants. This method is called to generate the various taxonomic headings on the index page. See Section 11.5, “TaxonPhotoSet.walk(): Walk the tree”.

          [ generate self, followed by the descendants of self,
            in preorder traversal ]

Because the presentation of a taxon with only one form is different than the presentation of a multi-form taxon, the .nForms() method allows the caller to determine the number of forms. See Section 11.6, “TaxonPhotoSet.nForms(): Number of contained forms”.

        .nForms():    [ returns the number of forms in self ]

The .genForms() method generates the contained FormPhotoSet objects in order. See Section 11.7, “TaxonPhotoSet.genForms(): Generate referred FormPhotoSet objects”.

          [ generate the FormPhotoSet objects in self, in
            ascending order by inverted English name ]

Here are the internals of the instance. Each node maintains two counters. The .nContained attribute counts all the photos ever added to this node's subtree. The .nReferred attribute is a count of only those photos referred to this node's taxon.

Each TaxonPhotoSet instance is a container for two kinds of objects: child taxa, and FormPhotoSet instances for any photos that may be referred to this taxon.

One of the author's favorite standard Python tricks serves nicely to structure both these container relationships: we keep the contained values in a dictionary, and access them using a key that happens to sort in the desired access order.

The standard Python trick is: use the dictionary's .keys() method to extract a list of keys; sort that list; and then go through the dictionary in order using that list.

Dictionary .childMap contains the child TaxonPhotoSet elements as values. In order to access the children in taxonomic order, we use the txKey attribute of the taxon as the key, which is a string of digits that orders taxa in phylogenetic order.

          [ a dictionary whose values are the child TaxonPhotoSet
            nodes of self, and each corresponding key is the
            .txKey attribute of self's taxon ]

The desired order of form names within a taxon is alphabetical order by the inverted English name.

          [ a dictionary whose values are the FormPhotoSet
            objects holding photos referred to self.taxon,
            and each corresponding key is the inverted
            English name for that form ]