Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Readme #29

Merged
merged 6 commits into from
Oct 9, 2024
Merged

Readme #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a62db79
revise readme file
tomaszaba Oct 7, 2024
c9c8717
update readme file
tomaszaba Oct 8, 2024
046d677
update grVIZ
tomaszaba Oct 8, 2024
4a67f2f
centralize grViz
tomaszaba Oct 8, 2024
c1d06ad
centralize grViz
tomaszaba Oct 8, 2024
8a6579c
revise readme
tomaszaba Oct 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Contributing

## Bugs

* Submit an issue on the [issues page](https://github.com/nutriverse/mwana/issues)

## Code contributions

* Fork this repository to your Github account

* Clone your version on your account down to your machine from your account

```
git clone https://github.com/<yourgithubusername>/mwana.git
```

* Make sure to track progress upstream i.e., on our version of `mwana`
at `nutriverse/mwana`, by doing

```
git remote add upstream https://github.com/nutriverse/mwana.git
```

* Before making changes make sure to pull changes in from `upstream` by doing
either `git fetch upstream` then merge later or `git pull upstream` to fetch
and merge in one step

* Make your changes on a new feature branch

* Please write a test or tests for your changes if they affect code and not just
documentation

* Push up changes to your account

* Submit a pull request at `nutriverse/mwana`
29 changes: 11 additions & 18 deletions DESCRIPTION
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,21 @@
Type: Package
Package: ipccheckr
Title: Toolkit for Performing IPC Acute Malnutrition-related Data Checks
Title: Utilities for Analysing Children's Nutritional Status
Version: 0.0.0.9000
Authors@R: c(
person("Tomás", "Zaba", , "tomas.zaba@outlook.com", role = c("aut", "cre", "cph"),
comment = c(ORCID = "0000-0002-7079-3574")),
person("Ernest", "Guevarra", role = c("aut", "cph"),
comment = c(ORCID = "0000-0002-4887-4415")),
person("Douglas", "Jayasekaran", role = "ctb")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should revisit Douglas' role. If he reviews the package, then we should put him down as rev for reviewer. If he gives substantial feedback other than "looks great" or "I wish it can be better", then we can consider upgrading this role to ctb. For me, my criteria for a contributor is someone who provides at least one of the following:

  • feedback on code for function/s with a specific suggestion on what improvement is needed and/or what functionality should be added;
  • feedback on documentation other than spelling or grammar focusing on coherence and content that improves documentation for general audience; or.
  • provides a PR with suggested changes in functions and/or documentation.

A PR that is accepted and merged will automatically merit a ctb role as code from that person will actually get incorporated onto the package and will show in the git commits and diffs. The first two above will require really determining the significance of the person's feedback and whether or not we used that feedback to change/edit the package.

So, let us revisit this after you have shared/presented the package to him.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will be able to ascertain the type of his contribution once I share the link with him to review the documentation.I expect his reviews on the Vignettes, other than the function documentation per se. We can revisit this later.

comment = c(ORCID = "0000-0002-4887-4415"))
)
Description: The Integrated Food Security Phase Classification (IPC) for
Acute Malnutrition is a global tool used to classify geographical
areas based on the prevalence of acute malnutrition. An IPC AMN
product is primarily used to inform countries Humanitarian Needs
Overview (HNO) of the Humanitarian Programme Cycle (HPC). The accepted
sources of evidence on prevalence of acute malnutrition varies from
surveys, community-based screenings and sent- inel sites. According to
the IPC AMN protocols, every evidence must be subject to quality
checks to ascertain their reliability and decided whether to use or
not. This package provides useful functions and utilities that
supports IPC AMN-related data analysis check.
Description: A streamlined and comprehensive implementation of the Standardized
Monitoring and Assessment of Relief and Transition (SMART) Methodology
<https://smartmethodology.org/> guidelines for data quality checks and
prevalence estimation, with enhanced programmable process particularly when
handling large multiple datasets.
License: GPL (>= 3)
URL: https://github.com/tomaszaba/ipccheckr
BugReports: https://github.com/tomaszaba/ipccheckr/issues
URL: https://github.com/nutriverse/mwana, https://nutriverse.io/mwana
BugReports: https://github.com/nutriverse/mwana/issues
Imports:
dplyr (>= 1.1.4),
lubridate,
Expand All @@ -42,8 +35,8 @@ Config/testthat/edition: 3
Encoding: UTF-8
Language: en-GB
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.1
RoxygenNote: 7.3.2
Depends:
R (>= 2.10)
R (>= 4.1)
LazyData: true
VignetteBuilder: knitr
190 changes: 92 additions & 98 deletions README.Rmd
View file
Open in desktop

Large diffs are not rendered by default.

267 changes: 144 additions & 123 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,136 +1,146 @@


<!-- README.md is generated from README.Rmd. Please edit that file -->

# `ipccheckr`:Toolkit for Performing IPC Acute Malnutrition-related Data Checks
# `mwana`: Utilities for Analysing Children’s Nutritional Status

<!-- badges: start -->

[![R-CMD-check](https://github.com/tomaszaba/ipccheckr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/tomaszaba/ipccheckr/actions/workflows/R-CMD-check.yaml)
[![Lifecycle:
experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![Project Status: WIP – Initial development is in progress, but there
has not yet been a stable, usable release suitable for the
public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
[![R-CMD-check](https://github.com/nutriverse/mwana/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/tomaszaba/ipccheckr/actions/workflows/R-CMD-check.yaml)
[![Codecov test
coverage](https://codecov.io/gh/tomaszaba/ipccheckr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/tomaszaba/ipccheckr?branch=main)
coverage](https://codecov.io/gh/nutriverse/mwana/branch/main/graph/badge.svg)](https://app.codecov.io/gh/tomaszaba/ipccheckr?branch=main)
<!-- badges: end -->
<img src="man/figures/logo.png" align="right" height="250" alt="" />

## Background

IPC AMN is a global tool that uses a set o protocols to classify
geographical areas into a 5-phases severity based on the prevalence of
acute malnutrition among children aged 6:59 months. Its main objective
is to provide actionable information for decision-makers. It is not a
data collection method *per se*, therefore, it relies on evidence
generated through other methods (representative surveys, screening,
sentinel sites, etc). Before any evidence is used an IPC AMN analysis,
checks must performed to ascertain the quality of data, following the
minimum quality standards set in the protocol, hence its reliability. As
such, only evidence that pass the checks are allowed to be used in an
IPC analysis exercise.

## Why `ipccheckr`?

The typical analysis workflow is overly complex, tiring and tedious,
time-consuming and not not reproducible. Oftentimes, due to demand, the
workflow needs to be implemented on a pile of data in absolute short
time, making the process prone to human errors due to fatigue. In the
workflow, data “checker” needs to travel from software to software as
follows: SPSS software (mostly) to process data and export to Excel or
CSV to then import it into Emergency Nutrition Assessments (ENA) for
SMART software for to run the quality. From this stage downstream, the
workflow needs to be done one-by-one for the number of survey area a
data set may hold: run the quality check, then transfer the summary
results into a summary table (Excel spreadsheet or other). Then, run the
prevalence analysis (also one-by-one), and then transfer the results
into a spreadsheet and so on and so forth. Sometimes, a fourth tool is
used to correct for a likely overestimation of acute malnutrition
prevalence based on MUAC when there are excess of younger children (6:23
months) over older children (24:59 months) in the sample. Therefore, the
`ipccheckr` was developed simply to make the workflow simpler, joyful
and reproducible thanks to its array of handy functions.

## What does `ipccheckr` do?

In a nutshell, the array of exported functions span from sample size
checkers, data processors, quality checkers, prevalence calculators as
well as some handy functions to render formatted and presentable output
tables on the two latter groups of functions.

### Plausibility checks with `ipccheckr`

You can run plausibility checks on:

- Weight-for-height z-score (WFHZ) data
- MUAC-for-age z-score (MFAZ) data *when **age** variable **is**
available*
- Absolute values of MUAC data *when **age** variable **is not**
available*

#### Useful workflow with `ipccheckr` for data quality check

![](man/figures/README-ipccheckr_workflow-1.png)<!-- -->

### On the prevalence analysis

After the data quality checks workflow, you will now be in position to
decide whether or not you can proceed to the prevalence analysis. The
workflow is quite simple: you use the data returned by the data
processors in the above workflow. `ipccheckr` can compute acute
malnutrition prevalence based on:

- WFHZ and/or edema - guide
- MUAC and/or edema - guide
- Combined prevalence (of WFHZ and MUAC and edema) - guide
- MFAZ and/or edema - guide

<style>
.callout-tip {
border-left: 4px solid #2ECC71; /* Green border */
background-color: #EAFAF1; /* Light green background */
padding: 10px;
margin: 20px 0;
border-radius: 10px;
}
</style>

<div class="callout-tip">

<strong>💡 Tip </strong>

Despite the fact that this package was designed with the idea of
simplifying the IPC AMN checks workflow in mind, you can absolutely use
its utilities beyond this scope. For instance, if you are undertaking a
research and you want to censor your data before including in your
statistical models, etc, you can use this packages utilities for that.

</div>

<style>
.callout-warning {
border-left: 4px solid #FF4500; /* Red border */
background-color: #FDEDEC; /* Light red background */
padding: 10px;
margin: 20px 0;
border-radius: 10px;
}
</style>

<div class="callout-warning">

<strong>⚠️ Warning</strong>

Please note that `ipccheckr` is still highly experimental and is
undergoing a lot of development. Hence, any functionalities described
below have a high likelihood of changing interface or approach as we aim
for a stable working version.

</div>

Child anthropometric assessments, implemented routinely in most
countries worldwide, are the cornerstones of child nutrition and food
security surveillance around the world. Ensuring the quality of child
anthropometric data, the accuracy of child undernutrition prevalence
estimates, and the timeliness of reporting is therefore critical in
establishing accurate, robust, and up-to-date child undernutrition
status globally.

`mwana`, term for *child* in *Elómwè*, a local language spoken in the
central-northern regions of Mozambique, and also a word with a similar
meaning across other Bantu languages (such as Swahili) spoken in many
parts of Africa, is a package that streamlines child anthropometry data
quality checks and undernutrition prevalence estimation for children
6-59 months old through comprehensive implementation of the SMART
Methodology guidelines in R.

## Motivation

`mwana` was borne out of the author’s own experience of having to work
with multiple child anthropometric datasets to conduct data quality
appraisal and prevalence estimation as part of the data quality
assurance team of the Integrated Phase Classification (IPC). The current
standard child anthropometric data appraisal workflow is extremely
cumbersome requiring significant time and effort utilising different
software tools (SPSS, Excel, Emergency Nutrition Assessment or ENA
software) for each step of the process for a single dataset. This
process is repeated for every dataset needing to be processed and often
needing to be implemented in a relatively short period time. This manual
and repetitive process, by its nature, is extremely error-prone.

`mwana`, which is primarily an R-based implementation of the ENA for
SMART software, simplifies this cumbersome workflow into a programmable
process particularly when handling large multiple datasets.

> [!NOTE]
>
> `mwana` was made possible thanks to the state-of-the-art work in
> nutrition survey guidance led by the [SMART
> initiative](https://smartmethodology.org). Under to hood, `mwana`
> bundles the SMART guidance through the use of the National Information
> Platforms for Nutrition Anthropometric Data Toolkit (nipnTK)
> functionalities in `R` to build its handy function around plausibility
> checks. Click [here](https://github.com/nutriverse/nipnTK) to learn
> more about the `nipnTK` package.

## What does `mwana` do?

It automates plausibility checks and prevalence analyses and respective
summaries of the outputs.

### Plausibility checks.

- `mwana` performs plausibility checks on weight-for-height z-score
(WFHZ)-based data by mimicking the SMART plausibility checkers in ENA
for SMART software, their scoring and classification criterion.

- It performs, as well, plausibility checks on MUAC data. For this,
`mwana` integrates recent advances in using MUAC-for-age z-score
(MFAZ) for auditing the plausibility of MUAC data. In this way, when
the variable age is available: `mwana` performs plausibility checks
similar to those in WFHZ, however with few differences in the scoring.
Otherwise, when the variables age is missing, a similar test suit used
in the current version of ENA is performed. Read details here.

#### A useful workflow for plausibility check using `mwana`

<img src="man/figures/README-worflow-1.png" data-fig-align="center" />

### Prevalence analysis

`mwana` prevalence calculators were built to take decisions on the
appropriate analysis procedure to follow based on the quality of the
data, as per the SMART rules. It returns an output table with the
appropriate results based on the data quality test results.
Fundamentally, the calculators loop over the survey areas in the dataset
whilst performing quality appraisal and taking decisions on the
appropriate prevalence analysis procedure to follow on the basis of the
result.

`mwana` computes prevalence for:

- Wasting on the basis of WFHZ and/edema (Read vignettes)
- Wasting on the basis of the absolute values of MUAC and/or edema:
here, when variable age is available, mwana applies MFAZ flags,
otherwise it applies the flagging criteria around the absolute values
of MUAC, to exclude outliers before computing prevalence, but the
actual prevalence is done on the absolute values. (Read link to the
specific section in the vignettes)
- Wasting on the basis of MFAZ and/edema: outliers excluded using MFAZ
flags. (Read link to the specific section in the vignettes)
- Combined prevalence of wasting: here a concept of combined flags is
used to streamline the flags removed in WFHZ and those in MUAC. (Read
link to the specific section in the vignettes).

`mwana` provides weighted prevalence analysis, if needed. And this is
controlled by the user. This is possible in all calculators, including
for MUAC, combined, which is not currently available in ENA for SMART.

In the context of IPC Acute Malnutrition (IPC AMN) analysis workflow,
`mwana` provides a handy function for checking if the minimum sample
size requirements in a given area were met on the basis of the
methodology used to collect the data: survey, screening or sentinel
sites. (Check out the vignette).

> [!TIP]
>
> If you are undertaking a research and you want to censor your data
> before including in your statistical models, etc, `mwana` is a great
> helper, as it identifies flags out of your anthro data.

> [!WARNING]
>
> Please note that `mwana` is still highly experimental and is
> undergoing a lot of development. Hence, any functionalities described
> below have a high likelihood of changing interface or approach as we
> aim for a stable working version.

## Installation

`ipccheckr` is not yet on CRAN but you can install the development
version from [GitHub](https://github.com/) with:
`mwana` is not yet on CRAN but you can install the development version
from [nutriverse R universe](https://nutriverse.r-universe.dev) as
follows:

``` r
# install.packages("devtools")
devtools::install_github("tomaszaba/ipccheckr")
remotes::install_github("tomaszaba/ipccheckr")
```

Then load to in memory with
Expand All @@ -141,9 +151,9 @@ library(ipccheckr)

# Citation

If you were enticed to using `ipccheckr` package and found it useful,
please cite using the suggested citation provided by a call to
`citation` function as follows:
If you were enticed to use `mwana` package and found it useful, please
cite using the suggested citation provided by a call to `citation`
function as follows:

``` r
citation("ipccheckr")
Expand All @@ -163,3 +173,14 @@ citation("ipccheckr")
#> url = {https://github.com/tomaszaba/ipccheckr},
#> }
```

# Community guidelines

Feedback, bug reports and feature requests are welcome; file issues or
seek support [here](https://github.com/nutriverse/mwana/issues). If you
would like to contribute to the package, please see our [contributing
guidelines](https://nutriverse.io/mwana/CONTRIBUTING.html).

This project is releases with [Contributor Code of
Conduct](https://nutriverse.io/mwana/CODE_OF_CONDUCT.html). By
participating in this project you agree to abide by its terms.
Loading
Loading