naturecounts

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

Installation

You can install the main version of naturecounts from our R-Universe

install.packages("naturecounts", 
                 repos = c(birdscanada = 'https://birdscanada.r-universe.dev',
                           CRAN = 'https://cloud.r-project.org'))

Usage

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).

$ \text{r} \text{nc\_count}(\text{username} = "\text{sample}") #> # \text{A} \text{tibble}: 2 \times 4 #> \text{collection} \text{akn\_level} \text{access} \text{nrecords} #> <\text{chr}> <\text{int}> <\text{chr}> <\text{int}> #> 1 \text{SAMPLE1} 0 \text{full} 991 #> 2 \text{SAMPLE2} 0 \text{full} 995 $

Use the show = "all" argument to show counts for all collections available (public or otherwise).

$ \text{r} \text{nc\_count}(\text{show} = "\text{all}") %>% \text{head}() #> # \text{A} \text{tibble}: 6 \times 4 #> \text{collection} \text{akn\_level} \text{access} \text{nrecords} #> <\text{chr}> <\text{int}> <\text{chr}> <\text{int}> #> 1 \text{ABATLAS1} 5 \text{full} 122258 #> 2 \text{ABATLAS2} 5 \text{full} 201357 #> 3 \text{ABBIRDRECS} 5 \text{full} 357264 #> 4 \text{ABOWLS} 3 \text{by} \text{request} 20956 #> 5 \text{ACCWS} 3 \text{by} \text{request} 22889 #> 6 \text{ATBANS} 3 \text{by} \text{request} 267 $

Fetching data

Fetch all observations of bittern which are available to user sample into a local data frame.

First find the species id

$ \text{r} \text{search\_species}("\text{American} \text{Bittern}") #> # \text{A} \text{tibble}: 1 \times 5 #> \text{species\_id} \text{scientific\_name} \text{english\_name} \text{french\_name} \text{taxon\_group} #> <\text{int}> <\text{chr}> <\text{chr}> <\text{chr}> <\text{chr}> #> 1 2490 \text{Botaurus} \text{lentiginosus} \text{American} \text{Bittern} \text{Butor} \text{d}'\text{Am}é\text{rique} \text{BIRDS} $

Use this id with nc_data_dl(). The info parameter is a short description of what the data is being downloaded for.

bittern <- nc_data_dl(species = 2490, username = "sample", 
                    info = "readme_example")
#> Using filters: species (2490); fields_set (BMDE2.00-ext)
#> Collecting available records...
#>   collection nrecords
#> 1    SAMPLE1        1
#> Total records: 1
#> 
#> Downloading records for each collection:
#>   SAMPLE1
#>     Records 1 to 1 / 1

Alternatively, save the downloaded data as a SQLite database (bittern).

bittern <- nc_data_dl(species = 2490, sql_db = "bittern", username = "sample", 
                    info = "readme_example")
#> Using filters: species (2490); fields_set (BMDE2.00-ext)
#> Collecting available records...
#>   collection nrecords
#> 1    SAMPLE1        1
#> Total records: 1
#> 
#> Database 'bittern.nc' does not exist, creating it...
#> 
#> Downloading records for each collection:
#>   SAMPLE1
#>     Records 1 to 1 / 1

Authorizations

To access private/semi-public projects/collections you must sign up for a free NatureCounts account and register 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.

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(), nc_data_dl()) the following articles for more information on these filters:

• Collections
• Species Codes
• Regional Codes
• IBAs and BCRs (regions)
• Using spatial data to filter observations

We also have an article on post-filtering your data

Metadata

NatureCounts includes a great deal of metadata which can be accessed through the functions with the meta_ prefix. See the Meta Documentation for specifics.