`combine_supp` Improve error messaging and input validation for missing required columns in parent SDTM dataset

[ankonyeni]

Description

The combine_supp() function currently errors out when the parent SDTM dataset is missing required columns (either core SDTM identifiers or the columns referenced by IDVAR in the SUPP dataset).

Although the error is expected, the current messaging does not clearly identify which required variables are missing. Improving this would make debugging easier for users.

Requested Enhancement

Add validation checks for the parent dataset passed to the dataset parameter to ensure that it contains:

• STUDYID
• DOMAIN
• USUBJID
• All variables listed in IDVAR in the SUPP dataset

If any of these required variables are missing, the function should return a clear, informative error message such as:

combine_supp() requires the parent dataset to contain the following variables: STUDYID, DOMAIN, USUBJID, and all IDVAR variables from the SUPP dataset. Missing: .

This will help users quickly identify and correct input issues.

Reproducible Examples

AE <- data.frame(
    STUDYID = c("ABC123","ABC123","ABC123","ABC123","ABC123"),
    DOMAIN = c("AE","AE","AE","AE","AE"),
    USUBJID = c("ABC123-001","ABC123-001","ABC123-002","ABC123-002","ABC123-003"),
    AESEQ   = c(1,2,1,2,1),
    AESPID  = c("AE01","AE02","AE01","AE02","AE01"),
    AEGRPID = c(NA, "GRP-A", NA, "GRP-B", "GRP-A"),
    AETERM  = c("Headache","Nausea","Dizziness","Vomiting","Rash")
)

SUPPAE <- data.frame(
    STUDYID = c("ABC123","ABC123","ABC123","ABC123","ABC123","ABC123"),
    RDOMAIN = c("AE","AE","AE","AE","AE","AE"),
    USUBJID = c("ABC123-001","ABC123-001","ABC123-001","ABC123-002","ABC123-002","ABC123-003"),
    IDVAR   = c("AESEQ","AESEQ","AESPID","AESPID","AEGRPID","AEGRPID"),
    IDVARVAL = c("1","2","AE01","AE02","GRP-B","GRP-A"),
    QNAM    = c("AELAT","AETOXGR","AEREL","AEPATT","AESEV2","AESOC2"),
    QLABEL  = c("Laterality","Toxicity Grade","Relationship","Pattern","Severity (Alt)","SOC (Alt)"),
    QVAL    = c("LEFT","2","RELATED","INTERMITTENT","MODERATE","SKIN DISORDERS"),
    QORIG   = c("CRF","CRF","CRF","CRF","DERIVED","DERIVED"),
    QEVAL   = c(NA,NA,"INVESTIGATOR",NA,NA,NA)
)

Example 1: Missing IDVAR columns

AE_01 <- AE[, !names(AE) %in% unique(SUPPAE$IDVAR)]

combine_supp(AE_01, SUPPAE)

#Example 2: Missing core SDTM join keys

AE_02 <- AE[, !names(AE) %in% c('STUDYID', 'DOMAIN', 'USUBJID')]

combine_supp(AE_02, SUPPAE)