README.Rmd

---
title: Tidyndr
output: github_document
---

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

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

<!-- <a href='https://github.com/stephenbalogun/tidyndr/tree/master/man/figures/logo.svg'><img src="man/figures/logo.svg" align="right" height="139"/></a> -->

<!-- badges: start -->

[![R-CMD-check](https://github.com/stephenbalogun/tidyndr/workflows/R-CMD-check/badge.svg)](https://github.com/stephenbalogun/tidyndr/actions) [![Codecov test coverage](https://codecov.io/gh/stephenbalogun/tidyndr/branch/master/graph/badge.svg)](https://app.codecov.io/gh/stephenbalogun/tidyndr?branch=master/) [![CRAN status](https://www.r-pkg.org/badges/version/tidyndr)](https://CRAN.R-project.org/package=tidyndr) [![Total CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/tidyndr?color=blue)](https://cranlogs.r-pkg.org/#badges) [![Monthly CRAN downloads](https://cranlogs.r-pkg.org/badges/tidyndr)](https://cranlogs.r-pkg.org/#badges)

<!-- badges: end -->

The goal of {tidyndr} is to provide a specialized, simple and easy to use functions that wrap around existing functions in `R` for manipulation of the [NDR](https://ndr.phis3project.org.ng/) patient line-list file allowing the user to focus on the tasks to be completed rather than the code/formula details.

The functions presented are similar to the PEPFAR Monitoring Evaluation and Reporting Indicators and are currently grouped into four categories:

-   The `read_ndr` function for reading the patient-level line-list downloaded from the front-end of the NDR in 'csv' format.

-   The PEPFAR treatment group of indicators that can be performed on the NDR line-list.

-   The 'Viral Load' indicators (`tx_vl_eligible()`, `tx_pvls_den()` `tx_pvls_num()` and `tx_vl_unsuppressed()`).

-   The summary functions (`summarise_ndr()` and `disaggregrate()`) provides a tabular summary for the tasks that have been completed using any of the functions above.

## Installation

You can install the released version of {tidyndr} from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("tidyndr")
```

Or the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("stephenbalogun/tidyndr",
build_vignette = TRUE)
```

## Usage

```{r load_library}
library(tidyndr)
```

### read_ndr

`read_ndr()` reads the downloaded ".csv" file into [`R`](https://cran.r-project.org) using [`vroom::vroom()`](https://vroom.r-lib.org/) behind the scene and passing appropriate column types to the `col_types` argument. It also formats the variable names using the [`snakecase`](https://en.wikipedia.org/wiki/Snake_case) style.

```{r read_ndr}
## read from a local file path (not run)

# file_path <- system.file("extdata", "ndr_example.csv", package = "tidyndr")

# read_ndr(file_path, time_stamp = "2021-02-15")

### read line-list available on the internet
path <- "https://raw.githubusercontent.com/stephenbalogun/example_files/main/ndr_example.csv"

ndr_example <- read_ndr(path, time_stamp = "2021-02-20")
```

### Treatment Indicators

The functions included in this group are:

-   `tx_new()`

-   `tx_curr()`

-   `tx_ml()` and `tx_ml_outcomes()`

-   `tx_rtt()`

-   Other supporting functions are: `tx_mmd()`, `tx_regimen()` and `tx_appointment()`

```{r tx_indicators}
## Subset "TX_NEW"
tx_new(ndr_example, from = "2021-01-01", to = "2021-03-31")


## Generate line-list of clients with medication refill in October 2021
ndr_example %>%
  tx_appointment(from = "2021-01-01",
                 to = "2021-01-31"
                 )

## Generate list of clients who were active at the beginning of October 2021 but became inactive at the end of December 2021.
  tx_ml(new_data = ndr_example,
        from = "2021-01-01",
        to = "2021-03-31")
```

### Viral Suppression Indicators

The `tx_vl_eligible()`, `tx_pvls_den()` and the `tx_pvls_num()` functions come in handy when you need to generate the line-list of clients who are eligible for viral load test at a given point for a given facility/state, those who have a valid viral load result (not more than 1 year for people aged 20 years and above and not more than 6 months for paediatrics and adolescents less or equal to 19 years), and those who are virally suppressed (out of those with valid viral load results). When the `sample = TRUE` attribute is supplied to the `tx_vl_eligible()` function, it generates the line-list of only those who are due for a viral load test out of all those who are eligible.

```{r vl_indicators}
## Generate list of clients who are eligible for VL (i.e. expected to have a documented VL result)
ndr_example %>%
  tx_vl_eligible(ref = "2021-12-31")

## Generate list of clients that will be expected to have a viral load test done by March 2022
ndr_example %>%
  tx_vl_eligible("2022-03-31",
                 sample = TRUE)

### Calculate the Viral Load Coverage as of December 2021
no_of_vl_results <- tx_pvls_den(ndr_example,
                                ref = "2021-12-31") %>%
  nrow()
no_of_vl_eligible <- tx_vl_eligible(ndr_example,
                                    ref = "2021-12-31") %>%
  nrow()

vl_coverage <- scales::percent(no_of_vl_results / no_of_vl_eligible)

print(vl_coverage)
```

For all the 'Treatment' and 'Viral Suppression' indicators (except `tx_ml_outcomes()`, which should be use with `tx_ml()`), you have control over the level of action (state or facility) by supplying to the `states` and/or `facilities` arguments the values of interest . For more than one state or facility, combine the values with the `c()` e.g.

```{r multiple_indicators}
## subset clients that have medication appointment in between January and March of 2021 in 
## and are also due for viral load
ndr_example %>%
  tx_appointment(from = "2021-01-01",
                 to = "2021-03-31",
                 ) %>%
  tx_vl_eligible(sample = TRUE)
```

### Summarising your Indicators

You might want to generate a summary table of all the indicators you have pulled out. The `summarise_ndr()` (or `summarize_ndr()`) allows you to do this with ease. It accepts all the line-lists you are interested in creating a summary table for, the level at which you want the summary to be created (country/ip, state or facility), and the names you want to give to each of your summary column.

```{r, summarise_ndr}
## generates line-list of TX_NEW between July and December 2021
new <- tx_new(ndr_example, from = "2021-01-01", to = "2021-03-31")

## generates line-list of currently active clients
curr <- tx_curr(ndr_example)

## generates line-list of clients who were active at the beginning of the October but inactive at end of December 2021
ml <- tx_ml(new_data = ndr_example, from = "2021-01-01", to = "2021-03-31") 

summarise_ndr(new, curr, ml,
              level = "state",
              names = c("tx_new", "tx_curr", "tx_ml"))
```

The `disaggregate()` allows you to summarise an indicator of interest into finer details based on "current_age", "sex" "pregnancy_status", "art_duration", "months_dispensed (of ARV)" or "age_sex". These are supplied to the `by` parameter of the function. The default disaggregates the variable of interest at the level of "states" but can also do this at "country/ip", "lga" or "facility" level when any of this is supplied to the `level` parameter.

```{r, disagg}
## generates line-list of TX_NEW between July and September 2021
new_clients <- tx_new(ndr_example, from = "2021-01-01", to = "2021-03-30")

disaggregate(new_clients,
             by = "current_age", pivot_wide = FALSE)

## disaggregate 'TX_CURR' by sex

ndr_example %>%
  tx_curr() %>%
  disaggregate(by = "sex")
```

## Code of Conduct

Please note that the {tidyndr} project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.