Load compound-specific data
load-data.RmdThis vignette describes how to provide the compound-specific data for the calculation of the DDI perpetrator risks.
In the first section, different data loading methods are presented, using the perpetrator drug property object as an example. The second section describes the requirements for the CYP-, UGT- or transporter inhibition data.
Drug properties
All functions within the ddir package that evaluate the
various DDI risks expect as their first argument a
perpetrator object that contains the compound properties
that are needed to calculate the relevant perpetrator
concentrations.
The following parameters are required to create a perpetrator object:
| PARAM | REQUIREMENT | DESCRIPTION |
|---|---|---|
| name | required | the name of the compound |
| oral | required | logical value (TRUE or FALSE) to indicate
whether the compound is administered orally |
| mw | required | molar weight in g/mol |
| dose | required for oral compounds | clinical dose in mg |
| imaxss | required | total \(C_{max}\) in ng/ml |
| fu | optional | fraction unbound, defaults to 1 |
| fumic | optional | microsomal unbound fraction, defaults to 1 |
| rb | optional | blood-to-plasma concentration ratio, defaults to 1 |
| fa | optional | fraction absorbed, defaults to 1 |
| fg | optional | fraction escaping gut metabolism, defaults to 1 |
| ka | optional | absorption rate constant, defaults to 0.1 /min |
| solubility | optional | aqueous solubility in mg/l, defaults to Inf
|
Input as data frame
As the most basic option, the compound property data can be hard-coded into a R script as a data frame and then converted into a perpetrator object:
parent_data_frame <- data.frame(
param = c("name", "oral", "mw", "dose", "imaxss"),
value = c("examplinib", "TRUE", "492.6", "450", "3530"),
source = c("", "", "", "", "")
)
parent <- new_perpetrator(parent_data_frame)
parent
#> ----- DDI perpetrator object -----
#> name examplinib
#> oral TRUE
#> mw 492.6
#> dose 450
#> imaxss 3530
#> fu 1 default
#> fumic 1 default
#> rb 1 default
#> fa 1 default
#> fg 1 default
#> ka 0.1 default
#> solubility Inf defaultNote that the constructor function for perpetrator objects expects all values to be of character type.
In the above code, only the strictly required fields were provided, the other fields were automatically set to their respective default values during the construction of the perpetrator compound.
Input as tribble
The tibble package that is part of the
tidyverse meta-package provides a very convenient function,
tribble(), to construct data frames in a row-wise fashion.
This renders the code much more readable:
parent_tribble <- tribble(
~param, ~value, ~source,
"name", "examplinib", "",
"oral", "TRUE", "",
"mw", "492.6", "",
"dose", "450", "",
"imaxss", "3530", ""
)
parent <- new_perpetrator(parent_tribble)
parent
#> ----- DDI perpetrator object -----
#> name examplinib
#> oral TRUE
#> mw 492.6
#> dose 450
#> imaxss 3530
#> fu 1 default
#> fumic 1 default
#> rb 1 default
#> fa 1 default
#> fg 1 default
#> ka 0.1 default
#> solubility Inf defaultRead from a csv file
Alternatively, the data can also be provided as comma-separated
values (csv) in an external data file, and read using
read_perpetrators(). The csv file
‘examplinib_compounds_single.csv’ is included as part of this package
for demonstration purposes:
parent_perpetrator <- read_perpetrators(
fs::path_package("extdata/examplinib_compounds_single.csv", package = "ddir")
)
parent_perpetrator %>%
class()
#> [1] "perpetrator" "data.frame"In the above code, the
fs::path_package("extdata/examplinib_compounds_single.csv", package = "ddir")
construct is needed to resolve the path to the sample file within the
package structure. In regular use, the file name should provided
here.
The csv file is expected to have ‘long table’ format: All line must start with the compound name, followed by the parameter name, the value and (optionally) source information.
This is what the content of a typical compound file may look like:
# PARENT
# compound, param, value, source
examplinib, oral, TRUE,
examplinib, mw, 492.6,
examplinib, dose, 450, clinical dose
examplinib, imaxss, 3530, study 001
examplinib, fu, 0.023, study 002
examplinib, fumic, 1, default
examplinib, rb, 1, study 003
examplinib, fa, 0.81, study 003
examplinib, fg, 1, default
examplinib, ka, 0.00267, unknownThe fields within a line must be separated by commas. All lines starting with ‘#’ are considered comments and are not evaluated.
Read from a data chunk within an R notebook
When the DDI risk calculations are done within an R notebook, which
we highly recommend to keep the data, code and report text in a single
Rmd document that can be knitted into a human-readable report, the
compound-specific data can be conveniently provided in the form of data
chunks. This is a neat feature introduced by the knitrdata
package.
The text contained in chunks of the type ‘data’ is assigned as-is to a character variable by the name defined by ‘output.var’ in the chunk header when the document is rendered:
```{data output.var = "compounds_text", wrapper = TRUE, engine="data"}# PARENT
# compound, param, value, source
examplinib, oral, TRUE,
examplinib, mw, 492.6,
examplinib, dose, 450, clinical dose
examplinib, imaxss, 3530, study 001
examplinib, fu, 0.023, study 002
examplinib, fumic, 1, default
examplinib, rb, 1, study 003
examplinib, fa, 0.81, study 003
examplinib, fg, 1, default
examplinib, ka, 0.00267, unknown
# METABOLITE
# compound, param, value, source
M1, oral, FALSE,
M1, mw, 506.56,
M1, dose, NA,
M1, imaxss, 1038, study 001
M1, fu, 0.012, study 002
-- 5 more lines of data ommitted --```Similar to the above csv file example, the content of this variable can then be read into a perpetrator object:
compounds <- read_perpetrators(
textConnection(compounds_text)
)
compounds
#> $examplinib
#> ----- DDI perpetrator object -----
#> name examplinib
#> oral TRUE
#> mw 492.6
#> dose 450 clinical dose
#> imaxss 3530 study 001
#> fu 0.023 study 002
#> fumic 1 default
#> rb 1 study 003
#> fa 0.81 study 003
#> fg 1 default
#> ka 0.00267 unknown
#> solubility Inf default
#> $M1
#> ----- DDI perpetrator object -----
#> name M1
#> oral FALSE
#> mw 506.56
#> dose NA
#> imaxss 1038 study 001
#> fu 0.012 study 002
#> fumic 1 default
#> rb 1 study 002
#> fa NA
#> fg NA
#> ka NA
#> solubility Inf defaultNote that since the data is not read from a file, the input string variable is wrapped in a
textConnection()construct.
Also note that the above data file contains data for two different compounds, ‘examplinib’ and ‘M1’. The output of the
read_perpetrators()function is therefore a list of perpetrator objects in this case.
You will find that the sample
DDI report for the fictional drug ‘examplinib’ that is provided as
part of the ddir package uses this approach. For your own
DDI assessment, feel free to copy that Rmd file and merely replace the
compound-specific data to obtain a basic DDI report for your drug.
Enzyme inhibition and induction data
The following sections describe the format in which the in
vitro data for enzyme or transporter inhibition or induction need
to be provided to the respective ddir functions. You can
use either of the above methods to load the data. However, as said
before, we suggest the input as data chunks within a R notebook
document.
Direct CYP inhibition data
The basic_cyp_inhibition_risk() and
mech_stat_cyp_risk() functions (and their
*_table() siblings) require the \(k_i\) values for direct CYP inhibition. A
data frame with the following fields is expected as the the ‘cyp_inh’
parameter to these functions:
| PARAM | DESCRIPTION |
|---|---|
| name | The name of the compound |
| cyp | The CYP enzyme (in upper case) |
| ki | the in vitro \(k_i\) in µM |
| source | source information for the parameter |
See the below sample data frame for ‘examplinib’:
examplinib_cyp_inhibition_data
#> name cyp ki source
#> 1 examplinib CYP1A2 NA
#> 2 examplinib CYP2B6 NA
#> 3 examplinib CYP2C8 11 study 001
#> 4 examplinib CYP2C9 0.6 study 001
#> 5 examplinib CYP2C19 0.25 study 001
#> 6 examplinib CYP2D6 NA
#> 7 examplinib CYP3A4 12.5 study 001
#> 8 M1 CYP2C9 4.4 study 002Use read_cyp_inhibitor_data() to load the data from a
csv file or textConnection.
UGT inhibition data
The basic_ugt_inhibition_risk() function relies on the
in vitro data for direct UGT inhibition. A data frame with the
following fields is expected as the ‘ugt_inh’ parameter to these
functions:
| PARAM | DESCRIPTION |
|---|---|
| name | The name of the compound |
| ugt | The UGT enzyme (in upper case) |
| ic50 | the in vitro \(k_i\) in µM |
| source | source information for the parameter |
See the below sample data frame for ‘examplinib’:
examplinib_ugt_inhibition_data
#> name ugt ic50 source
#> 1 examplinib UGT1A1 15 study 009
#> 2 examplinib UGT1A3 15 study 009
#> 3 examplinib UGT1A4 15 study 009
#> 4 examplinib UGT1A6 15 study 009
#> 5 examplinib UGT1A9 3.8 study 009
#> 6 examplinib UGT2B7 15 study 009
#> 7 examplinib UGT2B15 15 study 009
#> 8 examplinib UGT2B17 6.1 study 009
#> 9 M1 UGT1A1 1.1 study 009
#> 10 M1 UGT1A3 5.8 study 009
#> 11 M1 UGT1A4 6.2 study 009
#> 12 M1 UGT1A6 15 study 009
#> 13 M1 UGT1A9 3.6 study 009
#> 14 M1 UGT2B7 15 study 009
#> 15 M1 UGT2B15 9.6 study 009
#> 16 M1 UGT2B17 2.2 study 009Use read_ugt_inhibitor_data() to load the data from a
csv file or textConnection.
Time-dependent CYP inhibition (TDI) data
The basic_cyp_tdi_risk() and
mech_stat_cyp_risk() functions (and their
*_table() siblings) rely on the in vitro data for
TDI. A data frame with the below fields is expected as the ‘cyp_tdi’
parameter to these functions:
| PARAM | DESCRIPTION |
|---|---|
| name | The name of the compound |
| cyp | The CYP enzyme (in upper case) |
| ki | the in vitro \(k_i\) in µM |
| kinact | the inactivation rate in 1/h |
| source | source information for the parameters |
See the below sample data frame for ‘examplinib’:
examplinib_cyp_tdi_data
#> name cyp ki kinact source
#> 1 examplinib CYP3A4 0.17 0.04 study 001Use read_tdi_data() to load the data from a csv file or
textConnection.
CYP induction data
The static_cyp_induction_risk(),
kinetic_cyp_induction_risk() and
mech_stat_cyp_risk() functions (and their
*_table() siblings) rely on the in vitro data for
CYP induction. A data frame with the below fields is expected as the
‘cyp_ind’ parameter to these functions:
| PARAM | DESCRIPTION |
|---|---|
| name | The name of the compound |
| cyp | The CYP enzyme (in upper case) |
| emax | the in vitro emax, i.e., the maximal change in the mRNA level |
| ec50 | the \(EC_{50}\) of the induction in µM |
| maxc | the maximal concentration in µM tested in the in vitro study |
| source | source information for the parameters |
See the below sample data frame for ‘examplinib’:
examplinib_cyp_induction_data
#> name cyp emax ec50 maxc source
#> 1 examplinib CYP1A2 1.00 NA 5 study 007
#> 2 examplinib CYP2B6 1.00 NA 5 study 007
#> 3 examplinib CYP2C8 NA NA NA
#> 4 examplinib CYP2C9 NA NA NA
#> 5 examplinib CYP2C19 NA NA NA
#> 6 examplinib CYP2D6 NA NA NA
#> 7 examplinib CYP3A4 7.35 1.64 3 study 007
#> 8 M1 CYP1A2 1.00 NA 5 study 007
#> 9 M1 CYP2B6 6.98 1.86 5 study 007
#> 10 M1 CYP2C8 NA NA NA
#> 11 M1 CYP2C9 NA NA NA
#> 12 M1 CYP2C19 NA NA NA
#> 13 M1 CYP2D6 NA NA NA
#> 14 M1 CYP3A4 22.70 1.10 5 study 007Use read_inducer_data() to load the data from a csv file
or textConnection.
Transporter inhibition data
The transporter_inhibition_risk() function relies on the
in vitro data for direct transporter inhibition to be provided
as a data frame to the ‘transporter_inh’ parameter.
The following fields are expected:
| PARAM | DESCRIPTION |
|---|---|
| name | The name of the compound |
| transporter | The drug transporter |
| ic50 | the in vitro \(IC_{50}\) in µM |
| source | source information for the parameter |
See the below sample data frame for ‘examplinib’:
examplinib_transporter_inhibition_data
#> name transporter ic50 source
#> 1 examplinib Pgp 0.41 study 005
#> 2 examplinib BCRP 1.9 study 005
#> 3 examplinib OCT1 2.3 study 006
#> 4 examplinib OATP1B1 177 study 006
#> 5 examplinib OATP1B3 35 study 006
#> 6 examplinib OAT1 271
#> 7 examplinib OAT3 300
#> 8 examplinib BSEP 12.8
#> 9 examplinib OCT2 67 study 006
#> 10 examplinib MATE1 3.6 study 006
#> 11 examplinib MATE2k 1.1 study 006Use read_transporter_inhibitor_data() to load the data
from a csv file or textConnection.