DOCSEARCHbyAlgolia
Submit Docs

pygbif

repository·master·Indexed 41 days ago

https://github.com/gbif/pygbif

A Python client for the GBIF API providing structured access to biodiversity data. It includes specialized modules for occurrences, species taxonomies, registry metadata, maps, literature, collections, and institutions. Features include global caching via pygbif.caching() and support for large-scale data downloads using GBIF credentials.

Tokens
5.2K
Snippets
27
Records
36
Agent score
99%

What's inside pygbif

  1. Overview of pygbif modules

    master

    The pygbif library is organized into several specialized modules that map to different GBIF API capabilities:

    • occurrence: Access core GBIF occurrence data, including count, search, and download APIs.
    • registry: Manage datasets, installations, networks, nodes, and organizations.
    • species: Perform name searches, lookups, suggestions, usage checks, and backbone searches.
    • maps: Access map-related functionalities.
    • literature: Search for scientific literature.
    • collection: Search GRSciColl collections.
    • institution: Search GRSciColl institutions.
    • utils: General utility functions (e.g., wkt_rewind).

  2. Understand the pygbif module structure

    master

    The pygbif library is organized into specialized modules corresponding to major GBIF API functional groups. You can either import the entire library or import specific modules to access relevant methods:

    • Registry: Access Datasets, Nodes, Installations, Networks, and Organizations.
    • Species: Access taxonomic name data.
    • Occurrences: Access occurrence data and the download API.
    • Maps: Access map generation tools.

    Additionally, the library includes a caching mechanism to manage whether HTTP requests are cached.

  3. Install pygbif

    master

    You can install the stable version of pygbif from PyPI using pip. If you need the development version, you can install directly from the GitHub repository.

    # Stable version
pip install pygbif

# Development version
[sudo] pip install git+git://github.com/gbif/pygbif.git#egg=pygbif

  4. Get occurrence data for a set of taxonomic names

    master

    You can retrieve occurrence counts for a list of species by first resolving their names to GBIF backbone taxonomic keys using the species module, and then querying the occurrences module using those keys.

    1. Resolve names to keys: Use species.name_backbone(name)['usageKey'] to get the unique identifier for a taxon.
    2. Query occurrences: Use occ.search(taxonKey=key, limit=0)['count'] to retrieve the total number of records for that taxon without downloading the full dataset.
    3. Process results: Combine the original names and the counts into a dictionary for analysis.
    from pygbif import species as species
from pygbif import occurrences as occ

# 1. List of species names
splist = ['Cyanocitta stelleri', 'Junco hyemalis', 'Aix sponsa', 'Ursus americanus', 'Pinus conorta', 'Poa annuus']

# 2. Get GBIF backbone taxonomic keys
keys = [ species.name_backbone(x)['usageKey'] for x in splist ]

# 3. Get a count of occurrence records for each taxon
out = [ occ.search(taxonKey=x, limit=0)['count'] for x in keys ]

# 4. Create a sorted dictionary of species names and record counts
x = dict(zip(splist, out))
sorted_results = sorted(x.items(), key=lambda z:z[1], reverse=True)
print(sorted_results)

  6. Configure GBIF credentials for downloads

    master

    GBIF download endpoints require authentication. You can provide credentials in two ways:

    1. Environment Variables: Set GBIF_USER and GBIF_PWD in your shell environment.
    2. Function Arguments: Pass user= and pwd= directly to the download methods.

    Use environment variables to avoid hardcoding sensitive information in your scripts.

    export GBIF_USER="your_gbif_username"
export GBIF_PWD="your_gbif_password"

  7. Use the occurrences module for GBIF data

    master

    The pygbif.occurrences module provides access to GBIF occurrence data through various methods for searching, retrieving, counting, and downloading occurrence records.

    Common tasks include:

    • Searching: Use search() to find occurrences based on criteria like taxonKey.
    • Retrieving: Use get() to fetch specific records by their unique key.
    • Counting: Use count() or specialized count methods (e.g., count_basisofrecord, count_year) to get aggregate statistics.
    • Downloading: Use download() to initiate large-scale data downloads using query strings.
    from pygbif import occurrences as occ

# Search for occurrences of a specific taxon
occ.search(taxonKey=3329049)

# Get a specific occurrence by its key
occ.get(key=1986559641)

# Count georeferenced occurrences
occ.count(isGeoreferenced=True)

# Initiate a download with a query
occ.download('basisOfRecord = PRESERVED_SPECIMEN')

  11. Use the registry module to access GBIF registry data

    master

    The registry module in pygbif provides access to various GBIF registry endpoints. You can use it to query information about organizations, nodes, networks, installations, datasets, and more.

    Commonly used methods include:

    • organizations(): Access organization data.
    • nodes(): Access node data.
    • networks(): Access network data.
    • installations(): Access installation data.
    • datasets(): Access dataset information.
    • dataset_metrics(): Retrieve metrics for a specific dataset.
    • dataset_suggest(): Get dataset suggestions.
    • dataset_search(): Search for datasets.
    • dataset_metrics(): Retrieve metrics for a specific dataset using a UUID.
    from pygbif import registry

# Example: Retrieve metrics for a specific dataset using its UUID
registry.dataset_metrics(uuid='3f8a1297-3259-4700-91fc-acc4170b27ce')