Automated Approach to PK and PKPD Dataset Assembly
This repository contains several R functions to support the assemblyof PK(PD) datasets to be used in NONMEM. The functions will create aPK(PD) dataset with consistent column names and covariate labels.Additional functions are used to support covariate analysis, combinedatasets to form a population dataset, and create dataset definitionfiles to support regulatory submissions.
The latest CRAN release can be installed with the followingcommands:
install.packages("apmx")library(apmx)The current development package can be downloaded from GitHub withthe following commands:
devtools::install_github("stephen-amori/apmx")library(apmx)pk_build() creates a PK(PD) dataset for analysis inNONMEM from source data. The functions is not intended to producedatasets for NCA.
The function automatically maps CDISC terminology to a uniform variablename (apmx name) appropriate for pharmacometric analysis.
The function issues a variety of warnings and errors to inform the userof problematic subjects and records.
General comments:
* Theex andpc domain may accept standardCDISC attribute names or apmx names. apmx names are required for pdevents.
*DTIM (the date/time of the record) must be in ISO-8601format to be processed correctly. All date/times assumed to be UTC.Accepted forms:
+ YYYY:mm:ddTHH:MM:SS
+ YYYY:mm:dd HH:MM:SS
+ YYYY:mm:ddTHH:MM
+ YYYY:mm:dd HH:MM
+ YYYY:mm:dd (this format is not accepted for ex, pc, or pdevents)
* All covariates are automatically renamed based on type and categoricalcovariates are automatically mapped to a numeric type in the followingmanner:
+ All character-type covariates are considered categorical. The givencovariate will be mapped to a numeric value and the column name willstart with a prefix “N” (subject-level) or “T” (time-varying). Thecharacter description is retained and the column name will end with thesuffix “C”. For example, an input subject-level covariate “SEX” willmapped to “NSEX” (numeric) and “NSEXC” (character).
+ All numeric-type covariates are considered continuous. The covariatecolumn name will start with a prefix “B” (baseline) or “T”(time-varying).
+ All numeric-type covariates must also have an associated charactercolumn for units. For example, an input dataframe with covariate “AGE”must have an accompanying column “AGEU”.
* The study labelSTUDY must be provided in either theex domain orsl.cov domain.
* Missing date/times can be handled three different ways with theimpute parameter.
+impute can be left empty, which will not impute times forany event missingDTIM.
+impute = 1 will set all actual time variables equal tothe nominal time for events whereDTIM is missing. Thismethod is appropriate for pre-clinical analysis when actual times maynot be collected.
+impute = 2 will estimate actual time variables relativeto other events occurring that day for events whereDTIM ismissing. This method is appropriate for phase I-III analyses whenindividual events are missing a date/time.
apmx attribute names and definitions:
*USUBJID: unique subject ID (character or numeric)
*DTIM: date-time of the event (character)
*NDAY: nominal day of event, derived from protocol-definedvisit (numeric) + Day of first dose should start at nominal (study) day1, not day 0.
+ Day prior to first dose should be documented as day -1, not day0.
*TPT: nominal timepoint of event, derived fromprotocol-defined timepoint (numeric)
*VISIT: visit label (character)
*TPTC: timepoint label (character)
*ROUTE: dose route description (character)
*FRQ: dose frequency description (character)
*AMT: administered dose amount for dose events only(numeric)
*CMT: compartment assignemt for each event (numeric)
*DVID: dependent variable label (character)
+ dose events should have the same label as the parent PKmetabolite
*DVIDU: dependent variable unit label (character)
+ dose events should have the dose units listed in this variable
*ODV: original dependent variable (numeric)
*LLOQ: lower limit of quantification (numeric)
*STUDY: study label (character)
apmx derived attribute names and definitions:
*SUBJID: numeric form ofUSUBJID
*ID: ID counting variable
*ATFD: actual time since first dose
*ATLD: actual time since last (most recent) dose
*NTFD: nominal time since first dose
*NTLC: nominal time since last cycle
*NTLD: nominal time since last (most recent) dose
*EVID: event ID (NONMEM-required)
*MDV: missing dependent variable (NONMEM-required) *DVID: numeric mapping of input DVID
*LDV: log-transformed dependent variable
*BDV: baseline dependent variable (for PD eventsonly)
*DDV: delta from baseline dependent variable (for PDevents only)
*PDV: percent change from baseline dependent variable (forPD events only)
*BLQ: flag for BLQ records
+BLQ = 0 when observation is not BLQ
+BLQ = 1 when observation is BLQ and prior to firstdose
+BLQ = 2 when observation is BLQ and after firstdose
*DOSEA: most recently administered dose amount
*DOMAIN: event domain *DVIDC: characterlabel for DVID
*TIMEU: units for all time variables
*FDOSE: date/time of first dose
*VERSN: apmx package version number *BUILD:date of dataset construction
*COMBD: date of dataset combination (generated fromapmx::pk_combine() only)
apmx derived binary flag names and definitions:
*PDOSEF: records that occur prior to first dose
*TIMEF: records with no TIME information
*AMTF: dose events with missingAMT
*DUPF: duplicated events within the sameID-ATFD-EVID-CMT
*NOEXF: subjects with no dose events
*NODVNF: subjects with no observations in compartment n(one flag per observation compartment)
*SDF: subjects who are single-dose (as opposed tomulti-dose)
*PLBOF: records where the most recent dose isplacebo
*SPARSEF: records associated with sparse sampling (asopposed to serial)
*TREXF: dose records that trail the final observationrecord
*IMPEX: time of last (most recent) dose event wasimputed
*IMPDV: time of observation event was imputed
*IMPFEX: time of first dose event was imputed
*C: comment flag to indicate a record will be ignored inthe analysis
pk_combine() will combine two PK(PD) datasets built bypk_build() to form a population dataset.
All categorical covariates are re-calculated to ensure they areconsistently labeled throughout the population analysis.
The function confirms the analytes and compartments are in agreementbetween both studies.
cov_find() will identify the columns in a PK(PD) datasetthat belong to a certain covariate class.
Covariates can be “categorical”, “continuous”, “exposure”, “empiricalbayes estimate”, or “other”.
Types can be “numeric” or “character”.
cov_apply() will add additional covariates to a PK(PD)dataset already built bypk_build().
It can apply covariates of any type, either subject-level ortime-varying.
Covariates can be merged by any ID variable (USUBJID, SUBJID, or ID) orany time variable (ATFD, ATLD, NTFD, NTLC, NTLD, NDAY, TPT).
The same prefix and suffix system is applied to covariates built withcov_apply()
* Exposure metrics can be added with this function and will receive theprefix “C”
* Empirical bayes estimates can be added with this functoin and willreceive the prefix “I”
pk_write() will write out a PK(PD) dataset as a .csvfile to the filepath of your choice in a NONMEM-ready format.
pk_define() will create a definition file for a PK(PD)dataset built bypk_build(). It can be produced as a dataframe in R or exported as a Word document. The function requres adataset and a list of variable definitions. For more information on thislist, refer tovariable_list_create().
Other arguments: *file: filepath to a .docx file tospecify the file name and location of exported Word document *project: character string to specify project name. Thisname will appear in the header of the definition file if the templatecontains the word “Project” in the header.
*data: character string to specify dataset name. This namewill appear in the header of the definition file if the templatecontains the word “Dataset” in the header.
*variable.list: data frame of variable definitions youwish to use. The variable list should have the following columns in thisorder:
+ Variable: variable name (covariates just need the root term for properdefinitions. For example, the variable for covariates “NSEX” and “NSEXC”only need to be listed once as “SEX”)
+ Category: desired variable category
+ Description: desired variable description (covariates areautomatically detected as “subject-level” or “time-varying” and labeledas such, you only need to provide the root definition. For example, thedescription for “SEX” can be listed “sex”. For NSEX, the definition filewould read “Subject sex”.)
+ Comment: desired comment
*template: optional filepath to template .docx documentyou wish to use. The definition table will append to the end of thedocument. If you leave the template blank, the definition table willread into a blank document, andproject anddata parameters will be ignored.
pk_summarize() will create summary tables (BLQ,categorical covariates, and continuous covariates) of the datasetcreated bypk_build() orpk_combine().
Summary tables can be exported as .csv files, .docx files, and/or .pptxfiles. They can be stratified by any variable in the dataset. You canfilter the dataset prior to summary statistics.
version_log() will create a version log of datasetscreated bypk_build() orpk_combine(). Thefirst time you call the function, it will create an initial entry. Youcan export the version log as a Word document. Then, after you create anew, updated dataset, you can call theversion_log() again.If you provide the filepath to the current version log, the new dataset,and the old dataset, the version log will add the new dataset andprovide a brief summary comparison of the two.
variable_list_create() is a helper function forpk_define() that creates a standard variable list. Thestandard apmx variable names and definitions are already included. Youcan add your own variables (custom covariates, etc.) so they areincluded in the definition file.
In addition to bug fixes and runtime improvements, future functionswill focus on the following areas:
* Assembly of datasets to support QTC-prolongation analysis
* Assembly of datasets to support TTE and other ER analyses
* Additional dataset QC and documentation tools
* Auxiliary functions to support dataset assembly
Mildred Afoumbom
Joyceline Afumbom
Stephen Amori
Ethan DellaMaestra
Michael Dick
Ekiti Ekote
Daniel Litow
Jonah Lyon