-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
133 lines (104 loc) · 3.92 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
---
output:
github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
[![Travis-CI Build Status](https://travis-ci.org/parksandwildlife/biosysR.png?branch=master)](https://travis-ci.org/parksandwildlife/biosysR)
[![Coverage status](https://codecov.io/gh/parksandwildlife/biosysR/branch/master/graph/badge.svg)](https://codecov.io/github/parksandwildlife/biosysR?branch=master)
# biosysR makes BioSys data accessible in R
[BioSys](https://biosys.dbca.wa.gov.au/) 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](https://biosys.dbca.wa.gov.au/sso/api) and
[from scripts](https://biosys.dbca.wa.gov.au/api) protected (read and write)
through basicauth using a BioSys username and password.
The [BioSys API documentation](https://biosys-admin.dbca.wa.gov.au/api/explorer/)
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](http://vita.had.co.nz/papers/tidy-data.html) `dplyr::tibble`.
## Installation
Install `biosystR` from GitHub:
```{r, eval=FALSE}
# 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:
```{r setenv_session, eval=FALSE}
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
```{r projects}
projects <- biosysR::biosys_projects()
dplyr::glimpse(projects)
```
### BioSys datasets
```{r datasets}
datasets <- biosysR::biosys_datasets(project_id = 6)
dplyr::glimpse(datasets)
```
### BioSys records
```{r 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.
```{r example_data}
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)
```{r, eval=FALSE}
vignette("biosysR")
```
# Contribute
Every contribution, constructive feedback, or suggestion is welcome!
Send us your ideas and requests as
[issues](https://github.com/parksandwildlife/biosysr/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}
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:
```{r, eval=FALSE}
Sys.setenv(CODECOV_TOKEN=Sys.getenv("BIOSYS_CODECOV_TOKEN"))
covr::codecov()
```