MonolixSuite in R
MonolixSuite in R
Breadcrumbs

process_QTcData()

Purpose

The function processes cardiac data to prepare the necessary variables for the conc-QTc analysis. In particular, it compute QTc, baseline column and delta values. The generated dataset is saved in csv or xlsx format.

Details

The function performs the following steps:

  • computes HR = 60 / (RR / 1000) and RR = 60 / (HR / 1000) if not provided.

  • replaces missing concentrations by zero. If missing concentrations are found in the non-placebo groups, a warning is raised.

  • remove lines with missing time value.

  • computes QTc column using Fridericia, Bazett, Framingham or Hodges formula, or computes the optimal alpha coefficient QTc=QT/(RR/1000)^(1/alpha) using the drug-free records. This step can be done before or after averaging triplicates. If QTc is already present in the dataset, this step can be skipped.

  • averages triplicates (if any). The grouping is done based on the ID, TIME, TRT, BLFLAG and additional variables (if provided).

  • computes baseline QTc and baseline HR columns. Baseline records are indicated via the BLFLAG column. The grouping is done by ID and TRT (if predose baseline), as well as by TIME in case of time-matched baseline. Additional variables can be indicated in addition. If BLQTc and BLHR are already present in the dataset, this step can be skipped.

  • in case of time-matched baseline, deletes the baseline records lines.

  • computes the baseline-corrected QTc (ΔQTc = QTc - BLQTc) and baseline-corrected HR (ΔHR = HR - BLHR).

  • computes the baseline QTc centered by the population average as BLQTc_cent=BLQTc-mean(BLQTc). This variable will be used in the linear model.

  • if placebo data is available for all individuals, computes the placebo-adjusted baseline-corrected QTc (ΔΔQTc = ΔQTc_active - ΔQTc_placebo) and placebo-adjusted baseline-corrected HR (ΔΔHR = ΔHR_active - ΔHR_placebo). The placebo-adjusted centered BLQTc is also computed.

  • duplicates the RR, CONC and TIME columns, such that they be used in several ways in the monolix project.

  • saves the generated dataset.

Arguments

  • data (character): the path to a dataset in csv format. Mandatory

  • QTname (character): column name for QT interval (in ms units). Mandatory

  • RRname (character): column name for RR interval (in ms units). Optional (if missing, the HR column is mandatory)

  • HRname (character): column name for heat rate (in bpm units). Optional (if missing, the RR column is mandatory)

  • CONCname (character): column name for drug concentration (any units). Mandatory

  • TRTname (character): column name for treatment group (e.g placebo versus drug). Optional if no placebo, mandatory otherwise

  • IDname (character): column name for subject ID. Mandatory

  • TIMEname (character): column name for nominal time points (in hr units). Mandatory

  • TRT (vector of characters): a vector of treatment groups to include in the analysis (should be a subset of the values present in the TRTname column). Defaults to all groups in the dataset. Optional

  • placeboName (character): a string specifying the name of the placebo group. Default: “Placebo” (case insensitive). Optional

  • addVariables (vector of characters): additional columns to be used as grouping variables to average triplicates and compute the baseline column (e.g “day”). Optional

  • bComputeBaseline (logical): if ‘true’ (default) computes baseline QTc and HR. Otherwise, uses pre-calculated baseline values provided via BLQTCname and BLHRname. Optional

  • BLFLAGname (character): column name for baseline flag. It should contain "Y"/"N" or "1"/"0" values with Y or 1 indicating baseline records. Mandatory if bComputeBaseline=T, ignored otherwise

  • bComputeBLperAddVar (logical): if ‘true’ (default) the baseline QTc and HR are computed for each value of the ‘addVariables’ (e.g for each day). Optional

  • baselineType (character): a string specifying the baseline type, among ‘predose’ (default) or ‘time-matched’. Optional

  • BLQTCname (character): column name for pre-calculated baseline QTc (if available). Mandatory if bComputeBaseline=T, otherwise ignored.

  • BLHRname (character): column name for pre-calculated baseline HR (if available). Mandatory if bComputeBaseline=T, otherwise ignored.

  • bComputeQTc (logical): If ‘true’ (default), computes baseline QTc and HR. Otherwise, uses pre-calculated QTc values provided via QTCname. Optional

  • correctionMethod (character): a string specifying the heart-rate correction method, among ‘Fridericia' (default), 'Bazett', 'Framingham', 'Hodges' or 'Population’. Optional

  • QTCname (character): column for the pre-calculated corrected QT (QTc) (if available). Mandatory when bComputeQTc=F, otherwise ignored.

  • stepOrder (chacacter): if ‘FirstCorrectThenAverage’, the function first calculated QTc and then average triplicates. Otherwise, with ‘FirstAverageThenCorrect’, the function first averages triplicates and then calculated QTc. Optional

  • outName (character): a string specifying the output file name (with file extension .csv, .xlsx, or .txt). Mandatory

  • silent (logical): if ‘false’ (default), the transformation steps are printed to the R console. Optional

Examples

Example 1

The first example below shows how to process a dataset which contains columns for QT and RR, but for which the QTc and its baseline are not available yet. We thus use bComputeQTc = TRUE and specify the correction formula with correctionMethod = "Fridericia". In case of triplicate records which will be averaged, the order of heart-rate correction and triplicate averaging can be chosen using stepOrder = "FirstCorrectThenAverage". In order to create dedicated columns containing the baseline QTc and baseline HR, we use bComputeBaseline = TRUE. Which records correspond to the baseline must be indicated using a column containing “Y”/”N” or “1”/”0” values and passed as BLFLAGname argument. The type of baseline (predose or time-matched) is indicated via baselineType = "predose". The placebo versus active drug periods must be indicated in a column given as TRTname argument. The different categories present in the TRT column are detected automatically, but can also be listed explicitly in the TRT argument, which allows to select only a subset if needed. The category corresponding to the placebo is usually detected automatically, but can also be given explicitly in placeboname if a non-standard string is used for placebo in the TRT column.

process_QTcData(
   data = "/path/data.csv",
   QTname = "QT",
   RRname = "RR",
   CONCname = "Conc",
   TRTname = "TRT",
   IDname = "USUBJID",
   TIMEname = "TSLD",
   TRT = c("LIX1234 50 mg", "LIX1234 100 mg", "Placebo"),
   placeboName = "Placebo",
   bComputeBaseline = TRUE,
   BLFLAGname = "BLFLAG",
   baselineType = "predose",
   bComputeQTc = TRUE,
   correctionMethod = "Fridericia",
   stepOrder = "FirstCorrectThenAverage",
   outName =  = "processed_data.csv",
   silent = F
 )

Example 2

The second example is a dataset which already contains a column for QTc and the QTc and HR baseline values. Thus, these columns do not need to be computed by the function and we use bComputeBaseline = FALSE and bComputeQTc = FALSE. The precomputed QTc and baseline QTc and HR columns are indicated via the arguments BLQTCname, BLHRname and QTCname. In this example, the HR column is defined instead of the RR column.

process_QTcData(
   data = "/path/data.csv",
   QTname = "ECGQT",
   HRname = "ECGHR",
   CONCname = "Conc",
   TRTname = "TRT",
   IDname = "USUBJID",
   TIMEname = "TIME",
   bComputeBaseline = FALSE,
   BLQTCname = "QTCBL", 
   BLHRname = "HRBL",
   bComputeQTc = FALSE,
   QTCname = "ECGQTC",
   outName = "processed_data.csv",
   silent = F
)

Example 3

In this example we consider a dataset without placebo data and time-matched baseline records. Given that the TRTname argument is not specified, all individuals are assumed to belong to the same (active) treatment. To compute the baseline using the time-matched records, we use baselineType = "time-matched".

process_QTcData(
   data = "/path/data.csv",
   QTname = "QT",
   RRname = "RR",
   CONCname = "Conc",
   IDname = "USUBJID",
   TIMEname = "TSLD",
   bComputeBaseline = TRUE,
   BLFLAGname = "BLFLAG",
   baselineType = "time-matched",
   bComputeQTc = TRUE,
   correctionMethod = "Fridericia",
   outName = "processed_data.csv",
   silent = F
 )

Example 4

This example shows the setup for a dataset with QT data collected over several days. The column containing the time within the day is indicated using TIMEname = "TIME" and the additional day variable is indicated with addVariables = "DAY". To use the day variable to group records to average triplicates and to compute the baseline, we use bComputeBLperAddVar = T.

process_QTcData(
   data = "/path/data.csv",
   QTname = "QT",
   RRname = "RR",
   CONCname = "DRUG",
   IDname = "USUBJID",
   TIMEname = "TIME",
   bComputeBaseline = TRUE,
   BLFLAGname = "BLFLAG",
   baselineType = "predose",
   addVariables = "DAY",
   bComputeBLperAddVar = T,
   bComputeQTc = TRUE,
   correctionMethod = "Fridericia",
   outName = "processed_data.csv",
   silent = F
 )