Skip to content

Download the Jupyter notebook

Assignment 02: Fetching Occurrence Records With pygbif

BIO597 Spatial Analysis of Biodiversity

This assignment gives you more practice with the workflow from Lab 02.

You will use pygbif to search GBIF for several snake species, download a small number of occurrence records, convert those records to GeoDataFrame objects, and make simple maps and summaries.

Some cells are partly filled in. You should fill in the missing pieces and run the notebook from top to bottom.

Remember, learning to code is often about learning how to strategically copy, paste, and modify. Look back at Lab 02 when you need a model.

Species for this assignment

Use these species:

  • Storeria dekayi
  • Agkistrodon contortrix
  • Pantherophis guttatus
  • one additional snake species of your choice

For each species, we will ask GBIF for georeferenced records so the results can be mapped.

1. Import packages

Import the same packages used in Lab 02.

species is used for taxonomic name searches. occ is used for occurrence record searches.

from pygbif import species
from pygbif import occurrences as occ

import pandas as pd
import geopandas as gpd

2. Search for possible name matches

Use species.name_suggest() to search for Storeria dekayi.

Fill in the species name. Then inspect the first result.

dekayi_suggestions = species.name_suggest(q="Storeria dekay")
# dekayi_suggestions will have a list of dictionaries
# select the first element of this list here and save it as a new variable called `dekayi_match`

3. Save the taxon key

Pull the speciesKey out of the match result and save it as dekayi_key.

dekayi_key = dekayi_match["__________"]
dekayi_key

4. Count records before downloading

Use occ.count() to count georeferenced GBIF records for Storeria dekayi.

This count tells you how many records GBIF has that match your search, not how many you will download in this assignment.

dekayi_count = occ.count(
    taxonKey=dekayi_key,
    isGeoreferenced=True,
)

dekayi_count

5. Determine how many total records there are for S. dekayi

5. Determine how many total records there are for S. dekayi

The isGeoreferenced parameter determines whether occurrences with latlongs are returned. Make a copy of the call to occ.count() as above, but change the True to False, which will return only occurrences without latlongs. Capture the results in a new variable called dekayi_nolatlong_count and then add this to dekayi_count from the previous cell to get the total number of records.

# How many total S. Dekayi records are there?

6. Fetch up to 100 records

Use occ.search() to fetch occurrence records for Storeria dekayi.

Keep limit=100. Do not request more than 100 records for a species in this assignment.

dekayi_records = occ.search(
    speciesKey=__________,
    hasCoordinate=True,
    hasGeospatialIssue=False,
    limit=100,
)

dekayi_records.keys()

7. Turn the records into a table

The occurrence records are stored in the "results" key of the dekayi_records dictionary. Convert that list of records to a pandas DataFrame.

dekayi_df = pd.DataFrame(dekayi_records["__________"])
dekayi_df.head()

8. Keep a small set of useful columns

Keep the columns needed for a map and a few simple summaries.

Fill in the latitude column name.

dekayi_small = dekayi_df[
    ["key", "scientificName", "decimalLongitude", "__________", "year", "basisOfRecord", "countryCode"]
]

dekayi_small.head()

9. Convert the table to a GeoDataFrame

Use the longitude and latitude columns to create point geometry. This is the same idea as Lab 01 and Lab 02.

dekayi_gdf = gpd.GeoDataFrame(
    dekayi_small,
    geometry=gpd.points_from_xy(dekayi_small["__________"], dekayi_small["__________"]),
    crs="EPSG:4326",
)

dekayi_gdf["Species"] = "Storeria dekayi"
dekayi_gdf.head()

10. Map Storeria dekayi

Make an interactive map of the Storeria dekayi records.

__________.explore()

11. Repeat the workflow for Agkistrodon contortrix

Now repeat the same steps for eastern copperhead, Agkistrodon contortrix.

This cell should get the name suggestions and save the speciesKey.

contortrix_suggestions = species.name_suggest(q="Agkistrodon contortrix")

# Select the first element from the `contortrix_suggestions` list
contortrix_match = ___________________

# Get the `speciesKey`
contortrix_key = contortrix_match["__________"]

contortrix_key

13. Fetch and map Agkistrodon contortrix

Write code to fetch up to 100 records with coordinates, convert them to a table, convert that table to a GeoDataFrame, add a Species column, and map the result.

Use the same variable names shown in the comments. In occ.search(), use hasCoordinate=True and hasGeospatialIssue=False.

# Create contortrix_records with occ.search().

# Create contortrix_df from contortrix_records["results"].

# Create contortrix_small with the columns you want to keep.

# Create contortrix_gdf with gpd.GeoDataFrame().

# Add a Species column with the name Agkistrodon contortrix.

# Map contortrix_gdf with .explore().

14. Repeat the workflow for Pantherophis guttatus

This time you will do a little more on your own.

First, use species.name_suggest() to get the speciesKey for Pantherophis guttatus.

# Write your code here.

16. Fetch and map Pantherophis guttatus

Fetch up to 100 georeferenced records and convert them to a GeoDataFrame.

Keep the cell simple. It is fine to copy and modify code from earlier cells.

# Write your code here.

17. Combine the three GeoDataFrames

Use pd.concat() to combine your three species GeoDataFrames.

Then inspect the first few rows.

gbif_snakes = pd.concat([__________, __________, __________])

gbif_snakes.head()

18. Map all three species together

Use .explore() and color by Species so you can compare the three species on one map.

gbif_snakes.explore(column="__________", cmap="rainbow")

19. Count records by species

Use groupby() to count how many records you downloaded for each species.

gbif_snakes.groupby("__________").size()

20. Count records by basis of record

The countryCode field describes the general type of occurrence record.

Use groupby() to count records by countryCode.

gbif_snakes.groupby("__________").size()

21. Choose one additional species

Choose one additional snake species and repeat the workflow.

Your species does not have to be in the local EasternSnakes CSV files. It only needs to be a snake species that GBIF can find.

Your code should:

  • use species.name_suggest()
  • save the taxon key
  • count georeferenced records
  • fetch no more than 100 records with occ.search()
  • convert the records to a GeoDataFrame
  • map the records
# Write your code here.

22. Written reflection

Answer these questions after running your code.

Question 1: Which of your species had the most GBIF records available?

Your answer:

Question 2: Did the GBIF points look similar to the local CSV points from Assignment 01? Why might GBIF records look different?

Your answer:

Question 3: What is one reason it is useful to count records before downloading or mapping them?

Your answer:

23. Submit your work

Before submitting, make sure you have run the notebook from top to bottom and answered the written questions.

Commit and push your completed notebook to your class GitHub repository.

Open a terminal window and run these commands to add, commit, and push your notebook:

# Go to the labs directory in the course repo
cd ~/BIO597-SpatialBiodiversity/docs/assignments

# Add your changed lab
git add Assignment-02-pygbif.ipynb
git commit -m 'Finished Assignment 02'
git push