README.md 4.96 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
18
19
20
Here's an example using the ASPREE library to retrieve ASPREE XT consent status:
```
library(aspree)
library(dplyr)

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

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!