Author: Will Beasley and Peter Higgins
Date: 2022-08-12

# NIH Enrollment Tables in HTML

#### Will Beasley and Peter Higgins

#### 2022-08-12

## 0.1 Install `codified` Package

First, install the `codified` package if necessary, and then load it into memory.

    # if( !requireNamespace("codified", quietly = TRUE) )
    #   remotes::install_github(repo = "OuhscBbmc/codified")

    library(codified)

## 0.2 Local Data Source

### 0.2.1 Establish Datasets

    path <- system.file("misc/example-data-1.csv", package = "codified")
    col_types <- readr::cols_only(
      record_id = readr::col_integer(),
      name_last = readr::col_character(),
      dob       = readr::col_date(format = ""),
      gender    = readr::col_integer(),
      race      = readr::col_integer(),
      ethnicity = readr::col_integer()
    )
    ds <- readr::read_csv(path, col_types = col_types) |>
      dplyr::mutate(
        gender     = as.character(gender),
        race       = as.character(race),
        ethnicity  = as.character(ethnicity)
      )
    ds |>
      head(10) |>
      knitr::kable(caption = "Observed Dataset (first ten rows)")

Observed Dataset (first ten rows)
record_id | name_last | dob | ethnicity | race | gender
--- | --- | --- | --- | --- | ---
1 | Cornel | 1991-05-13 | 1 | 4 | 0
2 | Wojdyla | 1931-10-14 | 1 | 4 | 0
3 | Stunkard | 1964-09-15 | 1 | 3 | 1
4 | Cimochowski | 1969-05-03 | 1 | 4 | 1
5 | Woodland | 1969-11-22 | 1 | 4 | 0
6 | Pistoia | 1943-08-26 | 1 | 4 | 1
7 | Ahlquist | 1944-01-22 | 1 | 4 | 0
8 | Ashlin | 1931-04-14 | 1 | 4 | 1
9 | Djokovic | 1962-07-07 | 1 | 1 | 1
10 | Mosses | 1978-06-20 | 1 | 3 | 0

    ds_lu_gender <- tibble::tribble(
      ~input,   ~displayed            ,
      "0"   ,  "Female"               ,
      "1"   ,  "Male"                 ,
      "U"   ,  "Unknown/Not Reported"
    )
    knitr::kable(ds_lu_gender, caption = "Gender Mapping")

Gender Mapping
input | displayed
--- | ---
0 | Female
1 | Male
U | Unknown/Not Reported

    ds_lu_race <- tibble::tribble(
      ~input , ~displayed                                   ,
      "1"    , "American Indian/Alaska Native"              ,
      "2"    , "Asian"                                      ,
      "3"    , "Native Hawaiian or Other Pacific Islander"  ,
      "4"    , "Black or African American"                  ,
      "5"    , "White"                                      ,
      "M"    , "More than One Race"                         ,
      "6"    , "Unknown or Not Reported"
    )
    knitr::kable(ds_lu_race, caption = "Race Mapping")

Race Mapping
input | displayed
--- | ---
1 | American Indian/Alaska Native
2 | Asian
3 | Native Hawaiian or Other Pacific Islander
4 | Black or African American
5 | White
M | More than One Race
6 | Unknown or Not Reported

    ds_lu_ethnicity <- tibble::tribble(
      ~input,   ~displayed                      ,
      "2"   ,  "Not Hispanic or Latino"         ,
      "1"   ,  "Hispanic or Latino"             ,
      "0"   ,  "Unknown/Not Reported Ethnicity"
    )
    knitr::kable(ds_lu_ethnicity, caption = "Ethnicity Mapping")

Ethnicity Mapping
input | displayed
--- | ---
2 | Not Hispanic or Latino
1 | Hispanic or Latino
0 | Unknown/Not Reported Ethnicity

### 0.2.2 Apply Map to Observed Dataset

    ds_summary_long <- codified::table_nih_enrollment(
      d              = ds,
      d_lu_gender    = ds_lu_gender,
      d_lu_race      = ds_lu_race,
      d_lu_ethnicity = ds_lu_ethnicity
    )

    knitr::kable(ds_summary_long, caption = "Counts of Each Subgroup")

Counts of Each Subgroup
gender | race | ethnicity | n
--- | --- | --- | ---
Female | American Indian/Alaska Native | Not Hispanic or Latino | 1
Female | American Indian/Alaska Native | Hispanic or Latino | 8
Female | American Indian/Alaska Native | Unknown/Not Reported Ethnicity | 0
Female | Asian | Not Hispanic or Latino | 0
Female | Asian | Hispanic or Latino | 0
Female | Asian | Unknown/Not Reported Ethnicity | 0
Female | Native Hawaiian or Other Pacific Islander | Not Hispanic or Latino | 1
Female | Native Hawaiian or Other Pacific Islander | Hispanic or Latino | 28
Female | Native Hawaiian or Other Pacific Islander | Unknown/Not Reported Ethnicity | 3
Female | Black or African American | Not Hispanic or Latino | 1
Female | Black or African American | Hispanic or Latino | 172
Female | Black or African American | Unknown/Not Reported Ethnicity | 14
Female | White | Not Hispanic or Latino | 1
Female | White | Hispanic or Latino | 22
Female | White | Unknown/Not Reported Ethnicity | 2
Female | More than One Race | Not Hispanic or Latino | 0
Female | More than One Race | Hispanic or Latino | 0
Female | More than One Race | Unknown/Not Reported Ethnicity | 0
Female | Unknown or Not Reported | Not Hispanic or Latino | 0
Female | Unknown or Not Reported | Hispanic or Latino | 7
Female | Unknown or Not Reported | Unknown/Not Reported Ethnicity | 0
Male | American Indian/Alaska Native | Not Hispanic or Latino | 0
Male | American Indian/Alaska Native | Hispanic or Latino | 10
Male | American Indian/Alaska Native | Unknown/Not Reported Ethnicity | 0
Male | Asian | Not Hispanic or Latino | 0
Male | Asian | Hispanic or Latino | 0
Male | Asian | Unknown/Not Reported Ethnicity | 0
Male | Native Hawaiian or Other Pacific Islander | Not Hispanic or Latino | 1
Male | Native Hawaiian or Other Pacific Islander | Hispanic or Latino | 22
Male | Native Hawaiian or Other Pacific Islander | Unknown/Not Reported Ethnicity | 1
Male | Black or African American | Not Hispanic or Latino | 5
Male | Black or African American | Hispanic or Latino | 154
Male | Black or African American | Unknown/Not Reported Ethnicity | 6
Male | White | Not Hispanic or Latino | 0
Male | White | Hispanic or Latino | 33
Male | White | Unknown/Not Reported Ethnicity | 1
Male | More than One Race | Not Hispanic or Latino | 0
Male | More than One Race | Hispanic or Latino | 0
Male | More than One Race | Unknown/Not Reported Ethnicity | 0
Male | Unknown or Not Reported | Not Hispanic or Latino | 0
Male | Unknown or Not Reported | Hispanic or Latino | 7
Male | Unknown or Not Reported | Unknown/Not Reported Ethnicity | 0
Unknown/Not Reported | American Indian/Alaska Native | Not Hispanic or Latino | 0
Unknown/Not Reported | American Indian/Alaska Native | Hispanic or Latino | 0
Unknown/Not Reported | American Indian/Alaska Native | Unknown/Not Reported Ethnicity | 0
Unknown/Not Reported | Asian | Not Hispanic or Latino | 0
Unknown/Not Reported | Asian | Hispanic or Latino | 0
Unknown/Not Reported | Asian | Unknown/Not Reported Ethnicity | 0
Unknown/Not Reported | Native Hawaiian or Other Pacific Islander | Not Hispanic or Latino | 0
Unknown/Not Reported | Native Hawaiian or Other Pacific Islander | Hispanic or Latino | 0
Unknown/Not Reported | Native Hawaiian or Other Pacific Islander | Unknown/Not Reported Ethnicity | 0
Unknown/Not Reported | Black or African American | Not Hispanic or Latino | 0
Unknown/Not Reported | Black or African American | Hispanic or Latino | 0
Unknown/Not Reported | Black or African American | Unknown/Not Reported Ethnicity | 0
Unknown/Not Reported | White | Not Hispanic or Latino | 0
Unknown/Not Reported | White | Hispanic or Latino | 0
Unknown/Not Reported | White | Unknown/Not Reported Ethnicity | 0
Unknown/Not Reported | More than One Race | Not Hispanic or Latino | 0
Unknown/Not Reported | More than One Race | Hispanic or Latino | 0
Unknown/Not Reported | More than One Race | Unknown/Not Reported Ethnicity | 0
Unknown/Not Reported | Unknown or Not Reported | Not Hispanic or Latino | 0
Unknown/Not Reported | Unknown or Not Reported | Hispanic or Latino | 0
Unknown/Not Reported | Unknown or Not Reported | Unknown/Not Reported Ethnicity | 0

### 0.2.3 Conform to NIH Cosmetics

    codified::table_nih_enrollment_pretty(
      d              = ds,
      d_lu_gender    = ds_lu_gender,
      d_lu_race      = ds_lu_race,
      d_lu_ethnicity = ds_lu_ethnicity
    )

| Ethnic Categories
--- | ---
| Not Hispanic or Latino | Hispanic or Latino | Unknown/Not Reported Ethnicity
Racial Categories | Female | Male | Unknown/ Not Reported | Female | Male | Unknown/ Not Reported | Female | Male | Unknown/ Not Reported
American Indian/Alaska Native | 1 | 0 | 0 | 8 | 10 | 0 | 0 | 0 | 0
Asian | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Native Hawaiian or Other Pacific Islander | 1 | 1 | 0 | 28 | 22 | 0 | 3 | 1 | 0
Black or African American | 1 | 5 | 0 | 172 | 154 | 0 | 14 | 6 | 0
White | 1 | 0 | 0 | 22 | 33 | 0 | 2 | 1 | 0
More than One Race | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Unknown or Not Reported | 0 | 0 | 0 | 7 | 7 | 0 | 0 | 0 | 0

## 0.3 REDCap Data Source

A hosted (fake) clinical trial dataset demonstrates how to extract demographic data from REDCap and then present the demographic data in the NIH Inclusion Enrollment Report format.

### 0.3.1 Establish Datasets

First, install the `REDCapR` package if necessary, and then load it into memory.

    # if( !requireNamespace("REDCapR", quietly = TRUE) )
    #   remotes::install_github("OuhscBbmc/REDCapR")

    library(REDCapR)

Next, download the data from the REDCap database into the `ds_2` data.frame. If you’re running the most recent version of REDCapR (available on GitHub), the code will be:

    ds_2 <- REDCapR::redcap_read(
      redcap_uri = "https://bbmc.ouhsc.edu/redcap/api/",  # URL of REDCap Server.
      token      = "F304DEC3793FECC3B6DEEFF66302CAD3",    # User-specific token/password.
      guess_type = FALSE                                  # Keep all variables as strings/characters.
    )$data

However CRAN policy understandably discourages vignettes from using “Internet resources” so this vignette mimics the code above with this local call. On your own computer, feel free to call that demonstration REDCap project.

    ds_2 <-
      readr::read_csv(
        file      = system.file("misc/example-data-2.csv", package = "codified"),
        col_types = readr::cols(.default = readr::col_character())
      )

### 0.3.2 Conform to NIH Cosmetics

Now, convert these demographic data into a properly formatted NIH enrollment table. Pass the `ds_lu_gender`, `ds_lu_race`, and `ds_lu_ethnicity` metadata, which was defined above. As a reminder, these translate values like `1` to `Male` and `3` to `Native Hawaiian or Other Pacific Islander`.

    table_nih_enrollment_pretty(
      d               = ds_2,
      d_lu_gender     = ds_lu_gender,
      d_lu_race       = ds_lu_race,
      d_lu_ethnicity  = ds_lu_ethnicity
    )

| Ethnic Categories
--- | ---
| Not Hispanic or Latino | Hispanic or Latino | Unknown/Not Reported Ethnicity
Racial Categories | Female | Male | Unknown/ Not Reported | Female | Male | Unknown/ Not Reported | Female | Male | Unknown/ Not Reported
American Indian/Alaska Native | 1 | 0 | 0 | 8 | 10 | 0 | 0 | 0 | 0
Asian | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Native Hawaiian or Other Pacific Islander | 1 | 1 | 0 | 28 | 22 | 0 | 3 | 1 | 0
Black or African American | 1 | 5 | 0 | 172 | 154 | 0 | 14 | 6 | 0
White | 1 | 0 | 0 | 22 | 33 | 0 | 2 | 1 | 0
More than One Race | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Unknown or Not Reported | 0 | 0 | 0 | 7 | 7 | 0 | 0 | 0 | 0

## 0.4 Collapsing Levels

Many observed datasets may collect race with a different set of levels. For instance in `ds_3`, the `American Indian` level is separate from the `Alaska Native` level. In the first and second rows in the metadata below, the two levels are effectively combined into the`American Indian/Alaska Native` level, so it complies with the format of the NIH Enrollment table.

    ds_lu_race_3 <- tibble::tribble(
      ~input                      , ~displayed                                  ,
      "American Indian"           , "American Indian/Alaska Native"             , # Combine w/ Alaska Native
      "Alaska Native"             , "American Indian/Alaska Native"             , # Combine w/ American Indian
      "Asian"                     , "Asian"                                     ,
      "Native Hawaiian"           , "Native Hawaiian or Other Pacific Islander" , # Combine w/ Pacific Islanders
      "Pacific Islander"          , "Native Hawaiian or Other Pacific Islander" , # Combine w/ Hawaiian
      "Black or African American" , "Black or African American"                 ,
      "White"                     , "White"                                     ,
      "More than One Race"        , "More than One Race"                        ,
      "Unknown or Not Reported"   , "Unknown or Not Reported"
    )

    ds_3 <- tibble::tribble(
      ~subject_id,   ~gender  , ~race            ,  ~ethnicity                 ,
               1L,   "Female" , "American Indian",  "Not Hispanic or Latino"   ,
               2L,   "Male"   , "American Indian",  "Not Hispanic or Latino"   ,
               3L,   "Male"   , "American Indian",  "Not Hispanic or Latino"   ,
               4L,   "Female" , "Alaska Native"  ,  "Not Hispanic or Latino"   ,
               5L,   "Male"   , "Alaska Native"  ,  "Not Hispanic or Latino"   ,
               6L,   "Male"   , "Alaska Native"  ,  "Not Hispanic or Latino"   ,
               7L,   "Male"   , "White"          ,  "Not Hispanic or Latino"   ,
               8L,   "Male"   , "White"          ,  "Not Hispanic or Latino"
    )

    table_nih_enrollment_pretty(
      d               = ds_3,
      d_lu_race       = ds_lu_race_3
    )

| Ethnic Categories
--- | ---
| Not Hispanic or Latino | Hispanic or Latino | Unknown/Not Reported Ethnicity
Racial Categories | Female | Male | Unknown/ Not Reported | Female | Male | Unknown/ Not Reported | Female | Male | Unknown/ Not Reported
American Indian/Alaska Native | 2 | 4 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Asian | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Native Hawaiian or Other Pacific Islander | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Black or African American | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
White | 0 | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 0
More than One Race | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0
Unknown or Not Reported | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0

## 0.5 Feedback Welcome

Please share your opinions with us by creating an issue at https://github.com/OuhscBbmc/codified/issues.

### 0.5.1 Upcoming Features

1. Create tables in a fresh docx file with flextable. Issue #5
2. Create tables in a fresh pdf file Issue #5.
3. Populate tables in an existing pdf file with staplr?
4. The ‘totals’ column & row are calculated. The NIH form does this already, so this is mostly for the purpose of checking. Issue #4.
5. Allow variable names to change (e.g., `Gender` instead of `gender`). Issue #3.
6. pkgdown site, like REDCapR.

### 0.5.2 Group discussion

- Any holes in the functionality or concept?
- What else (e.g., features or explanation) do you think would be helpful?
- Are people able to run this package? Is the vignette clear?
- What other standardized tables/graphs/whatever could this be applied to?
  - IRB continuation tables?
  - Graphs?