forked from Public-Health-Scotland/phsmethods
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
209 lines (144 loc) · 9.83 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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
---
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-"
)
```
# phsmethods
[](https://github.com/Public-Health-Scotland/phsmethods/releases/latest)
[](https://travis-ci.com/Public-Health-Scotland/phsmethods)
[](https://codecov.io/gh/Public-Health-Scotland/phsmethods)
`phsmethods` contains functions for commonly undertaken analytical tasks in [Public Health Scotland (PHS)](https://www.publichealthscotland.scot/):
- `age_group()` categorises ages into groups
- `chi_check()` assesses the validity of a CHI number
- `chi_pad()` adds a leading zero to nine-digit CHI numbers
- `sex_from_chi()` extracts the sex of a person from a CHI number
- `file_size()` returns the names and sizes of files in a directory
- `fin_year()` assigns a date to a financial year in the format `YYYY/YY`
- `match_area()` converts geography codes into area names
- `postcode()` formats improperly recorded postcodes
- `qtr()`, `qtr_end()`, `qtr_next()` and `qtr_prev()` assign a date to a quarter
`phsmethods` can be used on both the [server](https://rstudio.nhsnss.scot.nhs.uk/) and desktop versions of RStudio.
## Installation
To install `phsmethods`, the package `remotes` is required, and can be installed with `install.packages("remotes")`.
You can then install `phsmethods` on RStudio server from GitHub with:
```{r gh-installation, eval = FALSE}
remotes::install_github("Public-Health-Scotland/phsmethods",
upgrade = "never"
)
```
Network security settings may prevent `remotes::install_github()` from working on RStudio desktop. If this is the case, `phsmethods` can be installed by downloading the [zip of the repository](https://github.com/Public-Health-Scotland/phsmethods/archive/master.zip) and running the following code (replacing the section marked `<>`, including the arrows themselves):
```{r source-installation, eval = FALSE}
remotes::install_local("<FILEPATH OF ZIPPED FILE>/phsmethods-master.zip",
upgrade = "never"
)
```
## Using phsmethods
Load `phsmethods` using `library()`:
```{r load}
library(phsmethods)
```
To access the help file for any of `phsmethods`' functions, type `?function_name` into the RStudio console after loading the package:
```{r help, eval = FALSE}
?fin_year
?postcode
```
### age_group
```{r age_group}
a <- c(54, 7, 77, 1, 26, 101)
# By default age_group goes in 5 year increments from 0 to 90+
age_group(a)
# But these settings can be changed
age_group(a, from = 0, to = 80, by = 10)
```
### chi_check
```{r chi_check, message = FALSE, warning = FALSE}
# chi_check returns specific feedback on why a CHI number might be invalid
library(dplyr)
b <- tibble(chi = c("0101011237", "0101336489", "3213201234", "123456789", "12345678900", "010120123?", NA))
b %>% mutate(validity = chi_check(chi))
```
### chi_pad
```{r chi_pad}
# Only nine-digit characters comprised exclusively of numeric digits are prefixed with a zero
chi_pad(c("101011237", "101201234", "123223", "abcdefghi", "12345tuvw"))
```
### sex_from_chi
```{r sex_from_chi}
# By default it will check that the CHI is valid before extracting the sex.
library(dplyr)
b <- tibble(chi = c("0101011237", "0101336489", "123456789", "12345678900", "010120123?", NA))
b %>% mutate(chi_sex = sex_from_chi(chi))
# Use custom values for male and female
b %>% mutate(chi_sex = sex_from_chi(chi, male_value = "M", female_value = "F"))
# Alternatively return the result as a factor (with labels 'Male' and 'Female')
b %>% mutate(chi_sex = sex_from_chi(chi, as_factor = TRUE))
```
### file_size
```{r file_size}
# Names and sizes of all files in the tests/testthat/files folder
file_size(testthat::test_path("files"))
# Names and sizes of Excel files only in the tests/testthat/files folder
file_size(testthat::test_path("files"), pattern = "\\.xlsx?$")
```
### fin_year
```{r fin_year}
c <- lubridate::dmy(c(21012017, 04042017, 17112017))
fin_year(c)
```
### match_area
```{r match_area}
match_area("S13002781")
d <- tibble(code = c("S02000656", "S02001042", "S08000020", "S12000013", "S13002605"))
d %>% mutate(name = match_area(code))
```
### postcode
```{r postcode, warning = FALSE}
# The default is pc7 format
postcode("G26QE")
# But pc8 format can also be applied
postcode(c("KA89NB", "PA152TY"), format = "pc8")
# postcode accounts for irregular spacing and lower case letters
e <- tibble(pc = c("G 4 2 9 B A", "g207al", "Dg98bS", "DD37J y"))
e %>% mutate(pc = postcode(pc))
```
### qtr, qtr_end, qtr_next and qtr_prev
```{r qtr}
f <- lubridate::dmy(c(26032012, 04052012, 23092012))
# qtr returns the current quarter and year
# The default is long format
qtr(f)
# But short format can also be applied
qtr(f, format = "short")
# qtr_end returns the last month in the quarter
qtr_end(f)
qtr_end(f, format = "short")
# qtr_next returns the next quarter
qtr_next(f)
qtr_next(f, format = "short")
# qtr_prev returns the previous quarter
qtr_prev(f)
qtr_prev(f, format = "short")
```
## Contributing to phsmethods
At present, the maintainers of this package are [David Caldwell](https://github.com/davidc92) and [Lucinda Lawrie](https://github.com/lucindalawrie).
This package is intended to be in continuous development and contributions may be made by anyone within PHS. If you would like to make a contribution, please first create an [issue](https://github.com/Public-Health-Scotland/phsmethods/issues) on GitHub and assign **both** of the package maintainers to it. This is to ensure that no duplication of effort occurs in the case of multiple people having the same idea. The package maintainers will discuss the issue and get back to you as soon as possible.
While the most obvious and eyecatching (as well as intimidating) way of contributing is by writing a function, this isn't the only way to make a useful contribution. Fixing typos in documentation, for example, isn't the most glamorous way to contribute, but is of great help to the package maintainers. Please see this [blogpost by Jim Hester](https://www.tidyverse.org/blog/2017/08/contributing/) for more information on getting started with contributing to open source software.
When contributing, please create a [branch](https://github.com/Public-Health-Scotland/phsmethods/branches) in this repository and carry out all work on it. Please ensure you have linked RStudio to your GitHub account using `usethis::edit_git_config()` prior to making your contribution. When you are ready for a review, please create a [pull request](https://github.com/Public-Health-Scotland/phsmethods/pulls) and assign **both** of the package maintainers as reviewers. One or both of them will conduct a review, provide feedback and, if necessary, request changes prior to merging your branch.
Please be mindful of information governance when contributing to this package. No data files (aside from publicly available and downloadable datasets or unless explicitly approved), server connection details, passwords or person identifiable or otherwise confidential information should be included anywhere within this package or any other repository (whether public or private) used within PHS. This includes within code and code commentary. For more information on security when using git and GitHub, and on using git and GitHub for version control more generally, please see the [Transforming Publishing Programme](https://www.isdscotland.org/Products-and-Services/Transforming-Publishing-Programme/)'s [Git guide](https://Public-Health-Scotland.github.io/git-guide/) and [GitHub guidance](https://github.com/Public-Health-Scotland/GitHub-guidance).
Please feel free to add yourself to the 'Authors' section of the `Description` file when contributing. As a rule of thumb, please assign your role as author (`"aut"`) when writing an exported function, and as contributor (`"ctb"`) for anything else.
`phsmethods` will, as much as possible, adhere to the [tidyverse style guide](https://style.tidyverse.org/) and the [rOpenSci package development guide](https://devguide.ropensci.org/). The most pertinent points to take from these are:
- All function names should be in lower case, with words separated by an underscore
- Put a space after a comma, never before
- Put a space before and after infix operators such as `<-`, `==` and `+`
- Limit code to 80 characters per line
- Function documentation should be generated using [`roxygen2`](https://github.com/r-lib/roxygen2)
- All functions should be tested using [`testthat`](https://github.com/r-lib/testthat)
- The package should always pass `devtools::check()`
It's not necessary to have experience with GitHub or of building an R package to contribute to `phsmethods`. If you wish to contribute code then, as long as you can write an R function, the package maintainers can assist with error handling, writing documentation, testing and other aspects of package development. It is advised, however, to consult [Hadley Wickham's R Packages book](https://r-pkgs.org/) prior to making a contribution. It may also be useful to consult the [documentation](https://github.com/Public-Health-Scotland/phsmethods/tree/master/R) and [tests](https://github.com/Public-Health-Scotland/phsmethods/tree/master/tests/testthat) of existing functions within this package as a point of reference.
Please note that this README may fail to 'Knit' at times as a result of network security settings. This will likely be due to the badges for the package's release version, continuous integration status and test coverage at the top of the document. If you are editing the `README.Rmd` document and are unable to successfully get it to 'Knit', please contact the package maintainers for assistance.