Introduction to the patientProfilesVis package

1 Introduction

This package patientProfilesVis enables to create subject profile reports of patients/subjects in a clinical trial.

Such visualization can be used to obtain a global view of the subject metadata information, combined with its treatment exposure and concomitant medications, in relation with the adverse events occurring during the trial, and any measurements conducted during a clinical trial (e.g. laboratory, vital signs or ECG).

    library(patientProfilesVis)
    library(pander)

1.1 Input data

1.1.1 Data format

The input dataset for the creation of patient profiles should be a data.frame, typically CDISC ‘Study Data Tabulation Model’ (a.k.a SDTM) or ‘Analysis Data Model’ (a.k.a. ADaM) datasets.

The package also support tibble datasets as imported by the read_sas/read_xpt functions from the haven.

Alternatively, datasets can be imported at once with the loadDataADaMSDTM function from the clinUtils package.

Furthermore, the input dataset should contain a variable containing subject identifier. This variable is set to USUBJID by default, but can be overwritten via the subjectVar parameter.

1.1.2 Example SDTM dataset

The package is demonstrated with a subset of the SDTM datasets from the CDISC Pilot 01 dataset, available in the clinUtils package.

library(clinUtils)

# import example data:
data(dataSDTMCDISCP01)
# formatted as a list of data.frame (one per domain)
dataSDTM <- dataSDTMCDISCP01
names(dataSDTM)

##  [1] "AE"     "CM"     "DM"     "DS"     "EX"     "LB"     "MH"     "QS"    
##  [9] "SUPPDM" "SV"     "VS"

# and corresponding labels
labelVarsSDTM <- attr(dataSDTM, "labelVars")
head(labelVarsSDTM) 

##                               STUDYID                                DOMAIN 
##                    "Study Identifier"                 "Domain Abbreviation" 
##                               USUBJID                                 AESEQ 
##           "Unique Subject Identifier"                     "Sequence Number" 
##                                AESPID                                AETERM 
##          "Sponsor-Defined Identifier" "Reported Term for the Adverse Event"

1.1.3 Example ADaM dataset

A subset of the ADaM datasets from the CDISC Pilot 01 dataset, available in the clinUtils package, is also imported for the example in section ADaM dataset.

# import example data:
data(dataADaMCDISCP01)
# formatted as a list of data.frame (one per domain)
dataADaM <- dataADaMCDISCP01
names(dataADaM)

## [1] "ADAE"     "ADCM"     "ADLBC"    "ADPP"     "ADQSADAS" "ADQSCIBC" "ADQSNPIX"
## [8] "ADSL"     "ADVS"

# and corresponding labels
labelVarsADaM <- attr(dataADaM, "labelVars")
head(labelVarsADaM)

##                     STUDYID                      SITEID 
##          "Study Identifier"     "Study Site Identifier" 
##                     USUBJID                        TRTA 
## "Unique Subject Identifier"          "Actual Treatment" 
##                       TRTAN                         AGE 
##      "Actual Treatment (N)"                       "Age"

# example subjects for the vignette:
subjectAE <- "01-718-1427"
subjectMH <- "01-718-1371"
subjectCM <- "01-701-1148"
subjectLB <- "01-704-1445"

2 Creation of the plot modules

2.1 General

Different types of visualization (a.k.a ‘modules’) are available via dedicated R function. Each function creates a separate visualization for each subject available in the dataset.

Four plot types/modules are currently available in the package:

• ‘text’ module: patient specific information formatted as text, available via the subjectProfileTextPlot function
• ‘interval’ module: representation of event with a start and end time, available via the subjectProfileIntervalPlot function
• ‘event’ module: representation of event occurring at a single time, available via the subjectProfileEventPlot function
• ‘line’ module: representation of the evolution of a continuous parameter across time via the subjectProfileLinePlot function

Each of this function returns a nested list of plots (ggplot object).

Each element of the list contains the plots for a specific subject. The subject profile plot for a specific subject/module is possibly split into multiple plots to fit in the final report (formatReport parameter).

2.2 Text module

The ‘text’ module enables to specify meta-information for each subject. There are two ways to specify such information, either by specifying a set of variables/columns of the data (paramValueVar only), or by a variable/column containing the parameter name (paramNameVar) and variable(s)/column(s) containing the parameter value (paramValueVar).

2.2.1 Wide format

    # annotate subject demographics meta-data
    # by specifying a set of variables to include
    dmPlots <- subjectProfileTextPlot(
        data = dataSDTM$DM,
        paramValueVar = c("SEX|AGE", "RACE|COUNTRY", "ARM"),
        labelVars = labelVarsSDTM
    )

Demographic information with the ‘subjectProfileTextPlot’ function for patient: 01-701-1148

2.2.2 Long format

2.2.2.1 General

It is possible to specify multiple variable to represent in the plot for a certain variable name.

    # annotate subject medical history
    # by specifying a combination of parameter value/name
    mhPlots <- subjectProfileTextPlot(
        data = dataSDTM$MH,
        paramNameVar = c("MHDECOD"),
        paramValueVar = c("MHSTDTC", "MHSEV"),
        paramGroupVar = "MHCAT",
        title = "Medical History: status",
        labelVars = labelVarsSDTM
    )

Medical history with the ‘subjectProfileTextPlot’ function for patient: 01-718-1371

2.2.3 Table format (listing)

Information is displayed as a listing, by setting the table parameter to TRUE.

    aeListingPlots <- subjectProfileTextPlot(
        data = dataSDTM$AE,
        paramValueVar = c(
            "AEBODSYS", "AESOC", "AEHLT", 
            "AELLT", "AEDECOD", "AESTDTC", 
            "AEENDTC", "AESER", "AEACN"
        ),
        paramGroupVar = "AESTDTC",
        labelVars = labelVarsSDTM,
        table = TRUE
    )