Derive Lab Toxicity Grade 0 - 4

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,
  abnormal_indicator = NULL,
  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"

abnormal_indicator

Value in BNRIND derivation to indicate an abnormal value. Usually "HIGH" for criteria_direction = "H" and "LOW" for criteria_direction = "L".

This is only required when meta_criteria = atoxgr_criteria_ctcv5 and BNRIND is a required variable. Currently for terms "Alanine aminotransferase increased", "Alkaline phosphatase increased", "Aspartate aminotransferase increased", "Blood bilirubin increased" and "GGT increased"

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.

See also

BDS-Findings Functions that returns variable appended to dataset: derive_basetype_records(), derive_var_analysis_ratio(), derive_var_anrind(), derive_var_atoxgr(), derive_var_base(), derive_var_chg(), derive_var_ontrtfl(), derive_var_pchg(), derive_var_shift(), derive_vars_crit_flag()

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