# - - - 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
census-filter; see Section 14.1, “
In the current release, this function must implement two of the CGI arguments:
HistArgs().lumpSubsp, subspecies lumping. For
any census record that uses the name of a subspecific
form, replace that name with the code for the containing
HistArgs().nmAlias, New Mexico name alias set.
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
singleton remain bound to those attributes for the life of the
#-- 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
#-- 1 # [ cen0 := census, with any bird codes replaced by exact # equivalents from txny if there are any ] cen0 = updateAbbrs(census, txny)
#-- 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) else: 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) else: 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