README.md 4.95 KB
Newer Older
Jason Rigby's avatar
Jason Rigby committed
1
# Installation
Jason Rigby's avatar
Jason Rigby committed
2
To install this package directly from git, you will first need the devtools package if not already installed:
Jason Rigby's avatar
Jason Rigby committed
3
```
Jason Rigby's avatar
Jason Rigby committed
4
install.packages(c("devtools"))
Jason Rigby's avatar
Jason Rigby committed
5 6
```

Jason Rigby's avatar
Jason Rigby committed
7 8
Then, the ASPREE package itself can be installed using the following command:
```
9
devtools::install_git("https://gitlab.erc.monash.edu.au/aspree/aspree-r-package.git")
Jason Rigby's avatar
Jason Rigby committed
10 11
```
You will be prompted for your Monash GitLab credentials before installation proceeds.
Jason Rigby's avatar
Jason Rigby committed
12

Jason Rigby's avatar
Jason Rigby committed
13 14 15 16 17
Here's an example using the ASPREE library to retrieve ASPREE XT consent status:
```
library(aspree)
library(dplyr)

18
aspreeConsent <- ASPREEDb("ASPREE Data Live") %>% GetXTConsent()
Jason Rigby's avatar
Jason Rigby committed
19 20
```

Jason Rigby's avatar
Jason Rigby committed
21 22 23 24
# Development

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

Jason Rigby's avatar
Jason Rigby committed
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
## 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.

Jason Rigby's avatar
Jason Rigby committed
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
## 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:
Jason Rigby's avatar
Jason Rigby committed
80
* will detect when errors in dependent functions or the underlying data arises
Jason Rigby's avatar
Jason Rigby committed
81 82 83 84
* 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.
Jason Rigby's avatar
Jason Rigby committed
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104

### 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!