Merge pull request #112 from nutriverse:dev

organise function sets; fix #110; fix #111

.github/workflows/R-CMD-check.yaml

@@ -4,9 +4,10 @@ on:
   push:
     branches: [main, master]
   pull_request:
-    branches: [main, master]
 
-name: R-CMD-check
+name: R-CMD-check.yaml
+
+permissions: read-all
 
 jobs:
   R-CMD-check:

.github/workflows/test-coverage.yaml

@@ -4,16 +4,16 @@ on:
   push:
     branches: [main, master]
   pull_request:
-    branches: [main, master]
 
-name: test-coverage
+name: test-coverage.yaml
+
+permissions: read-all
 
 jobs:
   test-coverage:
     runs-on: ubuntu-latest
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
     steps:
       - uses: actions/checkout@v4
@@ -24,18 +24,28 @@ jobs:
 
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: any::covr
+          extra-packages: any::covr, any::xml2
           needs: coverage
 
       - name: Test coverage
         run: |
-          covr::codecov(
+          cov <- covr::package_coverage(
             quiet = FALSE,
             clean = FALSE,
             install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package")
           )
+          covr::to_cobertura(cov)
         shell: Rscript {0}
 
+      - uses: codecov/codecov-action@v4
+        with:
+          # Fail if error if not on PR, or if on PR and token is given
+          fail_ci_if_error: ${{ github.event_name != 'pull_request' || secrets.CODECOV_TOKEN }}
+          file: ./cobertura.xml
+          plugin: noop
+          disable_search: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+
       - name: Show testthat output
         if: always()
         run: |

NAMESPACE

@@ -5,7 +5,7 @@ export(calculate_cured)
 export(calculate_dead)
 export(calculate_default)
 export(calculate_los)
-export(calculate_median_los)
+export(calculate_los_median)
 export(calculate_median_muac)
 export(calculate_no_response)
 export(calculate_performance)

NEWS.md

@@ -2,18 +2,24 @@
 
 This is a GitHub-only development version of the `{squeacr}` package.
 
+## New features
+
+* added `calculate_median_muac()` function for calculating median MUAC-at-admission
+
 ## General updates
 
 * added vignettes;
 
 * updated README;
 
-* re-factored `calculate_performance()` functions;
-
+* updated documentation of coverage estimators;
 
+* updated documentation of performance calculators;
 
 ## Bug fixes
 
+* re-factored `calculate_performance()` functions;
+
 <br/>
 
 # squeacr 0.0.0.9000

R/estimate_coverage.R

@@ -1,14 +1,13 @@
-################################################################################
-#
-#' Estimate cases not in CMAM programme
+#' 
+#' CMAM coverage estimators
 #'
 #' @param cin Cases in CMAM programme
 #' @param cout Cases not in CMAM programme
 #' @param rin Recovering cases in programme
 #' @param k Correction factor. Ratio of the mean length of an untreated episode
 #'   to the mean length of a CMAM treatment episode
 #'
-#' @return Value of number of cases not in CMAM programme
+#' @return Numeric value of required coverage estiamtor
 #'
 #' @author Ernest Guevarra based on technical notes and equations by Mark Myatt
 #'
@@ -20,75 +19,32 @@
 #'
 #' @examples
 #' calculate_rout(cin = 5, cout = 25, rin = 5, k = 3)
+#' calculate_cf(cin = 5, cout = 20)
+#' calculate_tc(cin = 5, cout = 20, rin = 5, k = 3)
 #'
 #' @export
+#' @rdname calculate_coverage
 #'
-#
-################################################################################
 
 calculate_rout <- function(cin, cout, rin, k = 3) {
   floor((1 / k) * (rin * ((cin + 1 + cout) / (cin + 1)) - rin))
 }
 
 
-################################################################################
-#
-#' Estimate case finding effectiveness
-#'
-#' @param cin Cases in CMAM programme
-#' @param cout Cases not in CMAM programme
-#'
-#' @return Value of case finding effectiveness
-#'
-#' @author Ernest Guevarra based on technical notes and equations by Mark Myatt
-#'
-#' @references Safari Balegamire, Katja Siling, Jose Luis Alvarez Moran,
-#'   Ernest Guevarra, Sophie Woodhead, Alison Norris, Lionella Fieschi,
-#'   Paul Binns, and Mark Myatt (2015). A single coverage estimator for use in
-#'   SQUEAC, SLEAC, and other CMAM coverage assessments. Field Exchange 49,
-#'   March 2015. p81. <www.ennonline.net/fex/49/singlecoverage>
-#'
-#' @examples
-#' calculate_cf(cin = 5, cout = 20)
 #'
 #' @export
+#' @rdname calculate_coverage
 #'
-#
-################################################################################
 
 calculate_cf <- function(cin, cout) {
   cin / (cin + cout)
 }
 
 
-################################################################################
-#
-#' Estimate treatment coverage
-#'
-#' @param cin Cases in CMAM programme
-#' @param cout Cases not in CMAM programme
-#' @param rin Recovering cases in CMAM programme
-#' @param k Correction factor. Ratio of the mean length of an untreated episode
-#'   to the mean length of a CMAM treatment episode
-#'
-#' @return Value of treatment coverage
-#'
-#' @author Ernest Guevarra based on technical notes and equations by Mark Myatt
-#'
-#' @references Safari Balegamire, Katja Siling, Jose Luis Alvarez Moran,
-#'   Ernest Guevarra, Sophie Woodhead, Alison Norris, Lionella Fieschi,
-#'   Paul Binns, and Mark Myatt (2015). A single coverage estimator for use in
-#'   SQUEAC, SLEAC, and other CMAM coverage assessments. Field Exchange 49,
-#'   March 2015. p81. <www.ennonline.net/fex/49/singlecoverage>
-#'
-#' @examples
-#' calculate_tc(cin = 5, cout = 20, rin = 5, k = 3)
 #'
 #' @export
+#' @rdname calculate_coverage
 #'
-#'
-#
-################################################################################
 
 calculate_tc <- function(cin, cout, rin, k = 3) {
   rout <- calculate_rout(cin = cin, cout = cout, rin = rin, k = k)

R/length_of_stay.R

@@ -1,13 +1,21 @@
 #'
-#' Calculate CMAM length of stay
+#' Calculate CMAM length of stay and median length of stay for a cohort of CMAM 
+#' discharges
 #'
 #' @param admission_date Date of admission in `YYYY-MM-DD` format. If child is a
 #'   kwashiorkor case, date of lowest weight (when oedema has subsided). Can be
 #'   a single date value or a vector of date values.
 #' @param discharge_date Date of discharge in `YYYY-MM-DD` format. Can be a
 #'   single date value or a vector of date values.
+#' @param group A character value/s with the same length as `admission_date` and
+#'   `discharge_data` to use as grouping variable within which median
+#'   length-of-stay is to be calculated. Default is NULL for no grouping.
 #'
-#' @return Numeric value or vector of numeric values for length-of-stay in days.
+#' @return Numeric value or vector of numeric values for length-of-stay in days
+#'   for [calculate_los()]. A numeric value for median length-of-stay in
+#'   days for [calculate_los_median()]. If `group` is not NULL, a vector of 
+#'   numeric values for median length-of-stay in days with length equal to the 
+#'   number of groups.
 #'
 #' @author Ernest Guevarra
 #'
@@ -17,8 +25,15 @@
 #'
 #' calculate_los(admission_date = c("2010-03-15", "2010-03-16"),
 #'               discharge_date = c("2010-06-14", "2010-06-20"))
+#' 
+#' calculate_los_median(
+#'   otp_beneficiaries$admDate,
+#'   otp_beneficiaries$disDate,
+#'   group = otp_beneficiaries$locality
+#' )
 #'
 #' @export
+#' @rdname calculate_los
 #'
 
 calculate_los <- function(admission_date, discharge_date) {
@@ -62,35 +77,12 @@ calculate_los <- function(admission_date, discharge_date) {
 }
 
 
-#'
-#' Calculate median length of stay for a cohort of CMAM discharges
-#'
-#' @param admission_date Date of admission in `YYYY-MM-DD` format. If child is a
-#'   kwashiorkor case, date of lowest weight (when oedema has subsided). Can be
-#'   a single date value or a vector of date values.
-#' @param discharge_date Date of discharge in `YYYY-MM-DD` format. Can be a
-#'   single date value or a vector of date values.
-#' @param group A character value/s with the same length as `admission_date` and
-#'   `discharge_data` to use as grouping variable within which median
-#'   length-of-stay is to be calculated. Default is NULL for no grouping.
-#'
-#' @return A numeric value for median length-of-stay in days. If `group` is not
-#'   NULL, a vector of numeric values for median length-of-stay in days with
-#'   length equal to the number of groups.
-#'
-#' @author Ernest Guevarra
-#'
-#' @examples
-#' calculate_median_los(
-#'   otp_beneficiaries$admDate,
-#'   otp_beneficiaries$disDate,
-#'   group = otp_beneficiaries$locality
-#' )
 #'
 #' @export
+#' @rdname calculate_los
 #'
 
-calculate_median_los <- function(admission_date,
+calculate_los_median <- function(admission_date,
                                  discharge_date,
                                  group = NULL) {
   ## Calculate median length of stay