---
title: "Introduction to tidyndr"
output: rmarkdown::html_vignette
description: >
  You'll learn the basic principle of the tidyndr package, the conception, and how it helps to perform a seamless analysis of the Nigeria National Data Repository of HIV program in.
vignette: >
  %\VignetteIndexEntry{Introduction to tidyndr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(collapse = T, comment = "#>")
options(tibble.print_min = 4L, tibble.print_max = 4L)
library(tidyndr)
set.seed(1014)
```

> *"To measure is to know. If you cannot measure it, you cannot improve it."*
>
> \- Lord Kelvin

The [Nigeria National Data Repository (NDR)](https://ndr.phis3project.org.ng/) houses the de-identified patient-level information for the HIV program in Nigeria. Perhaps the most versatile feature of the repository is that it allows users with login access to download this patient-level information, analyze, and make informed decisions to improve the response of their program towards achieving the [UNAIDS](https://www.unaids.org/) **three 95s** targets.You can download "treatment", "recent infection" and "HTS" line lists.

Analysis of the de-identified patient-level information is traditionally conducted in Microsoft Excel. While this provides a great platform, it has some downsides which include:

1.  The software must be installed on the user's computer.

2.  The user must be familiar with the formula for calculation of the indicator of interest.

3.  Because of the point-and-click nature of the analysis, it is error-prone. Sometimes these errors go unnoticed by the users giving a rather false result.

4.  Performing the same analysis periodically can be quite tedious and time-consuming as the analysis is usually done afresh every time.

The aim of the {tidyndr} package is to eliminate these hurdles by providing the user with an application that can be conducted on a free and open-source software, allows the user to focus on the task to be performed and not the formula, remove user-defined errors, and allow for easy automation of routine activities.

The {tidyndr} functions are grouped into five categories for performing related actions.

1.  Importing functions

2.  Treatment functions

3.  Viral Load functions

4.  Summary functions

5. HIV-1 recent infection functions

```{r, eval = FALSE}
library(tidyndr)
```

## Importing your NDR line-list

The `read_ndr()` function allows you to import your line-list in a nicely configured format for data analysis. It:

1.  Reads your `.csv` file.

2.  Formats the data type for each of the column variables as necessary (converts all date variables to dates and categorical variables to factors).

3.  Converts all column names to [snake case](https://en.wikipedia.org/wiki/Snake_case) format.

4.  Adds three new columns to your treatment data - `date_lost` (calculated by adding 28 days to the sum of `last_drug_pickup_date` and the `days_of_arv_refill`), `appointment_date` (calculated by adding the number of `days_of_arv_refill` to the `last_drug_pickup_date`, and `current_status` (calculated by classifying the patient as "active" or "inactive" using the value of the `time_stamp` argument as a reference.

The `read_ndr()` is an `s3 generic` function that calls another function depending on the type of line-list supplied

-   `path` - this specifies the location of the NDR line-list to be imported. You can do this either by specifying the "absolute" file path or a "relative" file path. See `?file.path()` and `?read_ndr()` for more details. The line-list must be exactly as downloaded from the NDR.

-   `type` - to specify the type of line-list that you are importing. The options are `treatment`, `recency` and `hts`.

-   `time_stamp` - this is required only when importing "treatment" line-list. It is the reference date for the NDR line-list. It is used to derive the `current_status` of clients based on the last drug pickup date and the number of days of ARV refill. The value for this argument should be specified in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) "yyyy-mm-dd" format. I recommend that you download the NDR line-list on Monday and specify this date as the previous Friday. That way, you are almost certain that all the data available on the NDR were as at the preceding week and upload of data from the new week has not commenced.

-   `cols` - when the value to this argument is absent, `read_ndr()` uses the column specification for NDR column modifications that occurred between October 2020 and March 2021. NDR column specifications before October 2020 are not accounted for by the default function so these will have to be specified manually. See `?vroom::cols()` for more details.

-   `quiet` - when this is set to FALSE (the default) it prints the names of the two columns added. This is available only when the line-list type is "treatment"

```{r, read_ndr, eval = FALSE}

## import file from the computer. This uses the "treatment" example file that comes with the {tidyndr} package.

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

ex_ndr <- read_ndr(file_path, time_stamp = "2021-12-15")

## import file from the computer using a few of the `...` arguments and setting `quiet` to TRUE

ndr_example <- read_ndr(file_path,
                        time_stamp = "2021-12-15",
                        skip = 0,
                        comment = "",
                        quiet = TRUE)

## import recent infection example file

file_path2 <- system.file(
  "extdata",
  "recency_example.csv",
  package = "tidyndr"
)

ex_recency <- read_ndr(file_path2, type = "recency")
```

## Treatment functions

These group of indicators are based on the [PEPFAR MER](https://datim.zendesk.com/hc/en-us/articles/360000084446-MER-Indicator-Reference-Guides) treatment indicators and their supporting indicators. They include:

1.  [`tx_new()`](#tx_new)
2.  [`tx_curr()`](#tx_curr)
3.  [`tx_ml()`](#tx_ml)
4.  [`tx_ml_outcomes()`](#tx_ml_outcomes)
5.  [`tx_rtt()`](#tx_rtt)
6.  [`tx_appointment()`](#tx_appointment)
7.  [`tx_mmd()`](#tx_mmd)

### `tx_new()` {#tx_new}

This generates the line-list of clients who started ART within a period. It can be supplied 5 different arguments with the first one being the only compulsory one:

-   `data` - the NDR line-list imported using the `read_ndr()`.

-   `from` - the start date for generating the requested line-list. This defaults to the beginning of the Fiscal Year. When this is supplied, it must in in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.

-   `to` - the end date for generating the requested line-list. This defaults to all clients who started ART after the `from` date.

-   `states` and `facilities` - the particular state(s) of interest. When this is not supplied,it calculates the new clients for all states and facilities contained in the data.

```{r, tx_new}
## generate tx_new clients between January and June 2021 for all states in the data
tx_new(ndr_example, from = "2021-01-01", to = "2021-06-30")

## generate tx_new for only one state ("Arewa" in the data) for January 2021.

tx_new(ndr_example,
       from = "2021-01-01",
       to = "2021-01-31",
       states = "Arewa")
```

### `tx_curr()` {#tx_curr}

Generates the line-list of all clients who are still active on treatment. It has 4 different parameters with only the first one as the compulsory argument to be specified. The parameters are:

-   `data`, `states` and `facilities` - see `data` for [`tx_new`](#tx_new) above.

-   `status` - the column to be used to determine the `tx_curr`. Can be one of two - 'calculated' or 'default'. The 'calculated' used the derived `current_status` column while the 'default' uses the NDR `current_status_28_days` column.

```{r, tx_curr}
## generate current clients using the calculated `current_status` column
tx_curr(ndr_example)

## generate current clients using the default `current_status_28_days` column
tx_curr(ndr_example,
        status = "default")
```

### `tx_ml()` {#tx_ml}

This generates the line-list of clients who were active at the beginning of the reference date and have now become inactive at the `to` date specified. The default is to generate the line-list of all clients who became inactive in the current Fiscal Year (i.e. were active at the beginning of FY22 but have become inactive at the end of December 2021). It accepts 5 arguments listed below:

-   `data`, `from`, `to`, `states`, `facilities` - see [`tx_new`](#tx_new) documentation above.

```{r, tx_ml, eval = FALSE}
## generate the line-list of clients who were active at the beginning of October 2020 
## (beginning of FY21) but became inactive at the end of December 2020.
tx_ml(new_data = ndr_example,
      from = "2021-10-01",
      to = "2021-12-31")

## if data from two periods are available, you can supply these to determine the `tx_ml"

file_path <- "https://raw.githubusercontent.com/stephenbalogun/example_files/main/ndr_example.csv"
ndr_old <- read_ndr(file_path, time_stamp = "2021-02-15")
ndr_new <- ndr_example
tx_ml(old_data = ndr_old,
      new_data = ndr_new)

## generate the line-list of clients who have become inactive for "Arewa" and "Abaji" 
## since the beginning of October 2021.
tx_ml(ndr_example,
      states = c("Abaji", "Arewa"), from = "2021-10-01")
```

### `tx_ml_outcomes` {#tx_ml_outcomes}

For the inactive clients generated, you might be interested in subsetting those with specific final outcomes of interest. Currently, the NDR recognizes only two final outcomes ("dead" and "transferred out"). These are the ones that can be subset using the `tx_ml_outcomes()` function. This function takes only two argument:

-   `data` - see `data` under [`tx_new()`](#tx_new) above.

-   `outcome` - one of "dead", "transfer out" (or "transferred out").

```{r, tx_ml_outcomes, eval = FALSE}
## generate the line-list of all clients who became inactive this Fiscal Year
ml_example <- tx_ml(ndr_example)

## subset inactive clients who were transferred out
tx_ml_outcomes(ml_example, outcome = "transferred out")
```

### `tx_rtt` {#tx_rtt}

You can filter for clients who were previously inactive but have returned to treatment and are still active at the end of the period of interest. This is the only function where you will be needing two different sets of data - the first data contains the inactive clients while the second data is where their change in status will be checked. The acceptable arguments to `tx_rtt` include:

-   `old_data` - the dataset including the list of inactive clients.

-   `new_data` - a more recent dataset where change in ART status will be evaluated.

-   `states`, and `facilities` - see [`tx_new`](#tx_new) above.

-   `status` - see [`tx_curr`](#tx_curr) above.

```{r, tx_rtt, eval = FALSE}
## location of the old line-list that contains the list of inactive clients
file_path <- "https://raw.githubusercontent.com/stephenbalogun/example_files/main/ndr_example.csv"

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

new_data <- ndr_example 
tx_rtt(old_data, new_data)
```

### `tx_appointment` {#tx_appointment}

Sometimes, you are interested in knowing the number of **Active** clients who are due for medication refill/drug pick up within a period of time. This can help you to plan for the visits, forecast medication appointments and also identify active clients who have missed their appointment. The `tx_appointment()` is one of the supporting treatment indicators that helps in this regard. It takes 6 arguments viz:

-   `data`, `from`, `to`, `states` and `facilities` - kindly see [`tx_new()`](#tx_new) documentation above.

-   `status` - please refer to the previous documentation for [`tx_curr()`](#tx_curr).

```{r, tx_appt}
## generate list of clients with medication appointment in Q2 of FY21
q2_appt <- tx_appointment(ndr_example,
              from = "2022-01-01",
              to = "2022-03-31")

## print the number of clients with appointments in Q2
nrow(q2_appt)
```

### `tx_mmd` {#tx_mmd}

Knowing the number of months of medications dispensed during the last medication refill allows you to calculate the number of **active** clients who are on MMD (Multi-month Dispensing), i.e. clients who were given between 3 months and 6 months medication during the last clinic visit. You might also be interested in know the details of clients who did not have MMD, or who had more than 6 months medication refill (some of which might be due to data entry errors). The arguments that can be supplied to this function include:

-   `data`, `states`, and `facilities` - see [`tx_new()`](#tx_new) above.

-   `status` - see [`tx_curr()`](#tx_curr) documentation above.

-   `months`- the number of months of ARV medications dispensed during the last clinic visit. The default filters active clients who had between 3 and 6 months of ARV but you can change this to generate the list of clients who had more than 6 months medications dispensed for example.

```{r, tx_mmd}
tx_mmd(ndr_example)

## filter clients who had more than 6 months of ARV
tx_mmd(ndr_example,
       months = c(7, Inf))

## list of clients who had either more than 6 months, or < 3 months medications dispensed
tx_mmd(ndr_example,
       months = c(1, 2, 7, Inf))
```

## Viral Load Indicators

The viral load group of indicators allows you to be able to generate the list of clients who are eligible for viral load; have a viral load result within the last one year (for adults of 20 years and above) or 6 months (for pediatrics and adolescents); and are virally suppressed. These indicators include:

1.  [`tx_vl_eligible()`](#tx_vl_eligible)

2.  [`tx_pvls_den()`](#tx_pvls_den)

3.  [`tx_pvls_num()`](#tx_pvls_num)

4.  [`tx_vl_unsuppressed()`](#tx_vl_suppressed)

### `tx_vl_eligible` {#tx_vl_eligible}

Two groups of clients are eligible for routine viral load test - clients who have been on ARV medication for at least 6 months and have not had a viral load result, and clients whose last viral load result is more than 12 months ago (for adults) and more than 6 months ago (for pediatrics and adolescents). `tx_vl_eligible()` generates this line-list using a combination of the 6 arguments below that can be provided:

-   `data`, `states` and `facilities` - see [`tx_new`](#tx_new) documentation above.

-   `status` - please see the documentation for `status` under [`tx_curr`](#tx_curr) above.

-   `ref` - the reference date for when the eligibility period should be determined. This should be provided in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. When this is not supplied, it assumes you would like to know the clients who are eligible for viral load test as at the day of analysis.

-   `sample` - one of two (TRUE or FALSE) to determine if only those who are eligible for viral load sample collection within the period of interest (sample = TRUE) or those eligible for viral load test results (sample = FALSE).

```{r, tx_vl_eligible}
## list of clients who are eligible for VL sample collection by the end of March 2022
tx_vl_eligible(ndr_example,
               ref = "2022-03-31",
               sample = TRUE)

## filter clients who are eligible for VL test (result) by 31st of December 2021
tx_vl_eligible(ndr_example,
               ref = "2021-12-31")
```

### `tx_pvls_den` {#tx_pvls_den}

This determines clients who have a documented viral load result and are not due for a repeat viral load test. It helps you to know what the viral load coverage (the number of those who have a VL result / the number of those eligible [when sample is set to FALSE]). It accepts arguments all the arguments that can be supplied to [`tx_vl_eligible`](#tx_vl_eligible) above.

```{r, tx_pvls_den}
## determine clients whose viral load result is within the last 1 year for adults (>= 20 years) 
## and 6 months for paediatrics and adolescents
tx_pvls_den(ndr_example)

## List of clients who will not be due for a repeat VL test by the end of September 2021
tx_pvls_den(ndr_example,
            ref = "2021-09-30")
```

### `tx_pvls_num` {#tx_pvls_num}

This determines the number of clients whose viral load test results are below a particular limit among those with a documented viral load result, thus are said to be virally suppressed. It helps you to know how many clients are doing well on their current medication. It accepts the following arguments:

-   `data`, `ref`, `states`, `facilities` and `status` - kindly see the documentation for [`tx_vl_eligible()`](#tx_vl_eligible) above.

-   `n` - the reference at which viral load values below are said to be suppressed. The default is 1000.

```{r, tx_pvls_num}
## clients whose last viral load result is within the last 1 year for adults (>= 20 years) 
## and 6 months for paediatrics and adolescents, and are virally suppressed
tx_pvls_num(ndr_example)

## generate the list of clients whose viral load result is less than 50
tx_pvls_num(ndr_example,
            n = 50)
```

### `tx_vl_unsuppressed`

This determines the number of clients whose viral load test results are above a particular limit among those with a documented viral load result. It accepts the following arguments:

-   `data`, `ref`, `states`, `facilities` and `status` - kindly see the documentation for [`tx_vl_eligible()`](#tx_vl_eligible) above.

-   `n` - the reference at which viral load values equal to or above are said to be unsuppressed. The default is 1000.

```{r, tx_vl_unsuppressed}
## clients whose last viral load result is within the last 1 year for adults (>= 20 years) 
## and 6 months for paediatrics and adolescents but were unsuppressed
tx_vl_unsuppressed(ndr_example)
```

## Summary Indicators

Summary indicators provide aggregates for a particular indicator of interest. {tidyndr} provides two aggregate functions. These are:\
1. [`summarise_ndr()`](#summrise_ndr)

2.  [`disaggregate()`](#disaggregate)

### `summarise_ndr` {#summarise_ndr}

All the previous functions generates patient-level line-lists. You will most often be interested in a tabular summary of the information provided. This is the work of `summarise_ndr()` (and its partner `summarize_ndr()`). It takes all the line-lists that you might have generated, and display a summary table with one column for each of your generated line-lists. `summarise_ndr()` accepts three arguments:

-   `...` - these are the names assigned to each of the line-lists that you have generated.

-   `level` - specifies the level at which the summary should be performed. The options are "facility", "lga", "state" or "country" ("ip"). The default level is "state".

-   `names` - the names to be assigned to each of the summary columns created. See `?summarise_ndr` for more details.

```{r, summarise_ndr}
curr <- tx_curr(ndr_example) # generate active clients and assign to "curr"

new <- tx_new(ndr_example, from = "2021-10-01", to = "2021-12-31") # generate TX_NEW for the FY and assign to "new"

summarise_ndr(curr, new, level = "state", names = c("curr", "tx_new")) # when the `names` argument is not supplied, the data names are used
```

### `disaggregate` {#disaggregate}

A very powerful function that allows you to summarise your generated line-list disaggregated based on a particular variable. The disaggregation options currently available are "current_age", "sex", "pregnancy_status", "art_duration", "months_dispensed", and "age_sex". It accepts 4 arguments:

-   `data` - see [`tx_new()`](#tx_new) documentation above.

-   `by`, `level` and `pivot_wide` - see the documentation for [`summarise_ndr()`](#summarise_ndr) above.

```{r, disaggregate, eval = FALSE}
## generate list of inactive clients
inactives <- tx_ml(new_data = ndr_example, from = "2021-01-01", to = "2021-03-31")

## disaggregate inactive clients by gender at state level
disaggregate(inactives,
             by = "sex")

## disaggregate inactive clients by "age group" at country level
disaggregate(inactives,
             by = "current_age",
             level = "country",
             pivot_wide = FALSE)

```
