DEVELOPERS.md

In ternaustralia/ausplotsR: TERN AusPlots Australian Ecosystem Monitoring Data

Loading development code in R

When you're hacking on this package locally, you can test it by installing from source:

1. change into the repo's root directory bash cd /path/to/git/ausplotsR/
2. start R bash R
3. make sure devtools and roxygen2 are installed, you only need to do this once R install.packages("devtools") install.packages("roxygen2")
4. install the dependencies for our package: R devtools::install_deps(pkg='.')
5. use the devtools::load_all (doco) function to load the package from source. There is no argument to this function as it looks in your current working directory: R # check your working directory with # getwd() # ...and set your working directory with # setwd('/path/to/dir') devtools::load_all()
6. if you make code changes, re-run devtools::load_all() to reload.

Override the API URL

The load_all() function defaults to exporting everything so you can access all package private functions to test them.

You might also want to change the URL of the API that is used (to your local machine?). To do so, we need to set an R option:

devtools::load_all()
options("ausplotsR_api_url" = "http://localhost:30000")
#...continue to call functions

You can check the current setting of the API URL with:

getOption("ausplotsR_api_url")

You can also set an option to turn on (or off) debug logs:

options("ausplotsR_api_debug" = TRUE)
#...continue to call functions

Running locally in a clean command line R environment (in Docker)

To test that the package can install into a fresh environment, we can use a Docker container. Note that this will use the repo you have locally, but it WILL NOT use dirty working directory state. It installs clean commits only.

1. start the container bash cd ausplotsR/ # root of this repo docker run \ --rm \ -it \ --name=ausplotsr-test \ -v `pwd`:/app \ zamora/r-devtools
2. in the container, install our package from the local source we mounted as a volume in the container R devtools::install_git('/app', ref = 'somebranch') # ref can be branch or commit
3. load our library R library(ausplotsR)
4. perform any other testing you need with the library

Running locally in a clean RStudio environment (in Docker)

If you prefer to use a GUI version of R, we can use an RStudio docker image:

1. start the container bash cd ausplotsR/ # root of this repo docker run \ -e PASSWORD=somepassword \ --rm \ --name=ausplotsr-test \ -v `pwd`:/app \ -p 8787:8787 \ rocker/tidyverse
2. open your browser to http://localhost:8787
3. login as rstudio with password somepassword
4. then run the install command the same as the command line version above. Or use the install from github commands.

Installing a branch from GitHub

To install a specific branch from GitHub, for example somebranch, use the following command:

devtools::install_github("ternaustralia/ausplotsR@somebranch")

Accessing unpublished data

For developers: the server-side mechanism to allow this is described in the docs for the server.

By default the public (unauthorised users) can only access site visits that are marked as published in the database.

The database also contains unpublished data. If you authorise yourself, you can access these unpublished records.

Follow these steps to access the unpublished site visits:

1. load the ausplotsR library like normal
2. configure some authorization to prove that you're allowed to access unpublished data. Note: this command is an example, you'll need to ask someone who maintains the ausplotsR database for the real role and secret values. R ausplotsR:::set_auth('somerole', 'somesecret')
3. now all queries you perform will include unpublished visit data
4. to return to only querying published data, run: R ausplotsR:::unset_auth()

The authorisation will expire. If you leave your R session open for a really long time, you might see an error like:

Error in .ausplots_api(path, query) : Unauthorized (HTTP 401).

If this is the case, re-run the set_auth() function and things should start working again.

ternaustralia/ausplotsR documentation built on Jan. 4, 2024, 8:36 a.m.