-
Notifications
You must be signed in to change notification settings - Fork 17
/
README.Rmd
290 lines (194 loc) · 8.85 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
# rebird: wrapper to the eBird API
<!-- badges: start -->
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/)
[![R-CMD-check](https://github.com/ropensci/rebird/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/rebird/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/ropensci/rebird/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ropensci/rebird?branch=master)
[![rstudio mirror downloads](https://cranlogs.r-pkg.org/badges/rebird)](https://github.com/r-hub/cranlogs.app)
[![cran version](https://www.r-pkg.org/badges/version/rebird)](https://cran.r-project.org/package=rebird/)
<!-- badges: end -->
`rebird` is a package to interface with the eBird webservices.
eBird is a real-time, online bird checklist program. For more information, visit their website: https://ebird.org/home
The API for the eBird webservices can be accessed here: https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest
## Install
You can install the stable version from CRAN
```{r eval=FALSE}
install.packages("rebird")
```
Or the development version from Github
```{r eval=FALSE}
install.packages("devtools")
devtools::install_github("ropensci/rebird")
```
# Direct use of `rebird`
Load the package:
```{r}
library("rebird")
```
The [eBird API server](https://documenter.getpostman.com/view/664302/S1ENwy59?version=latest)
requires users to provide an API key, which is linked to your eBird user account.
You can pass it to the 'key' argument in `rebird` functions, but we highly recommend
storing it as an environment variable called EBIRD_KEY in your .Renviron file.
If you don't have a key, you can obtain one from <https://ebird.org/api/keygen>.
You can keep your .Renviron file in your global R home directory (`R.home()`), your user's home
directory (`Sys.getenv("HOME")`), or your current working directory (`getwd()`). Remember
that .Renviron is loaded once when you start R, so if you add your API key to the file you will
have to restart your R session. See `?Startup` for more information on R's startup files.
Furthermore, functions now use species codes, rather than scientific names, for species-specific requests.
We've made the switch easy by providing the `species_code` function, which converts a scientific name to
its species code:
```{r speciescode}
species_code('sula variegata')
```
The `species_code` function can be called within other `rebird` functions, or the species code
can be specified directly.
## eBird Taxonomy
The eBird taxonomy is internally stored in `rebird` and can be called using
```{r tax}
rebird::tax
```
While the internal taxonomy is kept up to date with each package release, it could
be outdated if a new taxonomy is made available before the package is updated.
You can obtain the latest eBird taxonomy by
```{r taxonomy, eval=FALSE}
new_tax <- ebirdtaxonomy()
```
## Sightings at location determined by latitude/longitude
Search for bird occurrences by latitude and longitude point
```{r ebirdgeo1}
ebirdgeo(species = species_code('spinus tristis'), lat = 42, lng = -76)
```
## Recent observations at a region
Search for bird occurrences by region and species name
```{r ebirdregion1}
ebirdregion(loc = 'US', species = 'btbwar')
```
## Recent observations at hotspots
Search for bird occurrences by a given hotspot
```{r ebirdhotspot}
ebirdregion(loc = 'L99381')
```
## Nearest observations of a species
Search for a species' occurrences near a given latitude and longitude
```{r nearestobs}
nearestobs(species_code('branta canadensis'), 42, -76)
```
<!--
## Frequency of observations at hotspots or regions
Obtain historical frequencies of bird occurrences by hotspot or region
```{r ebirdfreq}
# ebirdfreq(loctype = 'hotspots', loc = 'L196159')
```
-->
## Recent notable sightings
Search for notable sightings at a given latitude and longitude
```{r ebirdnotable1}
ebirdnotable(lat = 42, lng = -70)
```
or a region
```{r ebirdnotable2}
ebirdnotable(locID = 'US-NY-109')
```
## Historic Observations
Obtain a list of species reported on a specific date in a given region
```{r ebirdhistorical1}
ebirdhistorical(loc = 'US-VA-003', date = '2019-02-14',max = 10)
```
or a hotspot
```{r ebirdhistorical2}
ebirdhistorical(loc = 'L196159', date = '2019-02-14', fieldSet = 'full')
```
## Information on a given region or hotspot
Obtain detailed information on any valid eBird region
```{r ebirdregioninfo1}
ebirdregioninfo("CA-BC-GV")
```
or hotspot
```{r ebirdregioninfo2}
ebirdregioninfo("L196159")
```
Obtain a list of eBird species codes for all species recorded in a region
```{r ebirdregionspecies1}
ebirdregionspecies("GB-ENG-LND")
```
or a hotspot
```{r ebirdregionspecies2}
ebirdregionspecies("L5803024")
```
Obtain a list of all subregions within an eBird region
```{r ebirdsubregionlist}
ebirdsubregionlist("subnational1","US")
```
## Checklist Feed
Obtain a list of checklists submitted on a given date at a region or hotspot
```{r ebirdchecklistfeed}
ebirdchecklistfeed(loc = "L207391", date = "2020-03-24", max = 5)
```
## View Checklist
Obtain all information on a specific checklist
```{r ebirdchecklist}
ebirdchecklist("S139153079")
```
## Hotspots in a region or nearby coordinates
Obtain a list of hotspots within a region
```{r ebirdhotspotlist1}
ebirdhotspotlist("CA-NS-HL")
```
or within a radius of up to 50 kilometers, from a given set of coordinates.
```{r ebirdhotspotlist2}
ebirdhotspotlist(lat = 30, lng = -90, dist = 10)
```
## `rebird` and other packages
### How to use `rebird`
This package is part of a richer suite called [spocc - Species Occurrence Data](https://github.com/ropensci/spocc), along with several other packages, that provide access to occurrence records from multiple databases. We recommend using `spocc` as the primary R interface to `rebird` unless your needs are limited to this single source.
### `auk` vs. `rebird`
Those interested in eBird data may also want to consider [`auk`](https://github.com/CornellLabofOrnithology/auk), an R package that helps extracting and processing the whole eBird dataset. The functions in `rebird` are faster but mostly limited to accessing recent (i.e. within the last 30 days) observations, although `ebirdfreq()` does provide historical frequency of observation data. In contrast, `auk` gives access to the full set of ~ 500 million eBird observations. For most ecological applications, users will require `auk`; however, for some use cases, e.g. building tools for birders, `rebird` provides a quicker and easier way to access data. `rebird` and `auk` are both part of the rOpenSci project.
## API requests covered by `rebird`
The 2.0 APIs have considerably been expanded from the previous version, and `rebird` only covers some of them. The webservices covered are listed below; if you'd like to contribute wrappers to APIs not yet covered by this package, feel free to submit a pull request!
### data/obs
- [x] Recent observations in a region: `ebirdregion()`
- [x] Recent notable observations in a region: `ebirdnotable()`
- [x] Recent observations of a species in a region: `ebirdregion()`
- [x] Recent nearby observations: `ebirdgeo()`
- [x] Recent nearby observations of a species: `ebirdgeo()`
- [x] Nearest observations of a species: `nearestobs()`
- [x] Recent nearby notable observations: `ebirdnotable()`
- [ ] Recent checklists feed
- [x] Historic observations on a date: `ebirdhistorical()`
### product
- [ ] Top 100
- [x] Checklist feed on a date: `ebirdchecklistfeed()`
- [ ] Regional statistics on a date
- [x] Species list for a region: `ebirdregionspecies()`
- [x] View Checklist: `ebirdchecklist()`
### ref/geo
- [ ] Adjacent Regions
### ref/hotspot
- [x] Hotspots in a region: `ebirdhotspotlist()`
- [x] Nearby hotspots: `ebirdhotspotlist()`
- [x] Hotspot Info: `ebirdregioninfo()`
### ref/taxonomy
- [x] eBird Taxonomy: `ebirdtaxonomy()`
- [ ] Taxonomic Forms
- [x] Taxonomy Versions: `ebirdtaxonomyversion()`
- [ ] Taxonomic Groups
### ref/region
- [x] Region Info: `ebirdregioninfo()`
- [x] Sub Region List: `ebirdsubregionlist()`
## Meta
* Please [report any issues or bugs](https://github.com/ropensci/rebird/issues).
* License: MIT
* Get citation information for `rebird` in R doing `citation(package = 'rebird')`
* Please note that the 'rebird' project is released with a [Contributor Code of Conduct][coc]. By contributing to this project, you agree to abide by its terms.
[![ropensci_footer](https://ropensci.org/public_images/github_footer.png)](https://ropensci.org/)
[coc]: https://github.com/ropensci/rebird/blob/master/CODE_OF_CONDUCT.md