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

10.13. hist.cgi: buildFilter—Set up census record filtration

# - - -   b u i l d F i l t e r

def buildFilter(txny):
    '''Set up a function to modify the names in census records.

      [ txny is an xnomo3.Txny instance ->
          return a census-filter function that implements the
          census record filtering selected by HistArgs() ]

The purpose of this function is to build the function that is passed to the cenFilter argument of the constructor for Section 28, “class CbcHist: The history class”. The resulting function must conform to the interface definition for census-filter; see Section 14.1, “census-filter.

In the current release, this function must implement two of the CGI arguments:

In case the reader is not familiar with the use of closures, in Python, an function defined within an outer function may refer to variables of the outer function, and it will retain these connections after the outer function has completed.

The filter function must have access to the HistArgs() singleton when it is called from the CbcHist constructor, but that singleton is not in the name scope of that constructor. By defining our filter function here inside the scope of the hist.cgi script, the references to attributes of the HistArgs() singleton remain bound to those attributes for the life of the function.

    #-- 1
    # [ result  :=  a census-filter function that filters census
    #       records according to the values of HistArgs().lumpSubsp
    #       and HistArgs().nmAlias ]
    def result(census):
        '''Closure to filter census records with subsp lumping+aliasing

          [ (HistArgs() is the HistArgs singleton) and
            (txny is a taxonomy as an xnomo3.Txny instance) and
            (census is a pycbc.Census instance) ->
              return a Census record representing (census), but with
              subspecies lumping if HistArgs().lumpSubsp is True and with
              species aliasing specified by HistArgs().nmAlias ]

The first step is to replace any bird codes that have exact modern equivalents; see hist-fixOldNames.

        #-- 1
        # [ cen0  :=  census, with any bird codes replaced by exact
        #             equivalents from txny if there are any ]
        cen0 = updateAbbrs(census, txny)

See Section 10.18, “hist.cgi: subspLumper()—Lump subspecies”.

        #-- 2
        # [ if (HistArgs().lumpSubsp) and (cen0's form is a subspecies
        #   in txny) ->
        #     cen1  :=  cen0 with its form replaced by the code
        #         for that subspecies's containing species in txny
        #   else ->
        #     cen1  :=  cen0 ]
        if HistArgs().lumpSubsp:
            cen1 = subspLumper(cen0, txny)
            cen1 = cen0

        #-- 3
        # [ if HistArgs().nmAlias is not None ->
        #     cen2  :=  census filtered by HistArgs().nmAlias()
        #   else ->
        #     cen2  :=  census ]
        if HistArgs().nmAlias:
            cen2 = lib.nmAlias(cen1)
            cen2 = cen1

        #-- 4
        return cen2

At this point, the local name result is bound to the function defined above. We still need to return that function to the caller.

    #-- 2
    return result