21.2. BirdNoteTree.genMonths(): Generate monthly record sets

21.2. `BirdNoteTree.genMonths()`: Generate monthly record sets

To extract records from a tree represented by an instance B of the BirdNoteTree class, use this method:

B.genMonths ( startDate=None, endDate=None, startSeason=None,
              endSeason=None )

This method generates a sequence of zero or more BirdNoteSet instances, each containing the entire set of records for one month file in the directory structure. The optional arguments allow you to extract only months from a specific time period.

startDate: To select only months after a given date, pass to this argument an instance of the date class of the standard Python datetime package. The method will generate BirdNoteSet instances for only the month containing that date and later months.
endDate: To ignore months after a given date, pass a datetime.date instance to this argument giving the last date of interest.
startSeason: To ignore months after a given date in all years, pass to this argument a datetime.date instance whose month and day specify the first date of interest. The year value in this argument will be ignored.
endSeason: To ignore months after a given date in all years, pass a datetime.date instance whose month and day specify the last date of interest. The year value will be ignored.

Note

The arguments provide filtering of records only down to the month level. The generated BirdNoteSet instances will still contain all the data from the original files. This level of filtering is provided only to speed up the retrieval of records by skipping files totally outside the dates and seasons of interest.

Here is a skeletal example. Suppose you want to extract all records, and further suppose that the current working directory is the root directory for the data files and that the aou.xml file containing the desired taxonomy is also in the current directory. The code would look something like this:

from txny import *
from birdnotes import *
import datetime
  …
txny = Txny()
tree = BirdNoteTree(txny)
for monthSet in tree.genMonths():
    process monthSet, a BirdNoteSet instance

Suppose that you want only months that contain only records from September 23, 1997, through February 10, 1998, inclusive. Replace the last two lines of the above example with these lines:

start = datetime.date ( 1997, 9, 23 )
end = datetime.date ( 1998, 2, 10 )

for monthSet in tree.genMonths(start, end):
    process monthSet, a BirdNoteSet instance

And for a final example, to extract only records from May 5 through May 20:

start = datetime.date ( 2000, 5, 5 )
end = datetime.date ( 2000, 5, 20 )
for monthSet in tree.genMonths(seasonStart=start, seasonEnd=end):
    process monthSet, a BirdNoteSet instance

In the example above, the year will be ignored, and the .genMonths() method will generate one BirdNoteSet instance for every year that had a file for May.

A system for encoding bird field notes