coldp.COLDP¶

Class¶

class coldp.COLDP(name, folder='.', code='ICZN', default_taxon_record=None, insert_species_for_trinomials=False, create_subspecies_for_infrasubspecifics=False, create_synonyms_without_subgenus=False, basionyms_from_synonyms=False, classification_from_parents=False, allow_repeated_binomials=False, create_taxa_for_not_established=False, issues_to_stdout=False, context=None)

Class to manage a set of Pandas dataframes for CSV tables in Catalogue of Life Data Package.

Parameters:

name¶ – The name for the COLDP package. If a folder of this name exists inside the folder specied by the folder parameter, this COLDP instance will be initialised with the contents of any COLDP-compliant CSV or TSV files in the named folder.
folder¶ – Name of folder that may contain the named COLDP source folder from which source files should be read (name specified via the name parameter) and that is the default folder in which a COLDP folder will be written when the COLDP instance is saved. This is not the folder in which the CSV files are written. It is the folder which will contain the subfolder holding CSV files.
code¶ – ICZN or ICBN to indicate the nomenclatural code for name formatting. ICZN is the default.
default_taxon_record¶ – Any values in the dictionary are automatically used as default values in taxon records added to the COLDP instance. In other words, the dictionary becomes the base into which other taxon record properties are then inserted.
insert_species_for_trinomials¶ – If true, insert species (taxon and name) if trinomials are provided without the associated species. This can be convenient when mapping source data that only lists infraspecific taxa for species with subspecies, varieties or forms.
create_subspecies_for_infrasubspecifics¶ – If true, automatically add a trinomial at subspecific rank as a synonym whenever an infrasubspecific name is added. This may be useful if the resulting dataset is intended to provide easy mapping of strings to taxon concepts, since versions of the trinomial lacking the rank marker will often be found in source data.
create_synonyms_without_subgenus¶ – If true, automatically add a binomial or trinomial without an included subgenus name as a synonym whenever a name including a subgenus is added. This may be useful if the resulting dataset is intended to provide easy mapping of strings to taxon concepts, since versions of lacking the subgeneric component will often be found in source data.
basionyms_from_synonyms¶ – If true, basionym associations are automatically created from synonyms within a loaded COLDP dataset. If an accepted name includes parentheses around the authorship, and if a name with the same epithet and authorship but no parentheses is included in the synonyms, the ID value for the synonym will be used for the basionymID element in the accepted name. This is normally a housekeeping step when first loading a new COLDP dataset. This option is only used when the dataset is first loaded. Addition of basionym relationships is automatic for names added as part of the same NameBundle.
classification_from_parents¶ – If true, insert names for higher ranks into relevant elements in each taxon record based on the parent and higher ancestry for the taxon.
allow_repeated_binomials¶ – If true, omit checks rejecting the addition of the same binomial more than once to the COLDP name dataframe.
create_taxa_for_not_established¶ – If true, generate taxon records even if the associated name is flagged as not established (i.e. not satisfying the relevant nomenclatural code)
issues_to_stdout¶ – If true, print any issue messages (see issue()) to stdout as well as inserting then in the issue dataframe.
context¶ – Value to be used in labeling issue records (see issue()). This value is more normally set using set_context().

A COLDP object is initalised with a source/destination folder, COLDP package name and other options.

If a subfolder exists with the supplied name in the supplied folder, it will be initialised with data from any CSV/TSV files it contains with any of the following base names: name, taxon, synonym, reference, distribution, speciesinteraction, namerelation, typematerial or nameusage, and with a file extension recognised via csv_extensions. File names are case insensitive.

Files with the base name nameusage are loaded only if the name, taxon or synonym file is absent, in which case the contents of the nameusage file are mapped internally to the more normalised COLDP format with separate name + taxon + synonym tables.

If no folder exists with the supplied name, an empty instance is created. Pandas dataframes are created as required for the COLDP data types as data are inserted into the instance.

The start_name_bundle() method produces a NameBundle object for preparing an accepted name and associated synonyms to pass to the add_names() method which creates name, taxon and synonym records as a set of cross-referenced objects.

Other data is added using the add_names(), add_name_relation(), add_typematerial(), add_distribution(), add_species_interaction() and modify_taxon() methods.

The save() method writes the data back to the same or another folder.

Methods¶

Control behaviour¶

COLDP.set_options(**options)¶

Set options controlling COLDP instance from keyword arguments

Parameters:: options¶ – Set of boolean options for controlling the behaviour of the COLDP package - see COLDP for boolean options that can be set.

Convenience method for setting options via keyword arguments after the COLDP instance has been created.

COLDP.set_default_taxon_record(default_taxon_record)¶

Set default values for properties in taxon records created by this COLDP instance

Parameters:: default_taxon_record¶ – Any values in the dictionary are automatically used as default values in taxon records added to the COLDP instance. In other words, the dictionary becomes the base into which other taxon record properties are then inserted.

Convenience method for setting default taxon record after the COLDP instance has been created.

COLDP.set_context(context)¶

Set a string label for annotating issues in the COLDP issue table

Parameters:: context¶ – String to label any issues associated with data changes from the current point forward

The COLDP class automatically logs errors and issues to an issues dataframe. This dataframe is included among the CSV output files when a COLDP instance is saved.

Each row in the issue table indicates a possible problem with data added to the instance. The context variable provides an external mechanism for the user to label these issues as they occur. For example, if the user is processing a spreadsheet of species names, they can call set_context with a string identifying the row from the source spreadsheet. This value will be included in the context column in the issue.csv output.

Add or modify records¶

COLDP.start_name_bundle(accepted, incertae_sedis=False, sic=False)¶

COLDP.add_names(bundle, parent=None)¶

Ensure one or more names are included in names dataframe and update taxa and synonyms dataframes as necessary

Parameters:

bundle¶ – NameBundle object with set of associated taxon names
parent¶ – ID for taxon record for which the accepted taxon in this bundle is to be added as a child

The supplied NameBundle object includes an accepted name record (as a dictionary of COLDP name properties) and a list, which may be empty, of synonym name records in the same format. add_names() ensures that name records exist for all these names in the names dataframe, that a taxon record exists for the accepted taxon name, and that synonym records exist for this taxon record for all supplied synonyms.

Depending on the options supplied for the COLDP object, additional synonyms may be created to represent subspecies-rank versions of infrasubspecific trinomials and subgenus-free versions of combinations including a subgenus name.

If a matching name already exists in the COLDP instance, no new name will normally be added. Instead, the name record in the bundle will be updated with the ID (and basionymID where applicable) from the existing name. This allows for additional synonyms to be added to an existing taxon. The behaviour can be over-ridden with the allow_repeated_binomials option, in which case any number of matching names can be added.

If the insert_species_for_trinomials option is set, a new species will be created if required before adding the trinomial as its child. In this case the bundle will contain the id for the species taxon as a species_taxon_id property.

Name records in the bundle are all updated with existing or new IDs and basionymIDs, which are inferred automatically for zoological names by associating combinations with and without parentheses around the authorship.

Upon completion, the bundle also contains an accepted_taxon_id property which includes the string ID for the taxon.

If parent is None, the new taxon record is created without a parent, i.e. becomes a root node in the classification.

COLDP.add_references(reference_list)¶

Ensure one or more references are included in references dataframe

Parameters:: reference_list¶ – List of dictionaries - each dictionary contains values keyed by terms from reference_headings
Returns:: Updated reference_list with IDs for references in this COLDP instance

Find existing ID values for each supplied reference, based on identity of: author, title, issued, containerTitle, volume, issue, page and citation. Add ID to the appropriate reference dictionary in references. If none found, set ID to next unused index and add to references.

The list is returned updated with current ID values so these can be used for referenceID values in other classes.

COLDP.add_type_material(type_material)¶

Add COLDP TypeMaterial record to COLDP instance

Parameters:: type_material¶ – COLDP TypeMaterial record represented as dictionary of properties
Returns:: TypeMaterial record returned unchanged

The nameID value must match the ID value for an existing name record.