Re-factor ipc check function

NAMESPACE

@@ -1,12 +1,12 @@
 # Generated by roxygen2: do not edit by hand
 
-export(check_sample_size)
 export(compute_combined_prevalence)
 export(compute_muac_prevalence)
 export(compute_wfhz_prevalence)
 export(define_wasting)
 export(flag_outliers)
 export(get_age_months)
+export(mw_check_ipcamn_ssreq)
 export(mw_neat_output_mfaz)
 export(mw_neat_output_muac)
 export(mw_neat_output_wfhz)

R/ipc_amn_check.R

@@ -0,0 +1,72 @@
+#'
+#' Check whether IPC Acute Malnutrition (IPC AMN) sample size requirements were met
+#'
+#' @description
+#' Evidence on the prevalence of acute malnutrition used in the IPC AMN
+#' can come from different sources: surveys, screenings or community-based
+#' surveillance system. The IPC set minimum sample size requirements
+#' for each source. This function helps in verifying whether the requirements
+#' were met or not depending on the source.
+#'
+#' @param df A dataset object of class `data.frame` to check.
+#'
+#' @param cluster A vector of class `integer` or `character` of unique cluster or
+#' screening or sentinel site IDs. If a `character` vector, ensure that names are
+#' correct and each name represents one location for accurate counts. If the class
+#' does not match the above expected type, the function will stop execution and
+#' return an error message indicating the type of mismatch.
+#'
+#' @param .source The source of evidence. A choice between "survey" for
+#' representative survey data at the area of analysis; "screening" for
+#' screening data; "ssite" for community-based sentinel site data.
+#'
+#' @returns A summary table of class `data.frame`, of length 3 and width 1, for
+#' the check results. `n_clusters` is for the total number of unique clusters or
+#' screening or site IDs; `n_obs` for the correspondent total number of children
+#' in the dataset; and `meet_ipc` for whether the IPC AMN requirements were met.
+#'
+#' @references
+#' IPC Global Partners. 2021. *Integrated Food Security Phase Classification*
+#' *Technical Manual Version 3.1.Evidence and Standards for Better Food Security*
+#' *and Nutrition Decisions*. Rome. Available at:
+#' <https://www.ipcinfo.org/ipcinfo-website/resources/ipc-manual/en/>.
+#'
+#' @examples
+#' mw_check_ipcamn_ssreq(
+#'   df = anthro.01,
+#'   cluster = cluster,
+#'   .source = "survey"
+#' )
+#'
+#' @export
+#'
+mw_check_ipcamn_ssreq <- function(df,
+                                  cluster,
+                                  .source = c("survey", "screening", "ssite")) {
+  ## Difuse and evaluate arguments ----
+  cluster <- eval_tidy(enquo(cluster), df)
+
+  ## Enforce the options in `.source` ----
+  .source <- match.arg(.source)
+
+  ## Enforce the class of `cluster` ----
+  if (!(class(cluster) %in% c("integer", "character"))) {
+    stop(
+      "`cluster` must be of class `integer` or `character`; not ", shQuote(class(cluster)), ". Please try again."
+    )
+  }
+
+  ## Summarize ----
+  df <- df |>
+    summarise(
+      n_clusters = n_distinct({{ cluster }}),
+      n_obs = n(),
+      meet_ipc = case_when(
+        .source == "survey" & n_clusters >= 25 ~ "yes",
+        .source == "screening" & n_clusters >= 3 & n_obs >= 600 ~ "yes",
+        .source == "ssite" & n_clusters >= 5 & n_obs >= 200 ~ "yes",
+        .default = "no"
+      )
+    )
+  as_tibble(df)
+}

pkgdown/_pkgdown.yml

@@ -68,7 +68,7 @@ home:
 
 #   - title: Check IPC AMN sample size requirements
 #     contents:
-#     - mw_check_ipc_ssreq
+#     - mw_check_ipcamn_ssreq
 
 #   - title: Check plausibility
 #     contents:

tests/testthat/test-ipc_amn_check.R

@@ -0,0 +1,27 @@
+# Test check: mw_check_ipcamn_ssreq() ----
+testthat::test_that(
+  "mw_check_ipcamn_ssreq() works as expected",
+  {
+    ## Observed results ----
+    x <- mw_check_ipcamn_ssreq(
+      df = anthro.01,
+      cluster = cluster,
+      .source = "survey"
+    )
+
+    ## Tests ----
+    testthat::expect_s3_class(object = x, class = "tbl_df", exact = FALSE)
+    testthat::expect_true(all(c("n_clusters", "n_obs", "meet_ipc") %in% names(x)))
+    testthat::expect_error(
+      mw_check_ipcamn_ssreq(
+        df = anthro.01,
+        cluster = weight,
+        .source = "survey"
+      ),
+      regexp = paste0(
+        "`cluster` must be of class `integer` or `character`; not ",
+        shQuote(class(anthro.01$weight)), ". Please try again."
+      )
+    )
+  }
+)

vignettes/sample_size.qmd → vignettes/ipc_amn_check.qmd

@@ -12,9 +12,9 @@ vignette: >
 
 library(mwana)
 ```
-Evidence on the prevalence of acute malnutrition used in the IPC Acute Malnutrition (IPC AMN) can come from different sources with data collected in different ways:  representative surveys, screenings or community-based surveillance system (known as sentinel sites). The IPC set minimum sample size requirements for each of these sources. Details can be read from the [IPC Manual version 3.1 ](https://www.ipcinfo.org/ipcinfo-website/resources/ipc-manual/en/). 
+Evidence on the prevalence of acute malnutrition used in the IPC Acute Malnutrition (IPC AMN) can come from different sources, namely: representative surveys, screenings or community-based surveillance system (known as sentinel sites). The IPC set minimum sample size requirements for each of these sources. Details can be read from the [IPC Manual version 3.1 ](https://www.ipcinfo.org/ipcinfo-website/resources/ipc-manual/en/).  
 
-In the IPC AMN analysis workflow, the very first step of a data analyst is to check if these requirements were met. This is done for each area meant to be included in the *de facto* IPC AMN analysis. For this, `mwana` provides a handy function: `check_sample_size()`.
+In the IPC AMN analysis workflow, the very first step of a data analyst is to check if these requirements were met. This is done for each area meant to be included in the IPC AMN analysis. For this, `mwana` provides a handy function: `mw_check_ipcamn_ssreq()`.
 
 To demonstrate its usage, we will use a built-in sample dataset `anthro.01`.
 
@@ -35,17 +35,17 @@ head(anthro.01)
 
 `anthro.01` contains anthropometry data from SMART surveys from anonymized locations. We can check further details about the dataset by calling `help(anthro.01)` in `R` console. 
 
-Now that we are acquainted with the dataset, we can now proceed to execute the task. To achieve this we simply do:
+Now that we are acquainted with the dataset, we can proceed to execute the task. To achieve this, we simply do:
 
 ```{r}
 #| label: check
 #| echo: true
 #| eval: false
 
-check_sample_size(
+mw_check_ipcamn_ssreq(
   df = anthro.01,
-  .group = cluster,
-  .data_type = "survey"
+  cluster = cluster,
+  .source = "survey"
 )
 ```
 
@@ -56,9 +56,9 @@ Or we can also choose to chain the data object to the function using the pipe op
 #| eval: false
 
 anthro.01 |>
-  check_sample_size(
-    .group = cluster,
-    .data_type = "survey"
+  mw_check_ipcamn_ssreq(
+    cluster = cluster,
+    .source = "survey"
   )
 ```
 
@@ -68,19 +68,19 @@ Either way, the returned output will be:
 #| echo: false
 
 anthro.01 |>
-  check_sample_size(
-    .group = cluster,
-    .data_type = "survey"
+  mw_check_ipcamn_ssreq(
+    cluster = cluster,
+    .source = "survey"
   )
 ```
 
 A table (of class `tibble`) is returned with three columns:  
 
-  + Column `groups` counts the number of unique cluster ID's in the dataset.  
-  + Column `n_obs` counts the number of children the dataset.  
+  + Column `n_clusters` counts the number of unique cluster IDs in the dataset.  
+  + Column `n_obs` counts the number of children in the dataset.  
   + Column `meet_ipc` indicates whether the IPC AMN sample size requirements (for surveys in this case) were met or not.
 
-The above output is not quite useful yet, as we often deal with multi-area dataset. We can get a summarised table by area as follows: 
+The above output is not quite useful yet as we often deal with multiple area dataset. We can get a summarised table by area as follows: 
 ```{r}
 #| label: group_by
 #| echo: true
@@ -92,9 +92,9 @@ library(dplyr)
 ## Use the group_by() function ----
 anthro.01 |>
   group_by(area) |>
-  check_sample_size(
-    .group = cluster,
-    .data_type = "survey"
+  mw_check_ipcamn_ssreq(
+    cluster = cluster,
+    .source = "survey"
   )
 ```
 
@@ -109,10 +109,10 @@ library(dplyr)
 
 anthro.01 |>
   group_by(area) |>
-  check_sample_size(
-    .group = cluster,
-    .data_type = "survey"
+  mw_check_ipcamn_ssreq(
+    cluster = cluster,
+    .source = "survey"
   )
 ```
 
-For screening or sentinel site-based data, we approach the task the same way; we only have to change the `.data_type` parameter to "screening" or to "ssite" as appropriate, as well as to supply `.group` with the right column name of the sub-areas inside the main area (villages, localities, comunas, communities, etc).
+For screening or sentinel site-based data, we approach the task the same way; we only have to change the `.source` parameter to "screening" or to "ssite" as appropriate, as well as to supply `cluster` with the right column name of the sub-areas inside the main area (villages, localities, comunas, communities, etc).