README.Rmd

---
output: github_document
---

```{r, echo = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.path = "man/figures/README-")
```

# wastdr <img src="man/figures/logo.png" align="right" />

<!-- 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/#active)
[![GitHub issues](https://img.shields.io/github/issues/dbca-wa/wastdr.svg?style=popout)](https://github.com/dbca-wa/wastdr/issues)
[![Last-changedate](https://img.shields.io/github/last-commit/dbca-wa/wastdr.svg)](https://github.com/dbca-wa/wastdr/commits/master)
[![tic](https://github.com/dbca-wa/wastdr/workflows/tic/badge.svg)](https://github.com/dbca-wa/wastdr/actions)
[![Test coverage](https://codecov.io/gh/dbca-wa/wastdr/branch/master/graph/badge.svg)](https://codecov.io/gh/dbca-wa/wastdr)
<!-- badges: end -->

The [WA Strandings Database WAStD](https://wastd.dbca.wa.gov.au/) 
([github](https://github.com/dbca-wa/wastd/)) 
provides a [RESTful API](https://wastd.dbca.wa.gov.au/api/1/). 
WAStD contains data about turtle strandings, turtle taggings, turtle track 
and nest encounters, and some ancillary data (areas, surveys, staff).
WAStD is accessible to authenticated staff of the 
WA Department of Biodiversity, Conservation and Attractions.
The WAStD API uses token and basic authentication, see vignette on details.

The API returns spatially explicit data as GeoJSON, which can be loaded directly 
into any standard-compliant GIS environments, e.g. [Quantum GIS](http://www.qgis.org/en/site/).

If the data consumer however wishes to analyse data in a statistical package like
R, the data need to be transformed from a nested list of lists (GeoJSON properties) 
into a two-dimensional tabular structure. This requires knowledge about the 
structure and content of the nested data from WAStD.

The main purpose of `wastdr` is to facilitate reading, parsing and using WAStD data
by providing helpers to access the API and flatten the API outputs into a 
[tidy](http://vita.had.co.nz/papers/tidy-data.html) `dplyr::tibble`.

The secondary purpose of `wastdr` is to centralize a collection of commonly used
analyses and visualisations of turtle data.
As development progresses, example analyses and visualisations will be added to 
the vignette. Contributions and requests are welcome!

Lastly, to facilitate collaboration with external stakeholders, `wastdr` contains
some anonymised example data (raw GeoJSON and parsed `tibble`) of turtle taggings, 
turtle track counts, and turtle nests.

## Installation

Install `wastdr` from GitHub. See also the top level `tic.R` file for other 
dependencies.

```{r, eval=FALSE}
# install.packages("devtools")
#
# https://github.com/r-spatial/mapview/issues/312
remotes::install_github(
  "r-spatial/mapview",
  dependencies = TRUE,
  upgrade = "always",
  force = TRUE,
  build_vignettes = TRUE
)

remotes::install_github(
  "ropensci/ruODK",
  dependencies = TRUE,
  upgrade = "always",
  force = TRUE,
  build_vignettes = TRUE
)

remotes::install_github(
  "dbca-wa/wastdr",
  dependencies = TRUE,
  upgrade = "always",
  build_vignettes = TRUE
)
```

While the WAStD API is only accessible to a selected audience, and `wastdr` is
under active development, it is not feasible to release `wastdr` on CRAN yet.
Therefore, `wastdr` will be distributed via GitHub for the time being.

## Setup
`wastdr` requires to be configured with the WAStD API URL and an access token or 
a username / password combination.
`wastdr` functions expect these settings to be available as environment variables.
For convenience, `wastdr_setup` sets the correct variables, while 
`wastdr_settings` retrieves the currently set values.

DBCA staff can find their WAStD API Token at [WAStD](https://wastd.dbca.wa.gov.au/) 
under "My Profile" and add to their `.Renviron`.
To use ODK Central turtle data download helpers, also add ODK Central 
credentials.

```{r, eval=F}
WASTDR_API_URL <- "https://wastd.dbca.wa.gov.au/api/1/"
WASTDR_API_TOKEN <- "Token XXX"
WASTDR_VERBOSE <- TRUE

ODKC_URL <- "https://odkcentral.dbca.wa.gov.au"
ODKC_UN <- "..."
ODKC_PW <- "..."
```

External collaborators can use their allocated WAStD username and password:

```{r, eval=F}
WASTDR_API_URL <- "https://wastd.dbca.wa.gov.au/api/1/"
WASTDR_API_UN <- "..."
WASTDR_API_PW <- "..."
WASTDR_VERBOSE <- TRUE

ODKC_URL <- "https://odkcentral.dbca.wa.gov.au"
ODKC_UN <- "..."
ODKC_PW <- "..."
```

Review the settings with:

```{r}
wastdr::wastdr_settings()
```

For other configuration methods please see the vignette "Setup".

## Get WAStD
Once set up, `wastdr` can load data from WAStD simply with:

```{r, eval=FALSE}
tracks <- "turtle-nest-encounters" %>%
  wastd_GET(max_records = 10) %>%
  parse_turtle_nest_encounters()
```

Valid endpoints are listed in the base API URL of WAStD, e.g.:

* `encounters`
* `animal-encounters`
* `turtle-nest-encounters`
* `turte-nest-disturbance-observations`

## ...or have a pickle
If you don't have access to the WAStD API, you can still get a feel for the data
by using the pickled example data:

```{r}
library(wastdr)

data("wastd_data")
data("odkc_data")

wastd_data

wastd_data$animals
wastd_data$tracks

wastd_data$tracks %>% map_tracks(sites = wastd_data$sites)
odkc_data$tracks %>% map_tracks_odkc(sites = odkc_data$sites)
```

## Learn more
See the vignettes for built-in helpers to transform, analyse and visualize 
WAStD data.

```{r, eval=FALSE}
vignette("getting-wastd", package = "wastdr")
vignette("analysis", package = "wastdr")
```

# Contribute
Every contribution, constructive feedback, or suggestion is welcome! 

Send us your ideas and requests as 
[issues](https://github.com/dbca-wa/wastdr/issues) or submit a pull request.

Pull requests should eventually pass tests and checks (not introducing new 
ERRORs, WARNINGs or NOTEs apart from the "New CRAN package" NOTE):

```{r, eval=FALSE}
styler:::style_pkg()
spelling::spell_check_package()
spelling::update_wordlist()
devtools::document(roclets = c("rd", "collate", "namespace", "vignette"))
devtools::build()
devtools::test()
devtools::check(force_suggests = T, args = c("--as-cran", "--timings"))
rcmdcheck::rcmdcheck()
goodpractice::goodpractice(quiet = F)
covr::codecov(token = Sys.getenv("CODECOV_TOKEN"))
usethis::use_version("patch")
```

To enable local testing of the API as well as checking and upload of test 
coverage, add your CODECOV token to your .Renviron:

```{r, eval=FALSE}
CODECOV_TOKEN <- "my-codecov-token"
```

The `wastdr` [webpage](https://dbca-wa.github.io/wastdr/) is hosted on
gh-pages and generated using [pkgdown](https://github.com/hadley/pkgdown).