---
title: "Estimating the prevalence of wasting"
author: Tomás Zaba
knitr:
  opts_chunk: 
    collapse: true
    comment: "#>"
vignette: >
  %\VignetteIndexEntry{Estimating the prevalence of wasting}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---

```{r}
#| label: load_library
#| echo: false
#| message: false

library(mwana)
library(dplyr)
```

## Introduction 
This vignette demonstrates the use of `mwana` package's functions to estimate the prevalence of wasting based on:  

  + Weight-for-height z-score (WFHZ) and/or oedema
  + Raw MUAC values and/or oedema
  + MUAC-for-age z-score (MFAZ) and/or oedema, and
  + Combined prevalence. 

The prevalence functions in `mwana` were carefully conceived and designed to simplify the workflow of a nutrition data analyst, especially when dealing with datasets containing imperfections that require additional layers of analysis. Let's try to clarify this with two scenarios that you may have faced: 

  + When analysing a multi-area dataset, users will likely need to estimate the prevalence for each area individually. Afterwards, they must extract the results and collate in a summary table for sharing.
  
  + When working with MUAC data, when age ratio test is rated as problematic, an additional tool is required to weight the prevalence and correct for age bias, thereby the associated likely prevalence over-estimation. In an unfortunate cases wherein multiple areas face this issue, the workflow must be repeated several times, making the process boredom and highly error-prone.

With `mwana`, you no longer have to worry about this. The functions are designed to deal with that. To demonstrate their use, we will use different datasets to represent different scenarios:

  + `anthro.02` : a survey data with survey weights. Learn more about this data with `?anthro.02`.
  + `anthro.03` : district-level SMART surveys with two districts whose WFHZ standard deviations are rated as problematic while the rest lay within range.  Do `?anthro.03` for more details.
  + `anthro.04` : a community-based sentinel site data. The data has different characteristics that require different analysis approaches.

## Estimation of the prevalence of wasting based on WFHZ {#sec-prevalence-wfhz}

To estimate the prevalence of wasting based on WFHZ we use the `mw_estimate_prevalence_wfhz()` function. The dataset to supply must have been wrangled by `mw_wrangle_wfhz()`. 

As usual, we start off by inspecting our dataset:

```{r}
#| label: inspect_anthro.02
#| echo: true
#| eval: false

tail(anthro.02)
```

```{r}
#| label: view_anthro.02
#| echo: false

tail(anthro.02)
```

We can see that the dataset contains the required variables for a WFHZ prevalence analysis, including for a weighted analysis. This dataset has already been wrangled, therefore there is no need to call the WFHZ wrangler.

### Estimation of unweighted prevalence 

To achieve this we do: 
```{r}
#| label: unwt_wast_wfhz
#| echo: true
#| eval: false

anthro.02 |>
  mw_estimate_prevalence_wfhz(
    wt = NULL,
    oedema = oedema
  )
```

This will return: 
```{r}
#| label: view_unwt_wast_wfhz
#| echo: false

mw_estimate_prevalence_wfhz(
  df = anthro.02,
  wt = NULL,
  oedema = oedema
)
```

If for some reason the variable oedema is not available in the dataset, or it's there but not plausible, we can exclude it from the analysis by setting the argument `oedema` to `NULL`:

```{r}
#| label: unwt_wast_wfhz_noedema
#| echo: true
#| eval: false

anthro.02 |>
  mw_estimate_prevalence_wfhz(
    wt = NULL,
    oedema = NULL # Setting oedema to NULL
  )
```

And we get: 

```{r}
#| label: view_unwt_wast_wfhz_noedema
#| echo: false

mw_estimate_prevalence_wfhz(
  df = anthro.02,
  wt = NULL,
  oedema = NULL
)
```

If we inspect the `gam_n` and `gam_p` columns of this output table and the previous, we notice differences in the numbers. This occurs because oedema cases were excluded in the second implementation. It is noteworthy that you will observe a change if there are positive cases of oedema in the dataset; otherwise, setting `oedema = NULL` will have no effect whatsoever. 

The above output summary does not show results by province. We can control this by supplying the variable or set of variables containing the locations where the data was collected, or any other category (such as teams, sex, etc.) after oedema. In our case, we will use the column `province`: 

```{r}
#| label: unwt_wast_wfhz_province
#| echo: true
#| eval: false

anthro.02 |>
  mw_estimate_prevalence_wfhz(
    wt = NULL,
    oedema = oedema,
    province # province is the variable name holding data on where the survey was conducted.
  )
```

And _voila_ : 

```{r}
#| label: view_unwt_wast_wfhz_province
#| echo: false

anthro.02 |>
  mw_estimate_prevalence_wfhz(
    wt = NULL,
    oedema = oedema,
    province
  )
```

A table with two rows is returned with each province's statistics.

### Estimation of weighted prevalence 

To get the weighted prevalence, we use the `wt` argument. We pass to it the column name containing the final survey weights. In our case, the column name is `wtfactor`:

```{r}
#| label: wt_wasting_wfhz
#| echo: true
#| eval: false

anthro.02 |>
  mw_estimate_prevalence_wfhz(
    wt = wtfactor, # Passing the wtfactor to wt
    oedema = oedema,
    province
  )
```

And you get: 

```{r}
#| label: view_wt_wasting_wfhz
#| echo: false

anthro.02 |>
  mw_estimate_prevalence_wfhz(
    wt = wtfactor,
    oedema = oedema,
    province
  )
```

:::{.callout-note}

#### The work under the hood of `mw_estimate_prevalence_wfhz`

Under the hood, before it begins with the prevalence estimation, the function first checks the quality of the WFHZ standard deviation. If it is not problematic, it proceeds with a complex-sample-based analysis; otherwise, prevalence is estimated applying the PROBIT method. This is as you see in the body of the plausibility report generated by ENA. The `anthro.02` dataset has no such issues, so you don't see `mw_estimate_prevalence_wfhz` in action in this regard. To see that, let's use the `anthro.03` dataset.
:::

`anthro.03` contains problematic standard deviation in Metuge and Maravia districts; the rest lay within range. 

Let's inspect our dataset:

```{r}
#| label: anthro.3
#| echo: false

head(anthro.03)
```

Now let's apply the prevalence function. This data needs to be wrangled before passing it to the prevalence function: 

```{r}
#| label: anthro.3_prev
#| echo: true
#| eval: false

anthro.03 |>
  mw_wrangle_wfhz(
    sex = sex,
    .recode_sex = TRUE,
    height = height,
    weight = weight
  ) |>
  mw_estimate_prevalence_wfhz(
    wt = NULL,
    oedema = oedema,
    district
  )
```

The returned output will be: 

```{r}
#| label: view_anthro.3_prev
#| echo: false

anthro.03 |>
  mw_wrangle_wfhz(
    sex = sex,
    .recode_sex = TRUE,
    height = height,
    weight = weight
  ) |>
  mw_estimate_prevalence_wfhz(
    wt = NULL,
    oedema = oedema,
    district
  )
```

In this output, while in Cahora-Bassa and Chiúta districts all columns are populated with numbers, in Metuge and Maravia, only the `gam_p`, `sam_p` and `mam_p` columns are filled with numbers, and everything else with `NA`. These are the districts wherein the PROBIT method was applied.

## Estimation of the prevalence of wasting based on MFAZ 

The prevalence of wasting based on MFAZ can be estimated using the `mw_estimate_prevalence_mfaz()` function. This function is implemented in the same way as demonstrated in [WFHZ](#sec-prevalence-wfhz), with the exception that its data wrangling is based on MUAC, which was also demonstrated in the [plausibility checks](https://mphimo.github.io/mwana/articles/plausibility.html). 

## Estimation of the prevalence of wasting based on raw MUAC values {#sec-prevalence-muac}

This job is assigned to three different functions: `mw_estimate_prevalence_muac()`, `mw_estimate_prevalence_screening()` and `mw_estimate_prevalence_screening2()`. The former is designed for survey data, and the latter two for data derived from screenings. Nonetheless, under the hood, they all implement the following logic:  

 + If the age‑ratio test is not rated as problematic, an unweighted prevalence is estimated. For survey‑derived data, this corresponds to the standard complex‑sample prevalence estimate.
 + If the age‑ratio test is rated as problematic __and__ the observed proportion of children aged 24–59 months is < 66%, an age‑weighted prevalence is estimated. Otherwise, the unweighted prevalence is used (see @fig-age-weighting-logic).

```{mermaid}
%%| label: fig-age-weighting-logic
%%| echo: false
%%| fig-cap: "Workflow for determining whether wasting prevalence should be unweighted or age‑weighted based on age‑ratio test results."

flowchart LR

A[(Input dataset)]
B[Age‑ratio test]
C[Classification]

%% Observed proportion node
D[Observed proportion<br>aged 24–59 months]

%% Single decision block
P{Is proportion > 66%?}

E{Excellent<br>Good<br>Acceptable}
F{Problematic}

I[Estimate unweighted prevalence]
J[Estimate age‑weighted prevalence]

K[(Summarised results)]

A --> B --> C
B --> D

%% Decision from D
D --> P

%% Unweighted prevalence
C --> E --> I --> K
C --> F --> P -->|Yes| I

%% Age-weighted prevalence
P -->|No| J --> K

```

When working with a multiple-area dataset, this logic is applied area wise.

:::{.callout-note}
#### How does it work on a multi-area dataset

Fundamentally, the function performs the standard deviation and age ratio tests, evaluates their acceptability, and returns a summarised table by area. It then iterates over that summary table (row-by-row) checking the above conditionals, and then the function accesses the original dataframe, pulls out the area-specific dataset, then it estimates the prevalence accordingly, and binds the results into a summary results.

:::

### Estimation for survey data  

To demonstrate this we will use the `anthro.04` dataset. 

As usual, let's first inspect it: 
```{r}
#| label: anthro.04
#| echo: false

tail(anthro.04)
```

You see that this data has already been wrangled, so we will go straight to the prevalence estimation. 

:::{.callout-important}

As in ENA Software, make sure you run the plausibility check before you call the prevalence function. This is good to know about the acceptability of your data. If we do that with `anthro.04` we will see which province has issues, hence what we should expect to see in below demonstrations is based on the conditionals stated above.

:::

```{r}
#| label: prev_muac
#| echo: true
#| eval: false

anthro.04 |>
  mw_wrangle_age(age = age) |>
  mw_wrangle_muac(
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age,
    sex = sex,
    .recode_sex = FALSE
  ) |>
  mutate(muac = recode_muac(muac, "mm")) |>
  mw_estimate_prevalence_muac(
    muac = muac,
    age = age,
    wt = NULL,
    oedema = oedema,
    analysis_unit
  )
```

This will return: 

```{r}
#| label: view_prev_muac
#| echo: false

anthro.04 |>
  mw_wrangle_age(age = age) |>
  mw_wrangle_muac(
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age,
    sex = sex,
    .recode_sex = FALSE
  ) |>
  mutate(muac = recode_muac(muac, "mm")) |>
  mw_estimate_prevalence_muac(
    muac = muac,
    age = age,
    wt = NULL,
    oedema = oedema,
    analysis_unit
  )
```

We see that in Unit A, all columns are filled with numbers; in Unit B, some columns are filled with numbers, while other are filled with `NA`s: this is where the age-weighting approach was applied. 

Alternatively, we can choose to apply the function that estimates age-weighted prevalence inside `mw_estimate_prevalence_muac()` directly onto our dataset. This can be done by calling the `mw_estimate_age_weighted_prev_muac()` function. It is noteworthy that although possible, it is recommend to use the main function. This is simply due the fact that if we decide to use the function independently, then we must, before calling it, check the acceptability of the age ratio test, and then evaluate if the conditions that fits the use `mw_estimate_age_weighted_prev_muac()` are there. We would have to do that ourselves. This can be boredom along the workflow, thereby increase the risk of picking a wrong analysis workflow.

```{r}
#| label: smart_wt
#| echo: true
#| eval: false

anthro.04 |>
  mw_wrangle_age(age = age) |>
  mw_wrangle_muac(
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age,
    sex = sex,
    .recode_sex = FALSE
  ) |>
  mutate(muac = recode_muac(muac, "mm")) |>
  mw_estimate_age_weighted_prev_muac(
    muac = muac,
    oedema = oedema,
    has_age = TRUE,
    age = age,
    age_cat = FALSE,
    raw_muac = FALSE,
    analysis_unit
  )
```

This returns the prevalence estimates split into age categories and the overall age-weighted estimate. The latter is given in the last three columns: `sam`, `mam`, and `gam`.
```{r}
#| label: smart_wt_view
#| echo: false

anthro.04 |>
  mw_wrangle_age(age = age) |>
  mw_wrangle_muac(
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age,
    sex = sex,
    .recode_sex = FALSE
  ) |>
  mutate(muac = recode_muac(muac, "mm")) |>
  mw_estimate_age_weighted_prev_muac(
    muac = muac,
    oedema = oedema,
    has_age = TRUE,
    age = age,
    age_cat = FALSE,
    raw_muac = FALSE,
    analysis_unit
  )
```

#### Estimation of weighted prevalence

For this we go back `anthro.02` dataset. 

We approach this task as follows: 

```{r}
#| label: wt_muac_prev
#| echo: true
#| eval: false

anthro.02 |>
  mw_wrangle_age(
    age = age,
    .decimals = 2
  ) |>
  mw_wrangle_muac(
    sex = sex,
    .recode_sex = FALSE,
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age
  ) |>
  mutate(
    muac = recode_muac(muac, .to = "mm")
  ) |>
  mw_estimate_prevalence_muac(
    muac = muac,
    age = age,
    wt = wtfactor,
    oedema = oedema,
    province
  )
```

This will return: 

```{r}
#| label: view_wt_muac_prev
#| echo: false
#| message: false

anthro.02 |>
  mw_wrangle_age(
    age = age,
    .decimals = 2
  ) |>
  mw_wrangle_muac(
    sex = sex,
    .recode_sex = FALSE,
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age
  ) |>
  mutate(
    muac = recode_muac(muac, .to = "mm")
  ) |>
  mw_estimate_prevalence_muac(
    muac = muac,
    age = age,
    wt = wtfactor,
    oedema = oedema,
    province
  )
```

:::{.callout-warning}

You may have noticed that in the above code block, we called the `recode_muac()` function inside `mutate()`. This is because after you use `mw_wrangle_muac()`, it puts the MUAC variable in centimetres. The `mw_estimate_prevalence_muac()` function was defined to accept MUAC in millimetres; therefore, it must be converted to millimetres. 

:::

### Estimation for non-survey data

The `anthro.04` dataset will be used to illustrate the application of these functions.
```{r}
#| label: non-survey
#| echo: true
#| eval: false

anthro.04 |>
  mw_wrangle_age(age = age) |>
  mw_wrangle_muac(
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age,
    sex = sex,
    .recode_sex = FALSE
  ) |>
  mutate(muac = recode_muac(muac, "mm")) |>
  mw_estimate_prevalence_screening(
    muac = muac,
    age = age,
    oedema = oedema,
    analysis_unit
  )
```

The returned output is: 
```{r}
#| label: non-survey-view
#| echo: false

anthro.04 |>
  mw_wrangle_age(age = age) |>
  mw_wrangle_muac(
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age,
    sex = sex,
    .recode_sex = FALSE
  ) |>
  mutate(muac = recode_muac(muac, "mm")) |>
  mw_estimate_prevalence_screening(
    muac = muac,
    age = age,
    oedema = oedema,
    analysis_unit
  )
```

The `mw_estimate_prevalence_screening2()` function is applied as demonstrated below. In this example, the input data contains age in months rather than in categories. To meet the function’s requirements, we convert the age variable into two categories and store the result in a new `age_cat` variable.

```{r}
#| label: non-survey2
#| echo: true
#| eval: false

anthro.04 |>
  mutate(age_cat = ifelse(age < 24, "6-23", "24-59")) |>
  mw_wrangle_muac(sex = sex, .recode_sex = TRUE, muac = muac) |>
  mw_estimate_prevalence_screening2(
    age_cat = age_cat,
    muac = muac,
    oedema = oedema,
    analysis_unit
  )
```

This will return: 
```{r}
#| label: non-survey2-view
#| echo: true
#| eval: false

anthro.04 |>
  mutate(age_cat = ifelse(age < 24, "6-23", "24-59")) |>
  mw_wrangle_muac(sex = sex, .recode_sex = TRUE, muac = muac) |>
  mw_estimate_prevalence_screening2(
    age_cat = age_cat,
    muac = muac,
    oedema = oedema,
    analysis_unit
  )
```


## Estimation of the combined prevalence of wasting

The estimation of the combined prevalence of wasting is a task attributed to the `mw_estimate_prevalence_combined()` function. The case-definition is based on the WFHZ, the raw MUAC values and oedema. From the workflow standpoint, it combines the workflow demonstrated in @sec-prevalence-wfhz and in @sec-prevalence-muac.

To demonstrate it's implementation we will use the `anthro.01` dataset.

Let's inspect the data:
```{r} 
#| label: view_anthro.01
#| echo: false
head(anthro.01)
```

#### Data wrangling

It combines the data wrangling workflow of WFHZ and MUAC: 
```{r}
#| label: combined_wrangling
#| echo: true
#| eval: false

## Apply the wrangling workflow ----
anthro.01 |>
  mw_wrangle_age(
    dos = dos,
    dob = dob,
    age = age,
    .decimals = 2
  ) |>
  mw_wrangle_muac(
    sex = sex,
    .recode_sex = TRUE,
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age
  ) |>
  mutate(
    muac = recode_muac(muac, .to = "mm")
  ) |>
  mw_wrangle_wfhz(
    sex = sex,
    weight = weight,
    height = height,
    .recode_sex = FALSE
  )
```

This is to get the `wfhz` and `flag_wfhz` the `mfaz` and `flag_mfaz` added to the dataset. In the output below, we have just selected these columns: 

```{r}
#| label: view_combined_wrangling
#| echo: false
#| message: false

anthro.01 |>
  mw_wrangle_age(
    dos = dos,
    dob = dob,
    age = age,
    .decimals = 2
  ) |>
  mw_wrangle_muac(
    sex = sex,
    .recode_sex = TRUE,
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age
  ) |>
  mutate(
    muac = recode_muac(muac, .to = "mm")
  ) |>
  mw_wrangle_wfhz(
    sex = sex,
    weight = weight,
    height = height,
    .recode_sex = FALSE
  ) |>
  select(area, wfhz, flag_wfhz, mfaz, flag_mfaz)
```

Under the hood, the function applies the same analysis approach as in `mw_estimate_prevalence_wfhz` and in `mw_estimate_prevalence_muac()`.
In this function, a concept of "combined flags" is used.
  
:::{.callout-note}
#### What is combined flag?

Combined flags consists in defining as flag any observation that is flagged in either `flag_wfhz` or `flag_mfaz` vectors. A new column `cflags` for combined flags is created and added to the dataset. This ensures that all flagged observations from both WFHZ and MFAZ data are excluded from the prevalence analysis.

:::

| **flag_wfhz** | **flag_mfaz** | **cflags** |
| :---: | :---: | :---: |
| 1 | 0  | 1 |
| 0 | 1  | 1 |
| 0 | 0  | 0 |
: A glimpse of case-definition of combined flag


Now that we understand what happens under the hood, we can now proceed to implement it: 

```{r}
#| label: cwasting
#| echo: true
#| eval: false

## Apply the workflow ----
anthro.01 |>
  mw_wrangle_age(
    dos = dos,
    dob = dob,
    age = age,
    .decimals = 2
  ) |>
  mw_wrangle_muac(
    sex = sex,
    .recode_sex = TRUE,
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age
  ) |>
  mutate(
    muac = recode_muac(muac, .to = "mm")
  ) |>
  mw_wrangle_wfhz(
    sex = sex,
    weight = weight,
    height = height,
    .recode_sex = FALSE
  ) |>
  mw_estimate_prevalence_combined(
    wt = NULL,
    oedema = oedema,
    area
  )
```

We get this: 

```{r}
#| label: view_cwasting
#| echo: false

anthro.01 |>
  mw_wrangle_age(
    dos = dos,
    dob = dob,
    age = age,
    .decimals = 2
  ) |>
  mw_wrangle_muac(
    sex = sex,
    .recode_sex = TRUE,
    muac = muac,
    .recode_muac = TRUE,
    .to = "cm",
    age = age
  ) |>
  mutate(
    muac = recode_muac(muac, .to = "mm")
  ) |>
  mw_wrangle_wfhz(
    sex = sex,
    weight = weight,
    height = height,
    .recode_sex = FALSE
  ) |>
  mw_estimate_prevalence_combined(
    wt = NULL,
    oedema = oedema,
    area
  )
```

In district E `NA`s were returned because there were issues with the data. I leave it to you to figure out what was/were the issue/issues. 

:::{.callout-tip}

Consider running the plausibility checkers.

:::