lifeR is an R package for identifying locations to visit in order to increase your bird species list count. The package relies on the eBird API to query for recent observations and compare them to a user’s species list. The lists can be life lists, year lists, etc. The primary output is a report of sites to visit in a region where species not on the user’s list have been reported recently.
You can install lifeR from CRAN via:
Alternatively, you can download the development version from GitHub with the help of the remotes package:
If you install from GitHub and want to have the introductory vignette
included in the installation, then pass
build_vignettes = TRUE
in the call to
install_github()
:
You will need a minimum of three pieces of information to use lifeR:
Because lifeR relies on the public eBird API, you will need to have your own unique API key to use this package. Visit https://ebird.org/api/keygen to get an eBird API key (note you will be prompted to log into your eBird account). The key will be a random string of letters and numbers. I suggest you copy the key and save it to a plain text file on your computer; you can use a program like Notepad or TextEdit to create plain text files. Save this file somewhere you will remember (like “My Documents”) and name it something that is recognizable (e.g. “ebird-api-key.txt”). We will use this file later to access the eBird API.
This should be a list of the species you have already seen, but it can vary based on the list you would like to add species to. If you want to find sites where birds you have never seen have been observed recently, you would use your life list. If you are working on a Big Year, you would use your year list. Trying to break 300 species for your Arizona year list? Then yes, use your Arizona species list for the current year. These can all be downloaded from your eBird account by going to https://ebird.org/lifelist/, using the dropdown menus near the top of the page to select the region and time range of your list, then downloading the list through the “Download (csv)” link near the upper-right corner of the page. Save the file somewhere where you will remember where it is.
Finally, lifeR is designed to identify sites in a region for you to visit. Therefore, you will need to provide information on where that region is. The package uses a latitude and longitude coordinates to serve as the “center” of the region of interest and finds sites within a certain radius of that center. The maximum radius is 50 kilometers - if you want to search a larger area, you will just need to define two centers (information on doing this is provided below). If you do not know the latitude and longitude of your “center” I recommend Google Maps, which allows you to right- or control-click on a location on a map, and the latitude and longitude coordinates will be displayed. Note lifeR requires decimal degree formatted data (e.g. -110.92, not 110° 55’ 12”).
Now that you have those three pieces of information, you can build a report of sites to visit.
This example creates a report from a single center, near McCall, Idaho, USA. It uses one function from lifeR:
SitesReport
a function that handles all the querying of
eBird, comparing lists, and building the reportlibrary(lifeR)
# To use the sample list included in this package
list_file <- system.file("extdata", "example-list.csv", package = "lifeR")
# If you have your list file downloaded, replace the line above with one that
# indicates the location of your list file, e.g.
# list_file <- "~/Desktop/ebird_world_year_2021_list.csv"
# Read the list of species into memory
user_list <- read.csv(file = list_file)
# Extract the common names of species from your list
my_species <- user_list$Common.Name
# Read in eBird API key from a text file; replace the argument to file with
# the actual location of your eBird key file
key <- scan(file = "ebird-api-key.txt", what = "character")
# A single center requires vector of coordinates
# Change these, unless you really want to go birding near McCall, Idaho
locs <- c(45, -116)
SitesReport(centers = locs,
ebird_key = key,
species_seen = my_species)
The resulting report will be called Goals-Report.html and you can open it in your favorite web browser.
NB: If the list file you are using was downloaded prior to 2023, the
format was different - the common and scientific names were combined in
a single column (called Species
) that needed to be split.
If your list is one of these older downloads, you will need to replace
this line:
with this:
The line above will use SplitNames()
, a helper function
to deal with the format of species names returned from eBird for older
downloads. Note this is only necessary if the download was
prior to 2023. If you are using your list from 2015 that you downloaded
yesterday, you do not need to use the SplitNames()
function
(i.e. just use my_species <- user_list$Common
).
The example above only uses one center on which to base searches and does not provide a name for that center (it will be given the default name of “Center 1” in the report). In the example below, we provide two starting points. Note that a list of nearby sites for each starting point will be included in the results. That is, the report will include the top five sites near the first set of latitude and longitude coordinates and the top five sites near the second set of latitude and longitude coordinates. The example assumes you have loaded in your species list and the location of your eBird API key file as in the first example, above.
# For more than one location, centers can be a matrix or a data frame, here
# we use a matrix of two sites
loc_mat <- matrix(data = c(39.5, -118.8, 39, -119.1), nrow = 2, byrow = TRUE)
# Instead of default "Center 1" and "Center 2", we can use custom names
loc_names <- c("Fallon", "Yerington")
# Sites report now uses loc_names in the output
SitesReport(centers = loc_mat,
ebird_key = key,
species_seen = my_species,
center_names = loc_names)
The SitesReport
can also accommodate a data frame of
latitude and longitude coordinates. You can also give your report a
different name (with report_filename
) and specify where it
is saved (with report_dir
).
loc_df <- data.frame(latitude = c(39.5, 39, 40),
longitude = c(-118.8, -119.1, -118.6))
loc_names <- c("Fallon", "Yerington", "Humbolt Wildlife")
# We can set the area to search by passing values to the dist argument
SitesReport(centers = loc_df,
ebird_key = key,
dist = 25,
species_seen = my_species,
center_names = loc_names,
report_filename = "Nevada-sites",
report_dir = "~/Desktop") # Saves report to desktop
SitesReport
and few or no sites are
being returned, try:
The main goal, identifying sites to visit to find species you have
yet to see, uses eBird’s API to query for recent local observations.
Specifically, the SitesReport
function:
Perhaps you are asking yourself “what is the difference between steps 1 and 3?” The two separate queries are required because the first only returns the most recent observation of each species for a given region. That is, even though the Black-bellied Whistling Duck has been seen at 14 nearby sites, only the most recent observation (and therefore locality information) is returned by eBird in step 1. It is not until step 3 where we retrieve all the sites at which that species was recently seen.
SitesReport()
.