[Biopython-dev] [Wg-phyloinformatics] BioGeography update/BioPython tree module discussion

[Brad Chapman]

Hi Nick;

> Summary: Major focus is getting the GBIF access/search/parse module into 
> "done"/submittable shape.  This primarily requires getting the 
> documentation and testing up to biopython specs.  I have a fair bit of 
> documentation and testing, need advice (see below) for specifics on what 
> it should look like.

Awesome. Thanks for working on the cleanup for this.

> OK, I will do this.  Should I try and figure out the unittest stuff?  I 
> could use a simple example of what this is supposed to look like.

In addition to Peter's pointers, here is a simple example from a
small thing I wrote:

http://github.com/chapmanb/bcbb/blob/master/align/adaptor_trim.py

You can copy/paste the unit test part to get a base, and then
replace the t_* functions with your own real tests.

Simple scripts that generate consistent output are also fine; that's
the print and compare approach.

> > - What is happening with the Nodes_v2 and Treesv2 files? They look
> >   like duplicates of the Nexus Nodes and Trees with some changes.
> >   Could we roll those changes into the main Nexus code to avoid
> >   duplication?
> 
> Yeah, these were just copies with your bug fix, and with a few mods I 
> used to track crashes.  Presumably I don't need these with after a fresh 
> download of biopython.

Cool. It would be great if we could weed these out as well.

> The API is really just the interface with GBIF.  I think developing a 
> cookbook entry is pretty easy, I assume you want something like one of 
> the entries in the official biopython cookbook?

Yes, that would work great. What I was thinking of are some examples
where you provide background and motivation: Describe some useful 
information you want to get from GBIF, and then show how to do it.
This is definitely the most useful part as it gives people working
examples to start with. From there they can usually browse the lower
level docs or code to figure out other specific things.

> Re: API documentation...are you just talking about the function 
> descriptions that are typically in """ """ strings beneath the function 
> definitions?  I've got that done.  Again, if there is more, an example 
> of what it should look like would be useful.

That looks great for API level docs. You are right on here; for this
week I'd focus on the cookbook examples and cleanup stuff.

My other suggestion would be to rename these to follow Biopython
conventions, something like:

gbif_xml -> GbifXml
shpUtils -> ShapefileUtils
geogUtils -> GeographyUtils
dbfUtils -> DbfUtils

The *Utils might have underscores if they are not intended to be
called directly.

Thanks for all your hard work,
Brad