Taxa

Taxon class

class taxonome.Taxon(name, authority='')

Name class

class taxonome.Name(name, authority='', rank=None)

Store a species name, optionally qualified with an authority.

When comparing two names, the authority of each will be simplified to try to overcome differences in format and punctuation. For example:

a = Name("Lablab purpureus", "(L.) Sweet")
b = Name("Lablab purpureus","Sweet.")
c = Name("Lablab purpureus", "Sweet. ex. MadeUp.")
a == b
a == c
b == c    # All True

Collections of taxa

class taxonome.TaxonSet

Bases: taxonome.taxa.collection.TaxaResource

This allows storing a collection of taxa, along with synonymy and easy lookup by name, whether or not the name is qualified with an authority.

Looking up synonyms that have been added returns the taxon, but looping through it will ignore synonyms.

There is currently no option to delete a taxon. Instead, build a new TaxonSet with only the taxa you want to keep.

Usage example:

mygenus = TaxonSet()
Lp = Taxon("Lablab purpureus", "(L.) Sweet")
Lp.othernames.add(Name("Dolichos lablab", "L."))
Lp.othernames.add(Name("Vigna aristata", "Piper"))
mygenus.add(Lp)
                  
# Unqualified name:
"Lablab purpureus" in mygenus       # -> True
"Dolichos lablab" in mygenus        # -> True
"Lablab vulgaris" in mygenus        # -> False
mygenus.resolve("Lablab purpureus") # -> List of possible Taxon() objects
mygenus.resolve("Dolichos lablab")  #    (will usually only have one item)
mygenus.select("Lablab purpureus")  # -> Picks the best match (may ask the
                                    #    user to select from alternatives)

# Qualified name:
Name("Lablab purpureus", "(L.) Sweet") in mygenus # -> True
Name("Lablab purpureus", "Sweet") in mygenus      # -> True
mygenus.select(Name("Dolichos lablab", "L."))  # Returns a Taxon() object

class taxonome.taxa.collection.TaxaResource

A base class for classes holding indexed collections of taxa.

Not designed to be instantiated.

get_by_accepted_name(name)

May be defined by subclass. Called with a Name object known to be an accepted name in this resource. Should return the corresponding taxon.

resolve_name(name)

Must be defined by subclass. The name given may be a string or a Name object.

Return a list of 3-tuples, (name, accepted_name, id), where the id can be passed to get_by_id() to retrieve the associated taxon.

select(name, strict_authority=False, upgrade_subsp='nominal', fuzzy=True, prefer_accepted='noauth', nameselector=None, tracker=<taxonome.tracker.NoopTracker object at 0x7fadc4528780>)

Select a taxon by name. If there is more than one match, an interactive prompt will ask the user to choose.

Parameters:

name : Name or str

The name (qualified or unqualified) to look for

strict_authority : bool

If True, names will be disregarded if their authority does not match that given (with a qualified name). If False, the authority will be used to distinguish homonyms, but will be overlooked if none of the names found have matching authority.

upgrade_subsp : str

If ‘none’, subspecies and varieties will only be matched to identical names. Otherwise, subspecies and varieties may be matched to their parent species if no exact match is found. ‘nominal’ will cause only nominal subspecies/varieties to be upgraded (e.g. Vicia faba var. faba –> Vicia faba), while ‘all’ allows any subspecies/variety to upgrade.

fuzzy : bool

If True, fuzzy matching will be used with the specified name where possible.

prefer_accepted : str

‘all’ will resolve ambiguities by choosing the accepted name where possible. ‘noauth’ does this only where the given name doesn’t have an authority. ‘none’ will always ask the user.

nameselector : NameSelector instance

Defines how to choose between alternative matches. See taxonome.taxa.name_selector.NameSelector. The default name selector is the _nameselector attribute on this collection.

tracker :

A tracker object - see details in taxonome.tracker.

Returns:

A taxon object if a match is found in this dataset. Raises KeyError if no match is found.

Matching and combining datasets

taxonome.taxa.match_taxa(taxa, target, merge_info=<function combine_dicts at 0x7fadc4533ea0>, tracker=<taxonome.tracker.NoopTracker object at 0x7fadc4528780>, **kwargs)

Match one set of taxa against another by name.

Parameters:

taxa : iterable

The taxa to be matched

target : TaxonSet

The taxa whose names we want to match to.

merge_info : function

A function which takes two dictionaries as arguments, and returns a dictionary. Called with the .info parameters of multiple taxa which are mapped to the same name.

tracker :

A tracker object (see taxonome.tracker) or tuple of trackers to record the name matching process.

strict_authority, upgrade_subsp, fuzzy, prefer_accepted, nameselector :

Control the matching procedure; see TaxonSet.select() for details.

Returns:

A TaxonSet, containing copies of the input taxa, with the .name attribute replaced with the name of the corresponding taxon from target_ts, .othernames cleared, and .info combined with taxa mapping to the same name.

Taxa which fail to match send a ‘no match’ event to the tracker.

taxonome.taxa.combine_datasets(target_ds, background_ds, distrib_ds_name, add_info=<function add_info_nested at 0x7fadc4548620>)

Combine several taxa datasets into one.

Parameters:

target_ds, background_ds :

Each should be a sequence of 2-tuples, (name, taxonset). The name will be used as the key in the taxa’s info. All taxa from any target dataset are included in the output, whereas information from background datasets is only copied to taxa in target datasets. There must be at least one target dataset, and at least one other (either target or background).

Target datasets may be any iterable collection of taxa. Background datasets should be TaxonSets or similar.

distrib_ds_name : str

The name of the dataset from which distribution information should be taken, or ‘all’ to combine distribution info from all datasets.

add_info : func

A function to combine the information dicts for a taxon. It takes three parameters: the taxon object, the information dict to be added, and the name of a dataset.

The default will nest information under the names of the datasets. The add_info_flat() function will make a flat dictionary.

Returns: A TaxonSet.