Derive Lab Toxicity Grade 0 - 4 — derive_var_atoxgr

Derives a character lab grade based on severity/toxicity criteria.

Usage

derive_var_atoxgr_dir(
  dataset,
  new_var,
  tox_description_var,
  meta_criteria,
  criteria_direction,
  get_unit_expr,
  signif_dig = get_admiral_option("signif_digits")
)

Arguments

dataset

Input dataset

The variables specified by the tox_description_var argument are expected to be in the dataset.

new_var

Name of the character grade variable to create, for example, ATOXGRH or ATOXGRL.

tox_description_var

Variable containing the description of the grading criteria. For example: "Anemia" or "INR Increased".

meta_criteria

Metadata data set holding the criteria (normally a case statement)

Permitted Values: atoxgr_criteria_ctcv4, atoxgr_criteria_ctcv5, atoxgr_criteria_daids

atoxgr_criteria_ctcv4 implements Common Terminology Criteria for Adverse Events (CTCAE) v4.0
atoxgr_criteria_ctcv5 implements Common Terminology Criteria for Adverse Events (CTCAE) v5.0
atoxgr_criteria_daids implements Division of AIDS (DAIDS) Table for Grading the Severity of Adult and Pediatric Adverse Events

The metadata should have the following variables:
TERM: variable to hold the term describing the criteria applied to a particular lab test, eg. "Anemia" or "INR Increased". Note: the variable is case insensitive.
DIRECTION: variable to hold the direction of the abnormality of a particular lab test value. "L" is for LOW values, "H" is for HIGH values. Note: the variable is case insensitive.
SI_UNIT_CHECK: variable to hold unit of particular lab test. Used to check against input data if criteria is based on absolute values.
VAR_CHECK: variable to hold comma separated list of variables used in criteria. Used to check against input data that variables exist.
GRADE_CRITERIA_CODE: variable to hold code that creates grade based on defined criteria.
FILTER: Required only for DAIDS grading, specifies admiral code to filter the lab data based on a subset of subjects (e.g. AGE > 18 YEARS)

criteria_direction

Direction (L= Low, H = High) of toxicity grade.

Permitted Values: "L", "H"

get_unit_expr

An expression providing the unit of the parameter

The result is used to check the units of the input parameters. Compared with SI_UNIT_CHECK in metadata (see meta_criteria parameter).

Permitted Values: A variable containing unit from the input dataset, or a function call, for example, get_unit_expr = extract_unit(PARAM).

signif_dig

Number of significant digits to use when comparing a lab value against another value.

Significant digits used to avoid floating point discrepancies when comparing numeric values. See blog: How admiral handles floating points

Value

The input dataset with the character variable added

Details

new_var is derived with values NA, "0", "1", "2", "3", "4", where "4" is the most severe grade

"4" is where the lab value satisfies the criteria for grade 4.
"3" is where the lab value satisfies the criteria for grade 3.
"2" is where the lab value satisfies the criteria for grade 2.
"1" is where the lab value satisfies the criteria for grade 1.
"0" is where a grade can be derived and is not grade "1", "2", "3" or "4".
NA is where a grade cannot be derived.

Examples

library(tibble)

data <- tribble(
  ~ATOXDSCL,                    ~AVAL, ~ANRLO, ~ANRHI, ~PARAM,
  "Hypoglycemia",               119,   4,      7,      "Glucose (mmol/L)",
  "Lymphocyte count decreased", 0.7,   1,      4,      "Lymphocytes Abs (10^9/L)",
  "Anemia",                     129,   120,    180,    "Hemoglobin (g/L)",
  "White blood cell decreased", 10,    5,      20,     "White blood cell (10^9/L)",
  "White blood cell decreased", 15,    5,      20,     "White blood cell (10^9/L)",
  "Anemia",                     140,   120,    180,    "Hemoglobin (g/L)"
)

derive_var_atoxgr_dir(data,
  new_var = ATOXGRL,
  tox_description_var = ATOXDSCL,
  meta_criteria = atoxgr_criteria_ctcv5,
  criteria_direction = "L",
  get_unit_expr = extract_unit(PARAM)
)
#> # A tibble: 6 × 6
#>   ATOXDSCL                    AVAL ANRLO ANRHI PARAM                     ATOXGRL
#>   <chr>                      <dbl> <dbl> <dbl> <chr>                     <chr>  
#> 1 Anemia                     129     120   180 Hemoglobin (g/L)          0      
#> 2 Anemia                     140     120   180 Hemoglobin (g/L)          0      
#> 3 Hypoglycemia               119       4     7 Glucose (mmol/L)          0      
#> 4 Lymphocyte count decreased   0.7     1     4 Lymphocytes Abs (10^9/L)  2      
#> 5 White blood cell decreased  10       5    20 White blood cell (10^9/L) 0      
#> 6 White blood cell decreased  15       5    20 White blood cell (10^9/L) 0      

data <- tribble(
  ~ATOXDSCH,                     ~AVAL,  ~ANRLO,   ~ANRHI, ~PARAM,
  "CPK increased",               129,    0,        30,     "Creatine Kinase (U/L)",
  "Lymphocyte count increased",  4,      1,        4,      "Lymphocytes Abs (10^9/L)",
  "Lymphocyte count increased",  2,      1,        4,      "Lymphocytes Abs (10^9/L)",
  "CPK increased",               140,    120,      180,    "Creatine Kinase (U/L)"
)

derive_var_atoxgr_dir(data,
  new_var = ATOXGRH,
  tox_description_var = ATOXDSCH,
  meta_criteria = atoxgr_criteria_ctcv5,
  criteria_direction = "H",
  get_unit_expr = extract_unit(PARAM)
)
#> # A tibble: 4 × 6
#>   ATOXDSCH                    AVAL ANRLO ANRHI PARAM                    ATOXGRH
#>   <chr>                      <dbl> <dbl> <dbl> <chr>                    <chr>  
#> 1 CPK increased                129     0    30 Creatine Kinase (U/L)    2      
#> 2 CPK increased                140   120   180 Creatine Kinase (U/L)    0      
#> 3 Lymphocyte count increased     4     1     4 Lymphocytes Abs (10^9/L) 0      
#> 4 Lymphocyte count increased     2     1     4 Lymphocytes Abs (10^9/L) 0

Derive Lab Toxicity Grade 0 - 4

Usage

Arguments

Value

Details

See also

Examples