Merge pull request #10 from Health-SocialCare-Scotland/readme

Readme

.Rbuildignore

@@ -2,3 +2,5 @@
 ^\.Rproj\.user$
 ^codecov\.yml$
 ^\.travis\.yml$
+^README\.Rmd$
+^README-.*\.png$

DESCRIPTION

@@ -3,6 +3,8 @@ Title: Standard Methods for use in PHI
 Version: 0.0.0.9000
 Authors@R: c(
     person("Jack", "Hannah", email = "[email protected]", role = c("aut", "cre")),
+    person("David", "Caldwell", email = "[email protected]", role = c("aut", "rev")),
+    person("Lucinda", "Lawrie", email = "[email protected]", role = "rev"),
     person("Tina", "Fu", email = "[email protected]", role = "aut"),
     person("Ciara", "Gribben", email = "[email protected]", role = "aut")
     )

NAMESPACE

@@ -3,7 +3,8 @@
 export(file_size)
 export(fin_year)
 export(postcode)
+export(qtr)
 export(qtr_end)
+export(qtr_next)
 export(qtr_prev)
-export(qtr_year)
 importFrom(magrittr,"%>%")

NEWS.md

@@ -0,0 +1,4 @@
+# phimethods 0.1.0
+
+- Initial package release
+- `file_size`, `fin_year`, `postcode`, `qtr`, `qtr_end`, `qtr_next` and `qtr_prev` functions added

R/file_size.R

@@ -104,18 +104,18 @@ file_size <- function(filepath = getwd(), pattern = NULL) {
     trimws()
 
   z <- dplyr::case_when(
-    stringr::str_detect(x, ".xls(b|m|x)?$") ~ "Excel ",
-    stringr::str_detect(x, ".csv$") ~ "CSV ",
-    stringr::str_detect(x, ".z?sav$") ~ "SPSS ",
-    stringr::str_detect(x, ".doc(m|x)?$") ~ "Word ",
-    stringr::str_detect(x, ".rds$") ~ "RDS ",
-    stringr::str_detect(x, ".txt$") ~ "Text ",
-    stringr::str_detect(x, ".fst$") ~ "FST ",
-    stringr::str_detect(x, ".pdf$") ~ "PDF ",
-    stringr::str_detect(x, ".tsv$") ~ "TSV ",
-    stringr::str_detect(x, ".html$") ~ "HTML ",
-    stringr::str_detect(x, ".ppt(m|x)?$") ~ "PowerPoint ",
-    stringr::str_detect(x, ".md$") ~ "Markdown ",
+    stringr::str_detect(x, "\\.xls(b|m|x)?$") ~ "Excel ",
+    stringr::str_detect(x, "\\.csv$") ~ "CSV ",
+    stringr::str_detect(x, "\\.z?sav$") ~ "SPSS ",
+    stringr::str_detect(x, "\\.doc(m|x)?$") ~ "Word ",
+    stringr::str_detect(x, "\\.rds$") ~ "RDS ",
+    stringr::str_detect(x, "\\.txt$") ~ "Text ",
+    stringr::str_detect(x, "\\.fst$") ~ "FST ",
+    stringr::str_detect(x, "\\.pdf$") ~ "PDF ",
+    stringr::str_detect(x, "\\.tsv$") ~ "TSV ",
+    stringr::str_detect(x, "\\.html$") ~ "HTML ",
+    stringr::str_detect(x, "\\.ppt(m|x)?$") ~ "PowerPoint ",
+    stringr::str_detect(x, "\\.md$") ~ "Markdown ",
     TRUE ~ ""
   )
 

R/fin_year.R

@@ -10,7 +10,7 @@
 #' be used to change a variable to date class.
 #'
 #' @examples
-#' x <- lubridate::dmy(c("21012017", "04042017", "17112017"))
+#' x <- lubridate::dmy(c(21012017, 04042017, 17112017))
 #'
 #' fin_year(x)
 #'

R/qtr.R

@@ -3,36 +3,47 @@
 #' @description
 #'
 #' The qtr functions take a date input and calculate the relevant
-#' quarter-related value from it.
+#' quarter-related value from it. They all return the year as part of this
+#' value.
 #'
 #' \itemize{
-#' \item \code{qtr_year} returns the current quarter and year in either short or
-#' long format.
+#' \item \code{qtr} returns the current quarter.
 #'
-#' \item \code{qtr_end} returns the last month in the quarter in either short or
-#' long format.
+#' \item \code{qtr_end} returns the last month in the quarter.
 #'
-#' \item \code{qtr_prev} returns the previous quarter in either short or long
-#' format.
+#' \item \code{qtr_next} returns the next quarter.
+#'
+#' \item \code{qtr_prev} returns the previous quarter.
+#' }
+#'
+#' @details Quarters are defined as:
+#'
+#' \itemize{
+#' \item January to March (Jan-Mar)
+#' \item April to June (Apr-Jun)
+#' \item July to September (Jul-Sep)
+#' \item October to December (Oct-Dec)
 #' }
 #'
 #' @param date A date supplied with \code{Date} class.
 #' @param format A \code{character} string specifying the format the quarter
-#' should be displayed in. Valid options are `short` (Jan-Mar 2018) and `long`
-#' (January to March 2018). The default is `long`.
+#' should be displayed in. Valid options are `long` (January to March 2018) and
+#' `short` (Jan-Mar 2018). The default is `long`.
 #'
 #' @examples
-#' x <- lubridate::dmy(c("26032012", "04052012", "23092012"))
+#' x <- lubridate::dmy(c(26032012, 04052012, 23092012))
 #'
-#' qtr_year(x, format = "long")
+#' qtr(x)
 #'
 #' qtr_end(x, format = "short")
 #'
-#' qtr_prev(x, format = "long")
+#' qtr_next(x)
+#'
+#' qtr_prev(x, format = "short")
 
 #' @export
-#' @rdname qtr_year
-qtr_year <- function(date, format = c("long", "short")) {
+#' @rdname qtr
+qtr <- function(date, format = c("long", "short")) {
 
   format <- match.arg(format)
 
@@ -66,7 +77,7 @@ qtr_year <- function(date, format = c("long", "short")) {
 }
 
 #' @export
-#' @rdname qtr_year
+#' @rdname qtr
 qtr_end <- function(date, format = c("long", "short")) {
 
   format <- match.arg(format)
@@ -101,7 +112,42 @@ qtr_end <- function(date, format = c("long", "short")) {
 }
 
 #' @export
-#' @rdname qtr_year
+#' @rdname qtr
+qtr_next <- function(date, format = c("long", "short")) {
+
+  format <- match.arg(format)
+
+  if (class(date) != "Date") {
+    stop("The input must have Date class")
+  }
+
+  quarter_num <- lubridate::quarter(date)
+
+  if (format == "long") {
+    return(dplyr::case_when(
+      quarter_num == 1 ~ paste0("April to June ",
+                                lubridate::year(date)),
+      quarter_num == 2 ~ paste0("July to September ",
+                                lubridate::year(date)),
+      quarter_num == 3 ~ paste0("October to December ",
+                                lubridate::year(date)),
+      quarter_num == 4 ~ paste0("January to March ",
+                                lubridate::year(date) + 1)))
+  } else {
+    return(dplyr::case_when(
+      quarter_num == 1 ~ paste0("Apr-Jun ",
+                                lubridate::year(date)),
+      quarter_num == 2 ~ paste0("Jul-Sep ",
+                                lubridate::year(date)),
+      quarter_num == 3 ~ paste0("Oct-Dec ",
+                                lubridate::year(date)),
+      quarter_num == 4 ~ paste0("Jan-Mar ",
+                                lubridate::year(date) + 1)))
+  }
+}
+
+#' @export
+#' @rdname qtr
 qtr_prev <- function(date, format = c("long", "short")) {
 
   format <- match.arg(format)

README.Rmd

@@ -0,0 +1,143 @@
+---
+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-"
+)
+```
+
+# phimethods
+
+[![Build Status](https://travis-ci.com/Health-SocialCare-Scotland/phimethods.svg?branch=master)](https://travis-ci.com/Health-SocialCare-Scotland/phimethods)
+[![codecov](https://codecov.io/gh/Health-SocialCare-Scotland/phimethods/branch/master/graph/badge.svg)](https://codecov.io/gh/Health-SocialCare-Scotland/phimethods)
+
+`phimethods` contains functions for commonly undertaken tasks by [PHI](https://nhsnss.org/how-nss-works/our-structure/public-health-and-intelligence/) analysts:
+
+- `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`
+- `postcode()` formats improperly recorded postcodes
+- `qtr()`, `qtr_end()`, `qtr_next()` and `qtr_prev()` assign a date to a quarter
+
+`phimethods` can be used on both the [server](http://spsssrv02.csa.scot.nhs.uk:8787/) and desktop versions of RStudio.
+
+## Installation
+
+To install `phimethods`, the package `remotes` is required, and can be installed with `install.packages("remotes")`.
+
+You can then install `phimethods` on RStudio server from GitHub with:
+
+```{r gh-installation, eval = FALSE}
+remotes::install_github("Health-SocialCare-Scotland/phimethods")
+```
+
+Network security settings may prevent `remotes::install_github()` from working on RStudio desktop. If this is the case, `phimethods` can be installed by downloading the [zip of the repository](https://github.com/Health-SocialCare-Scotland/phimethods/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>/phimethods-master.zip",
+                       upgrade = "never")
+```
+
+## Using phimethods
+
+Load `phimethods` using `library()`:
+
+```{r load}
+library(phimethods)
+```
+
+To access the help file for any of `phimethods`' functions, type `?function_name` into the RStudio console after loading the package:
+
+```{r help, eval = FALSE}
+?fin_year
+?postcode
+```
+
+### 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}
+a <- lubridate::dmy(c(21012017, 04042017, 17112017))
+fin_year(a)
+```
+
+### postcode
+
+```{r postcode, message = FALSE, 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
+# Postcodes containing invalid characters will return an NA
+library(dplyr)
+b <- tibble(pc = c("G 4 2 9 B A", "g207al", "DD37J    y", "DG?8BS"))
+b %>% mutate(pc = postcode(pc))
+```
+
+### qtr, qtr_end, qtr_next and qtr_prev
+```{r qtr}
+c <- lubridate::dmy(c(26032012, 04052012, 23092012))
+
+# qtr returns the current quarter and year
+# The default is long format
+qtr(c)
+
+# But short format can also be applied
+qtr(c, format = "short")
+
+
+# qtr_end returns the last month in the quarter
+qtr_end(c)
+qtr_end(c, format = "short")
+
+
+# qtr_next returns the next quarter
+qtr_next(c)
+qtr_next(c, format = "short")
+
+
+# qtr_prev returns the previous quarter
+qtr_prev(c)
+qtr_prev(c, format = "short")
+```
+
+## Contributing to phimethods
+
+At present, the maintainers of this package are [Jack Hannah](https://github.com/jackhannah95), [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 PHI. If you would like to contribute a function, or propose an improvement to an existing function, please first create an [issue](https://github.com/Health-SocialCare-Scotland/phimethods/issues) on GitHub and assign **all** 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.
+
+When contributing, please create a [branch](https://github.com/Health-SocialCare-Scotland/phimethods/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/Health-SocialCare-Scotland/phimethods/pulls) and assign **all** of the package maintainers as reviewers. One or more 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 publically 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 PHI. 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://nhs-nss-transforming-publications.github.io/git-guide/) and [GitHub guidance](https://github.com/NHS-NSS-transforming-publications/GitHub-guidance).
+
+`phimethods` 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 `phimethods`; 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](https://r-pkgs.org/) book prior to making a contribution. It may also be useful to consult the [documentation](https://github.com/Health-SocialCare-Scotland/phimethods/tree/master/R) and [tests](https://github.com/Health-SocialCare-Scotland/phimethods/tree/master/tests/testthat) of existing functions within this package as a point of reference.
+
+Please note that this README may fail to Knit on RStudio desktop as a result of network security settings. This is due to the badges for continuous integration and test coverage at the top of the document. If you are editing the README file, please Knit the `README.Rmd` document via RStudio server, or contact the package maintainers for assistance.