README.Rmd

---
output: github_document
---

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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# codeditr: Implementing Cause-of-Death Data Checks Based on the WHO CoDEdit Tool <img src='man/figures/logo.png' width='200px' align='right' />

<!-- badges: start -->
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![codeditr status badge](https://oxfordihtm.r-universe.dev/badges/codeditr)](https://oxfordihtm.r-universe.dev/codeditr)
[![R-CMD-check](https://github.com/OxfordIHTM/codeditr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/OxfordIHTM/codeditr/actions/workflows/R-CMD-check.yaml)
[![test-coverage](https://github.com/OxfordIHTM/codeditr/actions/workflows/test-coverage.yaml/badge.svg)](https://github.com/OxfordIHTM/codeditr/actions/workflows/test-coverage.yaml)
[![Codecov test coverage](https://codecov.io/gh/OxfordIHTM/codeditr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/OxfordIHTM/codeditr?branch=main)
[![CodeFactor](https://www.codefactor.io/repository/github/OxfordIHTM/codeditr/badge)](https://www.codefactor.io/repository/github/OxfordIHTM/codeditr)
[![DOI](https://zenodo.org/badge/752255505.svg)](https://zenodo.org/badge/latestdoi/752255505)
<!-- badges: end -->

The [World Health Organization](https://www.who.int/)'s [CoDEdit electronic tool](https://www.who.int/standards/classifications/classification-of-diseases/services/codedit-tool) is intended to help producers of cause-of-death statistics in strengthening their capacity to perform routine checks on their data. This package ports the original tool built using Microsoft Access into R. The aim is to leverage the utility and function of the original tool into a usable application program interface (API) that can be used for building more universal tools or for creating programmatic scientific workflows aimed at routine, automated, and large-scale monitoring of cause-of-death data.

## What does `codeditr` do?

The `codeditr` package provides functions for implementing data quality checks on cause-of-death records. It is built upon the same heuristics and algorithms that the WHO CoDEdit v2.0 electronic tool uses to evaluate quality of cause-of-death data produced and used by country level statisticians in charge of mortality reporting.

Through this package, end users will have the ability to programmatically create scientific workflows for routine monitoring and evaluation and/or research on cause-of-death data and their quality. They can also build more open tools or applications for routine monitoring of cause-of-death data without having to rely on the proprietary Microsoft Access software.

Currently, the `codeditr` package supports the following use cases:

1. Cause-of-death dataset preparation for use in the CoDEdit tool

To be able to use WHO's CoDEdit tool built on Microsoft Access, the user can either enter their cause-of-death data into the tool itself using a spreadsheet style input system with very specific input fields or through uploading of a Microsoft `.xlsx` file that is structured in a specific way required by the tool.

The `codeditr` package has a set of functions that support in checking that specific required variables are formatted to be compatible for the CoDEdit tool and structures these variables into a dataset that is consistent with what is required for uploading to the CodEdit tool.

This use case are for those what would still prefer to use WHO's CoDEdit tool using Microsoft Access (either for continuity purposes or for consistency with organisational policy) but would like to have the functionality of converting their existing cause-of-death dataset into a CoDEdit tool-compatible format and structure.

2. Cause-of-death dataset checking to identify data quality issues

The `codeditr` package has a set of functions that performs all the checks that the CoDEdit tool performs in addition to other general data quality checks. These functions allow for a similar output as the CoDEdit tool

This use case are for those that prefer not to use Microsoft Access (either because they don't already own a copy of this software or that their purpose for data quality checks is for large-scale datasets) and would like a completely programmatic approach to performing routine and potentially large scale cause-of-death data quality checks.

## Installation

`codeditr` is not yet on CRAN but can be installed through the [Oxford iHealth R Universe](https://oxfordihtm.r-universe.dev) with:

```{r install, eval = FALSE}
install.packages(
  "codeditr",
  repos = c("https://oxfordihtm.r-universe.dev", "https://cloud.r-project.org")
)
```

then load `codeditr`

```{r gh-installation2, eval = TRUE}
# load package
library(codeditr)
```

## Usage

### Support to usage of CoDEdit tool

1. Perform checks on existing input data for CoDEdit tool

Using the `icd10_example` dataset which is a dataset already formatted into a compatible structure required by the CoDEdit tool, we can perform a check on this dataset to see possible issues in its formatting and structure before using with the CoDEdit tool.

```{r use-case-1a}
cod_check_codedit_input(icd10_example)
```

2. Structure raw cause-of-death data for input into CoDEdit tool

Using the `cod_data_raw_example` dataset, we can format it into a compatible structure required by the CoDEdit tool.

```{r use-case-2a}
cod_structure_input(
  df = cod_data_raw_example, 
  sex = "sex", dob = "dob", dod = "dod", code = "code", id = "id"
)
```

The output is a data.frame that can then be saved as an `.xlsx` file for use as input into the CoDEdit tool.

### CoDEdit tool replacement workflow

1. Perform all checks on cause-of-death data

The `cod_check_code()` function performs all the checks implemented by the CoDEdit tool.

```{r use-case-3}
cod_check_code(
  cod_data_raw_example$code, version = "icd11", 
  sex = cod_data_raw_example$sex, age = cod_data_raw_example$age
)
```

Results of the per row cause-of-death checks can also be summarised to give a count of issues found in the dataset.

```{r use-case-4}
cod_check_code(
  cod_data_raw_example$code, version = "icd11", 
  sex = cod_data_raw_example$sex, age = cod_data_raw_example$age
) |>
  cod_check_code_summary()
```

2. Perform specific check types on cause-of-death data

The family of `cod_check_code_*` functions can be used to perform specific check types on the cause-of-death data.

```{r use-case-5}
### Perform code structure check on cause-of-death data ----
cod_check_code_structure_icd10(icd10_example$Code)

### Perform check for ill-defined codes on cause-of-death data ----
cod_check_code_ill_defined_icd11(cod_data_raw_example$code)

### Perform check for unlikely cause-of-death codes ----
cod_check_code_unlikely_icd11(cod_data_raw_example$code)

### Perform check for cause-of-death codes inappropriate for specific sex ----
cod_check_code_sex_icd11(cod_data_raw_example$code, cod_data_raw_example$sex)

### Perform check for cause-of-death codes inappropriate for specific age ----
cod_check_code_age_icd11(cod_data_raw_example$code, cod_data_raw_example$age)
```

## Citation

If you find the `codeditr` package useful please cite using the suggested citation provided by a call to the `citation()` function as follows:

```{r citation}
citation("codeditr")
```

## Community guidelines

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

This project is released with a [Contributor Code of Conduct](https://OxfordIHTM/codeditr/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms.