grade_lab.RdAdds ATOXGRL, ATOXGRH and ATOXGR to ADaM lab data. By default it grades
with the NCI-CTCAE v5 laboratory criteria that admiral ships as
data, by calling admiral::derive_var_atoxgr_dir() and
admiral::derive_var_atoxgr(). The toxicity logic is admiral's, not this
package's; what this wrapper adds is the table selection, the up-front check
that every variable the criteria reference is present, a unit expression that
defaults sensibly, and restoration of the input row order
(admiral::derive_var_atoxgr_dir() returns rows regrouped by term, which
silently breaks positional joins).
grade_lab(
adlb,
grading = "ctcv5",
param_var = "PARAMCD",
value_var = "AVAL",
tox_low_var = "ATOXDSCL",
tox_high_var = "ATOXDSCH",
unit_expr = NULL,
high_indicator = "HIGH",
low_indicator = "LOW",
signif_dig = admiral::get_admiral_option("signif_digits")
)ADaM lab data frame (BDS), e.g. ADLB.
Criteria set name ("ctcv5" default, "ctcv4",
"ctcv5_uscv", "daids"), a criteria/threshold data frame, or a
grading_table() object.
Threshold style only: name of the parameter code column in
adlb. Default "PARAMCD".
Threshold style only: name of the analysis value column to
grade. Default "AVAL".
Criteria style only: names of the columns
holding the low- and high-direction criteria term. Defaults "ATOXDSCL"
and "ATOXDSCH".
Criteria style only: a string parsed as the expression
that yields each record's unit, compared against the criteria UNIT_CHECK.
NULL (default) uses "AVALU" when that column exists, otherwise
"admiral::extract_unit(PARAM)".
Criteria style only: the BNRIND values
meaning abnormally high / low at baseline, used by the CTCAE v5 criteria
that grade against BASE. Defaults "HIGH" and "LOW" (CDISC CT).
Criteria style only: significant digits used when comparing
a result against a criterion. Passed to
admiral::derive_var_atoxgr_dir().
A tibble::tibble: adlb in its original row order with the
character columns ATOXGRL, ATOXGRH and ATOXGR added (existing columns
of those names are replaced). A plain data frame, ready to hand back to
admiral, rtables or xportr.
These are laboratory criteria only. "ctcv5" covers 40 terms across 3
SOCs; that is not the full NCI-CTCAE v5 term set, and non-laboratory CTCAE
terms are not covered by this function at all. See grading_table().
grade_lab(adlb) or
grade_lab(adlb, "ctcv4"). Requires tox_low_var / tox_high_var
(ATOXDSCL / ATOXDSCH) to already hold the criteria term for each
record, plus whatever the criteria reference (AVAL, ANRLO, ANRHI,
BASE, BNRIND). This package does not guess terms from PARAMCD -
merge your own PARAMCD-to-term lookup on first, as admiral's ADLB
template does with admiral::derive_vars_merged().
grade_lab(adlb, my_thresholds) with a data frame of
PARAMCD/DIRECTION/GRADE/THRESHOLD. Grades value_var directly
against the numbers in the table; no published standard is implied.
Three character variables are added, matching admiral::derive_var_atoxgr()
and the ADaM lab data in pharmaverseadam:
ATOXGRLLow-direction grade, "0" to "4".
ATOXGRHHigh-direction grade, "0" to "4".
ATOXGRCombined grade. A high toxicity is carried as a
positive grade ("1".."4"); a low toxicity is carried as a
negative grade ("-1".."-4"); no toxicity in either direction is
"0". If both directions grade above 0, the high grade wins.
Missing and ungradeable results stay missing, they never become "0":
a missing analysis value gives NA;
a term (criteria style) or parameter (threshold style) that is not in the
table gives NA;
a result whose unit does not match the criteria UNIT_CHECK gives NA -
grading g/dL haemoglobin against the SI "ctcv5" table returns NA, and
"ctcv5_uscv" is the table to use instead;
a value in range for a graded term gives "0".
The per-study %LABGRADE / %CTCAE macro: a DATA step of nested
IF paramcd = 'ALT' AND aval > 3*anrhi THEN atoxgr = 2; ELSE IF ...
branches, one block per parameter, re-typed and re-validated on every study.
Here the branches are published criteria data, and the IF/ELSE cascade is
replaced by one call. See sas_note().
adlb <- utils::read.csv(
system.file("extdata", "adlb_example.csv", package = "admiralease")
)
# Default: NCI-CTCAE v5 laboratory criteria (admiral::atoxgr_criteria_ctcv5)
graded <- grade_lab(adlb)
#> ℹ No criteria for 1 term: "Hypophosphatemia" (grade left NA).
graded[, c("PARAMCD", "AVAL", "ATOXDSCH", "ATOXGRL", "ATOXGRH", "ATOXGR")]
#> # A tibble: 17 × 6
#> PARAMCD AVAL ATOXDSCH ATOXGRL ATOXGRH ATOXGR
#> <chr> <dbl> <chr> <chr> <chr> <chr>
#> 1 ALT 20 Alanine aminotransferase increased NA 0 0
#> 2 ALT 120 Alanine aminotransferase increased NA 2 2
#> 3 ALT NA Alanine aminotransferase increased NA NA NA
#> 4 POTAS 5.4 Hyperkalemia 0 0 0
#> 5 POTAS 5.8 Hyperkalemia 0 2 2
#> 6 POTAS 3.2 Hyperkalemia 2 0 -2
#> 7 POTAS 1.9 Hyperkalemia 4 0 -4
#> 8 SODIUM 128 Hypernatremia 3 0 -3
#> 9 HGB 6 Hemoglobin increased NA NA NA
#> 10 PLAT 400 NA 0 NA 0
#> 11 PLAT 60 NA 2 NA -2
#> 12 BILI 40 Blood bilirubin increased NA 2 2
#> 13 CREAT 130 Creatinine increased NA 2 2
#> 14 ALB 30 NA 1 NA -1
#> 15 HGBC 9 Hemoglobin increased NA NA NA
#> 16 PHOS 0.7 NA NA NA NA
#> 17 ANISO 1 NA NA NA NA
# Same records under CTCAE v4.03
grade_lab(adlb, "ctcv4")$ATOXGR
#> [1] "0" "2" NA "0" "2" "-2" "-4" "-3" NA "0" "-2" "2" "2" "-1" NA
#> [16] "-2" NA
# US conventional units: only the g/dL haemoglobin record grades
grade_lab(adlb, "ctcv5_uscv")$ATOXGRL
#> ℹ No criteria for 1 term: "Hypophosphatemia" (grade left NA).
#> [1] NA NA NA "0" "0" "2" "4" "3" NA NA NA NA NA NA "2" NA NA
# Sponsor thresholds supplied as data. This fixture is a DEMO in
# pharmaverseadam units - not NCI-CTCAE, never use it to grade a study.
demo <- utils::read.csv(
system.file("extdata", "demo_grading_table.csv", package = "admiralease")
)
grade_lab(adlb, demo)$ATOXGR
#> ℹ No grading criteria for 4 parameters: "ALB", "HGBC", "PHOS", and "ANISO" (grade left NA).
#> [1] "0" "2" NA "0" "2" "-1" "-4" "-2" "-2" "0" "-2" "2" "1" NA NA
#> [16] NA NA