# Installation
To install this package directly from git, you will first need the devtools package if not already installed:
```
install.packages(c("devtools"))
```

Then, the ASPREE package itself can be installed using the following command:
```
devtools::install_git("https://gitlab.erc.monash.edu.au/aspree/aspree-r-package.git")
```
You will be prompted for your Monash GitLab credentials before installation proceeds.

Here's an example using the ASPREE library to retrieve ASPREE XT consent status:
```
library(aspree)
library(dplyr)

aspreeConsent <- aspreeDb("ASPREE Data Snapshot") %>% getXTConsent()
```

# Development

Recommended reading: [the devtools cheatsheet](https://www.rstudio.com/wp-content/uploads/2015/03/devtools-cheatsheet.pdf)

## Quick-start: Eight steps to writing a new function
1. Create or open an appropriate .R file inside the [R subdirectory](R)
2. Write your code, but don't include any `library` or `require` statements
3. Write the documentation (in roxygen format) above the function, adding `@import` or `@importFrom` to the roxygen code for any library that you would otherwise load with `library`. [Note that best practise is to be explicit](http://kbroman.org/pkg_primer/pages/depends.html), using the `::` operator to select the function directly from any package. In other words, try to avoid importing entire packages altogether.
4. Add `@export` to the documentation if this function is intended to be exposed to the end-user
5. Declare any additional dependencies (things that would need to be installed using `install.packages()`) by running `devtools::use_package("package-name")` for each required package, which will automatically update the `DESCRIPTION` file
6. (Try to) [write tests](tests/testthat)
7. Run `devtools::document()` to update `NAMESPACE` and the files inside `man`
8. Commit all the changes to git, and merge to the main repository

Regarding point (3), an example comparing the `library` statement with calling functions explicity, consider the following:
```
# Loading the libraries
library(DBI)
library(odbc)
con <- dbConnection(odbc(), "My Database")

# Explicitly calling each function
con <- DBI::dbConnection(odbc::odbc(), "My Database")
```
In the latter case, the programmer has no confusion about where each function originated, whereas the former relies upon the programmer having prior knowledge about the structure of the `DBI` and `odbc` packages.

## Dependencies
Package dependencies must be declared in the [DESCRIPTION](DESCRIPTION) file. Use the `devtools::use_package()` function to add these automatically.

## Documentation
Use the `roxygen` to document every function that needs to be visible to the end-user. Roxygen documentation can be provided by writing specially formatted comments above each function. An example from [the devtools cheatsheet](https://www.rstudio.com/wp-content/uploads/2015/03/devtools-cheatsheet.pdf):

```
#' Add together two numbers.
#'
#' @param x A number.
#' @param y A number.
#' @return The sum of \code{x} and \code{y}.
#' @examples
#' add(1, 1)
#' @export
add <- function(x, y) {
    x + y
}
```

The documentation should describe at least
* What the function does
* Each function parameter
* The data returned

If the function needs to be visible to the end user, it should also tag the function with `@export`.

Once the functions are written, tested and documented, `devtools::document()` should be run. This will regenerate `NAMESPACE` and the markdown documents in the `man` directory appropriately.

## Testing and quality control
All functions should be appropriately unit tested, ideally using the automated test framework `testthat`. More detail information regarding tests can be found in the [tests/testthat](tests/testthat) subdirectory.

Tests should be written in a way that:
* will detect when errors in dependent functions or the underlying data arises
* tests the behaviour when both valid and invalid data is provided, e.g. `sqrt(x)` should not be defined if a negative input is given
* never has an external dependency, e.g. pre-canned (fake) data should be provided to simulate database access

All changes should be proposed via GitLab merge requests and reviewed prior to acceptance. [Git `tags`](https://git-scm.com/book/en/v2/Git-Basics-Tagging) should be used to mark major releases to allow for reproducible analysis. Insofar as practical, git commits merged into the master branch should be squashed into units that sensibly describe their net effect.

### Running the tests
Tests can be run using `devtools::test()` with output that resembles the following:
```
> devtools::test()
Loading aspree
Testing aspree
✔ | OK F W S | Context
✔ | 77       | Generate longitudinal dataset file paths
✔ |  9       | Get demographic info

══ Results ════════════════════════════════════════════════════
Duration: 0.2 s

OK:       86
Failed:   0
Warnings: 0
Skipped:  0
```
The more automated sanity checks, the better!