-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathREADME.Rmd
108 lines (77 loc) · 4.42 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# naturecounts
<!-- badges: start -->
[](https://www.tidyverse.org/lifecycle/#experimental)
[](https://github.com/BirdsCanada/naturecounts/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
Access and download data on plant and animal populations from various databases through NatureCounts, a service managed by Birds Canada.
See tutorials, documentation and articles on the [naturecounts package Website](https://birdscanada.github.io/naturecounts)
## Installation
You can install the main version of `naturecounts` from our R-Universe
```{r eval = FALSE}
install.packages("naturecounts",
repos = c(birdscanada = 'https://birdscanada.r-universe.dev',
CRAN = 'https://cloud.r-project.org'))
```
## Usage
```{r}
library(naturecounts)
```
### Fetching counts
Use the `nc_count()` function to return collections and the number of observations in each for which you have access (here returns all collections associated with username **sample**).
```{r}
nc_count(username = "sample")
```
Use the `show = "all"` argument to show counts for all collections available (public or otherwise).
```{r}
nc_count(show = "all") %>%
head()
```
### Fetching data
Fetch all observations of bittern which are available to user **sample** into a local data frame.
First find the species id
```{r}
search_species("American Bittern")
```
Use this id with `nc_data_dl()`. The `info` parameter is a short description of what the data is being downloaded for.
```{r}
bittern <- nc_data_dl(species = 2490, username = "sample",
info = "readme_example")
```
Alternatively, save the downloaded data as a SQLite database (`bittern`).
```{r}
bittern <- nc_data_dl(species = 2490, sql_db = "bittern", username = "sample",
info = "readme_example")
```
```{r cleanup, include = FALSE}
file.remove("bittern.nc")
```
### Authorizations
To access private/semi-public projects/collections you must [sign up](https://www.birdscanada.org/birdmon/default/profile.jsp) for a free NatureCounts account and [register](https://www.birdscanada.org/birdmon/default/projects.jsp) for the projects you'd like to access. Once registered, you can use the `username` argument (you will be prompted for a password) for both `nc_count()` and `nc_data_dl()`, which will then return a different set of records.
```{r, eval = FALSE}
nc_count(username = "my_user_name")
bittern <- nc_data_dl(species = 2490, username = "my_user_name", info = "readme_example")
```
### More advanced options
`nc_count()` and `nc_data_dl()` have a variety of arguments that allow you to filter the counts/data prior to downloading. These options include `collections`, `species`, `years`, `doy` (day-of-year), `region`, and `site_type` (users can specify up to 3 of these). For `nc_data_dl()` you have the additional arguments `fields_set` and `fields` with which you can customize which fields/columns to include in your download.
See the function examples ([`nc_count()`](https://birdscanada.github.io/naturecounts/reference/nc_count.html), [`nc_data_dl()`](https://birdscanada.github.io/naturecounts/reference/nc_data_dl.html)) the following articles for more information on these filters:
- Collections
- [Species Codes](https://birdscanada.github.io/naturecounts/articles/species-codes.html)
- [Regional Codes](https://birdscanada.github.io/naturecounts/articles/region-codes.html)
- [IBAs and BCRs (regions)](https://birdscanada.github.io/naturecounts/articles/region-areas.html)
- [Using spatial data to filter observations](https://birdscanada.github.io/naturecounts/articles/region-spatial.html)
We also have an [article on post-filtering your data](https://birdscanada.github.io/naturecounts/articles/filtering-data.html)
### Metadata
NatureCounts includes a great deal of metadata which can be accessed through the functions with the `meta_` prefix. See the [Meta Documentation](https://birdscanada.github.io/naturecounts/reference/meta.html) for specifics.