What v1.5.0 puts in the package, annotated

Appendix Tables 56 and 57 give the level 1, 2 and 3 abnormality thresholds the guide counts outliers against; Tables 58 to 60 give the values beyond which a result is treated as a laboratory or recording error and left out of the mean-change figures. They existed only as a PDF. They are now two data frames, transcribed row for row, with the printed criterion kept beside the parsed number and the guide page on every row.

The extreme-value table is long: every parameter appears twice, once in US-conventional units and once in SI, because the guide prints both and the data decide which one applies. The example data are mostly SI with bilirubin in both unit systems, which is exactly the case that would go wrong with one column.

> subset(FDA_AbnormalityLevels, Panel == "Liver Biochemistry",
+        select = c(Parameter, Direction, Basis, Operator, Level1, Level2, Level3, GuidePage))
                  Parameter Direction        Basis Operator Level1 Level2 Level3 GuidePage
       Alkaline phosphatase      high uln_multiple        >    1.5    2.0      3       120
   Alanine Aminotransferase      high uln_multiple        >    3.0    5.0     10       120
 Aspartate Aminotransferase      high uln_multiple        >    3.0    5.0     10       120
            Total Bilirubin      high uln_multiple        >    1.5    2.0      3       120

> subset(FDA_ExtremeValues, Parameter == "Glucose", select = c(Specimen, UnitSystem, Unit, Low, High))
 Specimen UnitSystem   Unit  Low High
   plasma         US  mg/dL 10.0 2700
   plasma         SI mmol/L  0.6  150

Each function takes the long lab table the example data already use, one row per participant per test per visit, and returns the same table with its answer added as new columns. Nothing is dropped and nothing is summarised, so a static figure and its interactive twin can read the same derived values. Derive_ULNMultiple() puts each result on the multiple-of-ULN scale. Derive_AbnormalityLevel() grades it against Tables 56 and 57 and says which direction and which printed criterion fired. Derive_ExtremeValueFlag() marks the results Tables 58 to 60 would exclude.

Every liver result in the example data, graded. The dashed lines are the Table 56 cuts read from the dataset above, not typed into the plot; the colours are the grade the function assigned. Bilirubin carries 30 level 3 results and alkaline phosphatase 12, which is what the eDISH quadrants will be drawn from in phase 1.

> dfLabs <- ExampleData("adbds")
> dfLabs <- Derive_AbnormalityLevel(dfLabs)
Derive_AbnormalityLevel left NA for records it could not evaluate:
  unit differs from the criteria's (mg/dL): Blood urea nitrogen in mmol/L, Calcium in mmol/L, Cholesterol (total) in mmol/L, Glucose in mmol/L, Phosphate in mmol/L
  qualifier 'Fasting' needs a column this function does not take: Glucose
  unit differs from the criteria's (g/dL): Albumin in g/L, Protein (total) in g/L
  basis 'baseline_multiple' needs a baseline column this function does not take: Creatinine
  needs a sex column (strSexCol) for the sex-qualified rows: Hemoglobin
  ... (the full list names every skipped parameter and why)

> dfGraded <- dfLabs[!is.na(dfLabs$AbnormalityLevel) & dfLabs$AbnormalityLevel > 0, ]
> table(dfGraded$TEST, dfGraded$AbnormalityLevel)
                               1   2   3
  Alanine Aminotransferase   102  10   0
  Alkaline Phosphatase       121  14  12
  Aspartate Aminotransferase  93   0   0
  Bilirubin                   15  71  30
  Chloride                   243  27   0
  Leukocytes                  35   9   0
  Potassium                   40   9   0
  Sodium                       5   2   0

The safety.viz renderers each carry a requirement matrix, and a test cites a row by its ID. The FDA figures now have one too, in the same shape: FDA-FIG-001 to FDA-FIG-022 for the 22 figures, numbered as the guide numbers them, and FDA-RULE-001 to FDA-RULE-016 for the rules the guide states once and several displays read. A static rendering here and an interactive one in safety.viz cite the same ID, so their evidence meets on one row.

$ grep -c '^| FDA-FIG-' requirements/fda-stf.md
22
$ grep -cE '^\| FDA-[A-Z]+-[0-9]+' requirements/fda-stf.md
38
$ grep -rho 'FDA-RULE-[0-9]*' tests/testthat/ | sort | uniq -c
      4 FDA-RULE-001
      6 FDA-RULE-002
      1 FDA-RULE-003
      3 FDA-RULE-004
      2 FDA-RULE-005
      1 FDA-RULE-008
      1 FDA-RULE-016

The guide is written against ADaM. gsm.safety holds two other shapes: the vendored example data and the Mapped_* domains gsm.mapping produces. The design assumed they aligned and said phase 0 should check. The note lists, for ADSL, ADAE, ADLB and ADVS, every column the 22 figures and the three derivations need, marks each as found, mapped, derivable or missing, and records a decision for every gap.