In parksandwildlife/biosysR: BioSys API Wrapper

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)

biosysR makes BioSys data accessible in R

BioSys is a data warehouse for biological survey data run by the Western Australian Department of Biodiversity, Conservation and Attractions (DBCA).

BioSys is accessible to DBCA staff behind a single-sign-on firewall, whereas the BioSys API is accessible both to staff (behind SSO firewall) through a GUI and from scripts protected (read and write) through basicauth using a BioSys username and password. The BioSys API documentation provides a graphical API browser.

The BioSys API returns JSON dictionaries of projects, datasets, records, and other entities.

If a data consumer wishes to analyse data in a statistical package like R, the data need to be transformed from a nested list of lists (JSON) into a two-dimensional tablular structure.

The main purpose of this R package, somewhat uncreatively named biosysR, is to facilitate accessing and using BioSys data by providing helpers to access the API and flatten the API outputs into a tidy dplyr::tibble.

Installation

Install biosystR from GitHub:

# install.packages("devtools")
devtools::install_github("parksandwildlife/biosysR")
library(biosysR)

Setup

The BioSys API is only accessible with basicauth using a valid Biosys username and password. To get up and running, execute the following commands with your own BioSys username and password:

Sys.setenv(BIOSYS_UN = "USERNAME")
Sys.setenv(BIOSYS_PW = "PASSWORD")

See the package vignette for a comprehensive run-down on BioSys API authentication and setup options.

Usage example

All examples assume that authentication credentials are available as environment variables. See the vignette for more authentication options.

BioSys projects

projects <- biosysR::biosys_projects()
dplyr::glimpse(projects)

BioSys datasets

datasets <- biosysR::biosys_datasets(project_id = 6)
dplyr::glimpse(datasets)

BioSys records

records <- biosysR::biosys_records(project_id = 6)
dplyr::glimpse(records)

Example data

In case the BioSys API is not accessible, a sample of available data is supplied.

data(projects)
data(datasets)
data(records)

dplyr::glimpse(projects)
dplyr::glimpse(datasets)
dplyr::glimpse(head(records))

Learn more

See the vignette for in-depth examples of authenticating, transforming, analysing and visualising BioSys data. (Note: work in progress)

vignette("biosysR")

Contribute

Every contribution, constructive feedback, or suggestion is welcome!

Send us your ideas and requests as 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):

devtools::document()
devtools::test()
pkgdown::build_site()
devtools::check(check_version = T, force_suggests = T, cran = T)

Code coverage is automatically calculated and reported from TravisCI. To manually submit code coverage reports, run:

Sys.setenv(CODECOV_TOKEN=Sys.getenv("BIOSYS_CODECOV_TOKEN"))
covr::codecov()

parksandwildlife/biosysR documentation built on May 15, 2019, 5:50 p.m.