naturecounts

R package to access data from the NatureCounts platform by Bird Studies Canada

https://github.com/birdscanada/naturecounts

Keywords from Contributors

Repository

R package to access data from the NatureCounts platform by Bird Studies Canada

README.Rmd

---
output: github_document
---
 


```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```
# naturecounts


[![lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
[![R-CMD-check](https://github.com/BirdsCanada/naturecounts/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/BirdsCanada/naturecounts/actions/workflows/R-CMD-check.yaml)
![r-universe](https://birdscanada.r-universe.dev/badges/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](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.

Owner

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages