Regions

regions module

Handle geographic regions, which can be nested within one another.

This automatically loads the TDWG regions, together with indexes of names and ISO country codes (see tdwg_load.py for details of the data sources). They are accessible via the module variables tdwg, names and iso, as well as specific TDWG levels in tdwg_levels[1] - tdwg_levels[4]. The variable index combines these three sets of names for convenience.

Example usage:

regions.tdwg["IND"]     # TDWG level 3 region (most of India)
regions.names["India"]  # The country
i = regions.ISO["IN"]   # The country (ISO code)
regions.index["India"]  # .index includes all codes and names
print(i.children)       # Show immediate subregions

for subregion in i:     # Gets all subregions, down to the smallest
    print subregion.name

## Test if a region is in a larger region:
"NET" in regions.names["Europe"]  # True: The Netherlands is in Europe
"NET" in regions.tdwg["14"]       # False (14 is Eastern Europe, TDWG level 2)

for region in regions.tdwg_levels[1]:
    print(region.name)     # tdwg_levels has a set of the regions at each level

You can also use the add to the hierarchy, or create your own (e.g. for a much smaller area). See the Map class.

TDWG Data

taxonome.regions.load_tdwg()

Call this function to load the TDWG set of world regions.

If the ‘load-tdwg-regions’ config value is True, this will be called when the module is imported.

taxonome.regions.find_tdwg(name, level=3, index=None)

Find the set of TDWG regions at a given level corresponding to a given name.

Parameters:

name : str

The name or code to search for.

level : int

The target TDWG level (1-4). Defaults to 3.

index :

The index to use for looking up names/codes. Defaults to names. Others available in this module are: tdwg, ISO (two-letter ISO country codes, e.g NL) and combinedindex (which checks tdwg, names and ISO).

Returns:

A set of TDWG codes; either all the regions contained within the specified region, or the single region which contains or matches the specified region.

Raises: KeyError if the name/code is not found.

taxonome.regions.tdwgise(namegroup, level=3, index=None)

Transform an iterable of names to a set of TDWG regions at a particular level.

Note that, if the input specifies a larger region than the required tdwg level, the output will include all subregions of that region. This may lead to some inaccuracies - e.g. a species recorded as occurring in ‘Africa’ will appear to occur all over Africa.

Parameters: The same as find_tdwg(), except that the first parameter is an iterable of names.

Returns:

A pair of sets: the matching TDWG codes at the specified level, and any names which could not be matched.

Map class

class taxonome.regions.Map