lifecycle

Access and download data on plant and animal populations from various databases through NatureCounts, a service managed by Bird Studies Canada.

See tutorials, documentation and articles on the naturecounts package Website

Installation

You can install this developmental version of naturecounts from GitHub with the remotes package:

install.packages("remotes")
remotes::install_github("BirdStudiesCanada/naturecounts")

Usage

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

nc_count(username = "sample")
#> # A tibble: 2 x 4
#>   collection akn_level access nrecords
#>   <chr>          <int> <chr>     <int>
#> 1 SAMPLE1            0 full        994
#> 2 SAMPLE2            0 full        997

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

nc_count(show = "all") %>%
  head()
#> # A tibble: 6 x 4
#>   collection akn_level access     nrecords
#>   <chr>          <int> <chr>         <int>
#> 1 ABATLAS1           5 full         123364
#> 2 ABATLAS2           5 full         201382
#> 3 ABBIRDRECS         5 full         357264
#> 4 ABOWLS             4 by request        0
#> 5 ATBBS              4 by request        0
#> 6 ATOWLS             4 by request    25250

Fetching data

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

First find the species id

search_species("American Bittern")
#> # A tibble: 1 x 5
#>   species_id scientific_name       english_name     french_name      taxon_group
#>        <int> <chr>                 <chr>            <chr>            <chr>      
#> 1       2490 Botaurus lentiginosus American Bittern Butor d'Amérique 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-min)
#> 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-min)
#> 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:

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.