Validate or load a laboratory toxicity grading table

Returns an admiralease_grading object in one of two styles.

grading_table(x)

Arguments

x: One of: a criteria set name ("ctcv5", "ctcv4", "ctcv5_uscv", "daids"); a data frame in either style above; or an existing admiralease_grading object (returned unchanged).

Value

An admiralease_grading object: a tibble::tibble with a print() method and a style attribute, either "criteria" or "threshold".

Style 1: published criteria (the default)

grading_table("ctcv5") loads real published laboratory toxicity criteria shipped as data by admiral. These are the tables grade_lab() hands to admiral::derive_var_atoxgr_dir(); this package does not re-implement the grading logic. Accepted names:

"ctcv5": admiral::atoxgr_criteria_ctcv5 - NCI-CTCAE v5 lab criteria, SI units. The default.
"ctcv4": admiral::atoxgr_criteria_ctcv4 - NCI-CTCAE v4.03 lab criteria, SI units.
"ctcv5_uscv": admiral::atoxgr_criteria_ctcv5_uscv - NCI-CTCAE v5 lab criteria expressed in US conventional units (g/dL, mg/dL, 10^3/uL).
"daids": admiral::atoxgr_criteria_daids - DAIDS v2.1 lab criteria. Note these use DAIDS term names ("ALT, High"), not CTCAE term names, so ATOXDSCL/ATOXDSCH must be populated with DAIDS terms.

A data frame with the admiral criteria columns (TERM, DIRECTION, GRADE_CRITERIA_CODE, ...) is also accepted, so a sponsor-amended copy of a published table works unchanged.

What these tables do and do not cover

They are the laboratory subset of the criteria only. ctcv5 carries 40 terms across 3 SOCs (Blood and lymphatic system disorders, Investigations, Metabolism and nutrition disorders). That is not the full NCI-CTCAE v5 term set - non-laboratory CTCAE terms (nausea, fatigue, rash, ...) are not present and cannot be graded here. A term that is not in the table returns NA, never "0".

Style 2: a threshold table supplied as data

A data frame of plain numeric cut-points, for sponsor criteria that are not one of the published sets. Required columns:

PARAMCD: Parameter code, matched against param_var in the ADaM data.
DIRECTION: "HIGH" or "LOW" (case-insensitive). The direction of the toxicity, i.e. whether the abnormality is a high or a low value.
GRADE: Integer toxicity grade, 1 to 4.
THRESHOLD: Numeric boundary for that grade, in the same units as the analysis value being graded.

An optional DESCRIPTION column is carried through untouched and printed.

A threshold table carries no toxicity standard of its own: it grades exactly what the user typed into it. The table shipped at system.file("extdata", "demo_grading_table.csv", package = "admiralease") is a demonstration fixture in pharmaverseadam units. It is not NCI-CTCAE and must never be used to grade a study. Use "ctcv5" for that.

Threshold semantics

A value qualifies for a grade when it lies strictly beyond the threshold: AVAL > THRESHOLD for DIRECTION == "HIGH" and AVAL < THRESHOLD for DIRECTION == "LOW". A value exactly on a threshold does not qualify. The grade assigned is the highest grade whose threshold is beyond. Thresholds must therefore be monotone within a parameter and direction (increasing for HIGH, decreasing for LOW); this is checked and is the single most common transcription error in a hand-typed grading table.

Threshold tables written relative to the reference range (> 3 x ULN) are supported by grading a ratio: add RATIO = AVAL / ANRHI to the ADaM data and call grade_lab() with value_var = "RATIO" and a table of ratio thresholds.

Examples

# Published NCI-CTCAE v5 laboratory criteria (lab terms only, not all of CTCAE)
grading_table("ctcv5")
#> 
#> ── Laboratory toxicity criteria (ctcv5) ──
#> 
#> ℹ 40 terms, 40 criteria, 3 SOCs.
#> ! Laboratory terms only - not the full CTCAE term set. Non-lab terms are not graded.
#> # A tibble: 40 × 5
#>    SOC                                  TERM      DIRECTION UNIT_CHECK VAR_CHECK
#>    <chr>                                <chr>     <chr>     <chr>      <chr>    
#>  1 Blood and lymphatic system disorders Anemia    L         g/L        AVAL, AN…
#>  2 Blood and lymphatic system disorders Leukocyt… H         10^9/L     AVAL     
#>  3 Investigations                       Activate… H         NA         AVAL, AN…
#>  4 Investigations                       Alanine … H         NA         AVAL, AN…
#>  5 Investigations                       Alkaline… H         NA         AVAL, AN…
#>  6 Investigations                       Aspartat… H         NA         AVAL, AN…
#>  7 Investigations                       Blood bi… H         NA         AVAL, AN…
#>  8 Investigations                       Blood la… H         NA         AVAL, AN…
#>  9 Investigations                       CD4 lymp… L         10^9/L     AVAL, AN…
#> 10 Investigations                       Choleste… H         mmol/L     AVAL, AN…
#> # ℹ 30 more rows

# A threshold table supplied as data. This fixture is a DEMO in
# pharmaverseadam units - it is not NCI-CTCAE and must not grade a study.
demo <- utils::read.csv(
  system.file("extdata", "demo_grading_table.csv", package = "admiralease")
)
grading_table(demo)
#> 
#> ── Toxicity grading table (user-supplied thresholds) ──
#> 
#> ℹ 11 parameters, 60 thresholds, directions: HIGH and LOW.
#> ! No published toxicity standard is implied by a threshold table.
#> # A tibble: 60 × 5
#>    PARAMCD DIRECTION GRADE THRESHOLD DESCRIPTION
#>    <chr>   <chr>     <int>     <dbl> <chr>      
#>  1 ALT     HIGH          1      34   > ULN      
#>  2 ALT     HIGH          2     102   > 3 x ULN  
#>  3 ALT     HIGH          3     170   > 5 x ULN  
#>  4 ALT     HIGH          4     680   > 20 x ULN 
#>  5 AST     HIGH          1      34   > ULN      
#>  6 AST     HIGH          2     102   > 3 x ULN  
#>  7 AST     HIGH          3     170   > 5 x ULN  
#>  8 AST     HIGH          4     680   > 20 x ULN 
#>  9 BILI    HIGH          1      21   > ULN      
#> 10 BILI    HIGH          2      31.5 > 1.5 x ULN
#> # ℹ 50 more rows