Christmas Bird Count history report system

# - - -   f i n d H i s t o r y

def findHistory(db, txny, circleList):
    '''Pull effort and census records for the given circles.

      [ (db is a pycbc.CBCDatabase instance) and
        (txny is an xnomo3.Txny instance) and
        (circleList is a list of pycbc.CBCDatabase.Circle instances) ->
          if none of the circles in circleList have effort in db
          for the years selected by Args() ->
            raise lib.ScriptError
          else ->
            return a lib.CbcHist instance representing all effort
            and census data for those circles from db ]
    '''

Using the circles in circleList, we build a list of the related Effort instances for those circles that fall within the desired year range. If there are none, it's an error. See Section 10.12, “hist.cgi: findEfforts(): Locate selected effort records”.

    #-- 1
    # [ if the circles in circleList have any efforts in db for
    #   years selected by HistArgs() ->
    #     effKeyList  :=  EffortKey values from those effort records ]
    #   else -> raise ScriptError ]
    effKeyList = findEfforts(db, circleList)

Next, we examine the user's option values in the HistArgs() instance and set up a function that will filter the stream of census records according to those options. See Section 10.13, “hist.cgi: buildFilter—Set up census record filtration”.

This filter function accepts a Census record and returns a modified Census record. It implements name aliasing if selected (e.g., in New Mexico we can assume all Boat-tailed Grackle records are for what is now called Great-tailed Grackle). It also implements subspecies lumping, so that for example a record for Gambel's White-crowned Sparrow (a subspecies) appears under White-crowned Sparrow (the containing species).

    #-- 2
    # [ filter  :=  a census-filter function that implements the
    #       census record filtering selected by HistArgs() ]
    filter = buildFilter(txny)

The way data from different efforts are routed to logical columns of the report depends on whether the user has requested “year lumping.” One of the required arguments to the CBCHist constructor is a “layout factory,” which does this routing. For the lumped and split (unlumped) layout factories, see Section 47, “class LumpedLayout: Column layout for lumped years” and class-SplitLayout.

    #-- 3
    # [ cbcHist  :=  a CBCHist instance with db=db, effKeyList
    #       made from the effort keys of effortList, txny=txny,
    #       layoutFactory selected by HistArgs().yearLumping,
    #       and cenFilter=filter ]
    if HistArgs().yearLumping:
        layoutFactory = lib.LumpedLayout
    else:
        layoutFactory = lib.SplitLayout

See Section 28, “class CbcHist: The history class”.

    #-- 4
    return lib.CbcHist(db, effKeyList, txny, layoutFactory, filter)