Deprecate the file_size() function

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: phsmethods
 Title: Standard Methods for Use in Public Health Scotland
-Version: 1.0.2
+Version: 1.0.2.9000
 Authors@R: c(
     person("Public Health Scotland", , , "[email protected]", role = "cph"),
     person("David", "Caldwell", , "[email protected]", role = "aut"),
@@ -40,7 +40,8 @@ Imports:
     scales (>= 1.0.0),
     stringr,
     tibble,
-    utils
+    utils,
+    withr
 Suggests: 
     covr,
     ggplot2,
@@ -49,6 +50,8 @@ Suggests:
     rmarkdown,
     spelling,
     testthat (>= 3.0.0)
+VignetteBuilder: 
+    knitr
 RdMacros: 
     lifecycle
 Config/testthat/edition: 3
@@ -57,4 +60,3 @@ Language: en-GB
 LazyData: true
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
-VignetteBuilder: knitr

NEWS.md

@@ -1,3 +1,9 @@
+# phsmethods (development version)
+
+- `file_size()` has been deprecated as we believe it is no longer relevant (#11).
+Please let us know if you still have a use for it, otherwise it will be removed 
+in a future version.
+
 # phsmethods 1.0.2 (2024-01-05)
 
 - No user-facing changes. Fix some tests for `age_from_chi()` due to a helper 

R/file_size.R

@@ -1,9 +1,14 @@
 #' @title Calculate file size
 #'
-#' @description `file_size` takes a filepath and an optional regular
+#' @description
+#' `r lifecycle::badge('deprecated')`
+#'
+#' `file_size` takes a filepath and an optional regular
 #' expression pattern. It returns the size of all files within that directory
 #' which match the given pattern.
 #'
+#' @keywords internal
+#'
 #' @details The sizes of files with certain extensions are returned with the
 #' type of file prefixed. For example, the size of a 12 KB `.xlsx` file is
 #' returned as `Excel 12 KB`. The complete list of explicitly catered-for file
@@ -65,7 +70,7 @@
 #' library(magrittr)
 #' file_size() %>%
 #'   dplyr::pull(size) %>%
-#'   extract(1)
+#'   magrittr::extract(1)
 #'
 #' @seealso For more information on using regular expressions, see this
 #' [Jumping Rivers blog post](https://www.jumpingrivers.com/blog/regular-expressions-every-r-programmer-should-know/)
@@ -75,6 +80,14 @@
 #'
 #' @export
 file_size <- function(filepath = getwd(), pattern = NULL) {
+  lifecycle::deprecate_warn(
+    "1.1.0",
+    "file_size()",
+    details = "We think it is redundant, but if you still have a need for this
+    function, please get in touch.",
+    always = TRUE
+  )
+
   if (!file.exists(filepath)) {
     cli::cli_abort("A valid {.arg filepath} must be supplied.")
   }

README.Rmd

@@ -13,50 +13,62 @@ knitr::opts_chunk$set(
 ```
 
 # phsmethods
+
 <!-- badges: start -->
-[![CRAN status](https://www.r-pkg.org/badges/version/phsmethods)](https://CRAN.R-project.org/package=phsmethods)
-[![GitHub release (latest by date)](https://img.shields.io/github/v/release/Public-Health-Scotland/phsmethods)](https://github.com/Public-Health-Scotland/phsmethods/releases/latest)
-[![Build Status](https://github.com/Public-Health-Scotland/phsmethods/workflows/R-CMD-check/badge.svg)](https://github.com/Public-Health-Scotland/phsmethods/actions)
-[![codecov](https://codecov.io/gh/Public-Health-Scotland/phsmethods/branch/master/graph/badge.svg)](https://app.codecov.io/gh/Public-Health-Scotland/phsmethods)
-<!-- badges: end -->
 
-`phsmethods` contains functions for commonly undertaken analytical tasks in [Public Health Scotland (PHS)](https://www.publichealthscotland.scot/):
+[![CRAN
+status](https://www.r-pkg.org/badges/version/phsmethods)](https://CRAN.R-project.org/package=phsmethods)
+[![GitHub release (latest by
+date)](https://img.shields.io/github/v/release/Public-Health-Scotland/phsmethods)](https://github.com/Public-Health-Scotland/phsmethods/releases/latest)
+[![Build
+Status](https://github.com/Public-Health-Scotland/phsmethods/workflows/R-CMD-check/badge.svg)](https://github.com/Public-Health-Scotland/phsmethods/actions)
+[![codecov](https://codecov.io/gh/Public-Health-Scotland/phsmethods/branch/master/graph/badge.svg)](https://app.codecov.io/gh/Public-Health-Scotland/phsmethods)
 
-- `create_age_groups()` 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
-- `extract_fin_year()` assigns a date to a financial year in the format `YYYY/YY`
-- `match_area()` converts geography codes into area names
-- `format_postcode()` formats improperly recorded postcodes
-- `qtr()`, `qtr_end()`, `qtr_next()` and `qtr_prev()` assign a date to a quarter
-- `age_calculate()` calculates age between two dates
-- `dob_from_chi()` extracts Date of Birth (DoB) from the CHI number
-- `age_from_chi()` extracts age from the CHI number
+<!-- badges: end -->
 
-`phsmethods` can be used on both the PHS server and desktop versions of RStudio.
+`phsmethods` contains functions for commonly undertaken analytical tasks
+in [Public Health Scotland
+(PHS)](https://www.publichealthscotland.scot/):
+
+-   `create_age_groups()` 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.
+-   `extract_fin_year()` assigns a date to a financial year in the
+    format `YYYY/YY`.
+-   `match_area()` converts geography codes into area names.
+-   `format_postcode()` formats improperly recorded postcodes.
+-   `qtr()`, `qtr_end()`, `qtr_next()` and `qtr_prev()` assign a date to
+    a quarter.
+-   `age_calculate()` calculates age between two dates.
+-   `dob_from_chi()` extracts Date of Birth (DoB) from the CHI number.
+-   `age_from_chi()` extracts age from the CHI number.
+
+`phsmethods` can be used on both the PHS server and desktop versions of
+RStudio.
 
 ## Installation
 
-If you are using the PHS Posit Workbench the default repository is the PHS Posit Package Manager, the benefit of this is that `phsmethods` is listed there so you can install it with:
+If you are using the PHS Posit Workbench the default repository is the
+PHS Posit Package Manager, the benefit of this is that `phsmethods` is
+listed there so you can install it with:
 
 ``` r
 install.packages("phsmethods")
 ```
 
-To install `phsmethods` directly from GitHub, the package `remotes` is required, and can be
-installed with `install.packages("remotes")`.
+To install `phsmethods` directly from GitHub, the package `remotes` is
+required, and can be installed with `install.packages("remotes")`.
 
 You can then install `phsmethods` from GitHub with:
 
 ``` r
 remotes::install_github("Public-Health-Scotland/phsmethods")
 ```
 
-However, 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
+However, 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):
@@ -75,42 +87,108 @@ Load `phsmethods` using `library()`:
 library(phsmethods)
 ```
 
-To see the documentation for any `phsmethods`' functions, type `?function_name` into the RStudio console after loading the package:
+To see the documentation for any `phsmethods`' functions, type
+`?function_name` into the RStudio console after loading the package:
 
 ```{r help, eval = FALSE}
 ?extract_fin_year
 ?format_postcode
 ```
 
-You can access the full list of functions and their help pages on [Reference page of pkgdown website](https://public-health-scotland.github.io/phsmethods/reference/index.html). You will be able to see some examples of each function.
+You can access the full list of functions and their help pages on
+[Reference page of pkgdown
+website](https://public-health-scotland.github.io/phsmethods/reference/index.html).
+You will be able to see some examples of each function.
 
-There is also a very useful [PHS Methods online training course](https://scotland.shinyapps.io/phs-learnr-phsmethods) which gives you an interactive way to learn about this package.
+There is also a very useful [PHS Methods on-line training
+course](https://scotland.shinyapps.io/phs-learnr-phsmethods) which gives
+you an interactive way to learn about this package.
 
 ## Contributing to phsmethods
 
-At present, the maintainer of this package is [Tina Fu](https://github.com/Tina815).
-
-This package is intended to be in continuous development and contributions may be made by anyone within PHS. If you would like to contribute, 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 eye-catching (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 [blog post 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 before 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. You should only make edits to the `.Rmd` version, you can then knit yourself, or a GitHub action should run and knit it for you when you open a pull request.
-
+At present, the maintainer of this package is [Tina
+Fu](https://github.com/Tina815).
+
+This package is intended to be in continuous development and
+contributions may be made by anyone within PHS. If you would like to
+contribute, 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 eye-catching (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 [blog post 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 before 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. You should only make edits to the
+`.Rmd` version, you can then knit yourself, or a GitHub action should
+run and knit it for you when you open a pull request.

README.md

@@ -12,26 +12,26 @@ date)](https://img.shields.io/github/v/release/Public-Health-Scotland/phsmethods
 [![Build
 Status](https://github.com/Public-Health-Scotland/phsmethods/workflows/R-CMD-check/badge.svg)](https://github.com/Public-Health-Scotland/phsmethods/actions)
 [![codecov](https://codecov.io/gh/Public-Health-Scotland/phsmethods/branch/master/graph/badge.svg)](https://app.codecov.io/gh/Public-Health-Scotland/phsmethods)
+
 <!-- badges: end -->
 
 `phsmethods` contains functions for commonly undertaken analytical tasks
 in [Public Health Scotland
 (PHS)](https://www.publichealthscotland.scot/):
 
-- `create_age_groups()` 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
+- `create_age_groups()` 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.
 - `extract_fin_year()` assigns a date to a financial year in the format
-  `YYYY/YY`
-- `match_area()` converts geography codes into area names
-- `format_postcode()` formats improperly recorded postcodes
+  `YYYY/YY`.
+- `match_area()` converts geography codes into area names.
+- `format_postcode()` formats improperly recorded postcodes.
 - `qtr()`, `qtr_end()`, `qtr_next()` and `qtr_prev()` assign a date to a
-  quarter
-- `age_calculate()` calculates age between two dates
-- `dob_from_chi()` extracts Date of Birth (DoB) from the CHI number
-- `age_from_chi()` extracts age from the CHI number
+  quarter.
+- `age_calculate()` calculates age between two dates.
+- `dob_from_chi()` extracts Date of Birth (DoB) from the CHI number.
+- `age_from_chi()` extracts age from the CHI number.
 
 `phsmethods` can be used on both the PHS server and desktop versions of
 RStudio.
@@ -89,7 +89,7 @@ You can access the full list of functions and their help pages on
 website](https://public-health-scotland.github.io/phsmethods/reference/index.html).
 You will be able to see some examples of each function.
 
-There is also a very useful [PHS Methods online training
+There is also a very useful [PHS Methods on-line training
 course](https://scotland.shinyapps.io/phs-learnr-phsmethods) which gives
 you an interactive way to learn about this package.