Convert datasets in DataCombined to common units

When multiple (observed and/or simulated) datasets are present in a data frame, they are likely to have different units. This function helps to convert them to a common unit specified by the user.

This is especially helpful while plotting since the quantities from different datasets to be plotted on the X-and Y-axis need to have same units to be meaningfully compared.

Usage

convertUnits(dataCombined, xUnit = NULL, yUnit = NULL)

Arguments

dataCombined

A single instance of DataCombined class.

xUnit, yUnit

Target units for xValues and yValues, respectively. If not specified (NULL), first of the existing units in the respective columns (xUnit and yUnit) will be selected as the common unit. For available dimensions and units, see ospsuite::ospDimensions and ospsuite::ospUnits, respectively.

Value

A data frame with measurement columns transformed to have common units.

In the returned tibble data frame, the following columns will always be present:

name - group - dataType - xValues - xDimension - xUnit - yValues - yErrorValues - yDimension - yUnit - yErrorType - yErrorUnit - molWeight

Importantly, the xUnit and yUnit columns will have unique entries.

Note

Molecular weight is required for the conversion between certain dimensions (Amount, Mass, Concentration (molar), and Concentration (mass)). Therefore, if molecular weight is missing for these dimension, the unit conversion will fail.

See also

Other data-combined: DataCombined, calculateResiduals()

Examples

# simulated data
simFilePath <- system.file("extdata", "Aciclovir.pkml", package = "ospsuite")
sim <- loadSimulation(simFilePath)
simResults <- runSimulation(sim)
outputPath <- "Organism|PeripheralVenousBlood|Aciclovir|Plasma (Peripheral Venous Blood)"

# observed data
obsData <- lapply(
  c("ObsDataAciclovir_1.pkml", "ObsDataAciclovir_2.pkml", "ObsDataAciclovir_3.pkml"),
  function(x) loadDataSetFromPKML(system.file("extdata", x, package = "ospsuite"))
)
names(obsData) <- lapply(obsData, function(x) x$name)


# Create a new instance of `DataCombined` class
myDataCombined <- DataCombined$new()

# Add simulated results
myDataCombined$addSimulationResults(
  simulationResults = simResults,
  quantitiesOrPaths = outputPath,
  groups = "Aciclovir PVB"
)

# Add observed data set
myDataCombined$addDataSets(obsData$`Vergin 1995.Iv`, groups = "Aciclovir PVB")

convertUnits(
  myDataCombined,
  xUnit = ospUnits$Time$s,
  yUnit = ospUnits$`Concentration [mass]`$`µg/l`
)
#> # A tibble: 504 x 27
#>    name        group dataT~1 xValues xUnit xDime~2 yValues yUnit yDime~3 yErro~4
#>    <chr>       <chr> <chr>     <dbl> <chr> <chr>     <dbl> <chr> <chr>     <dbl>
#>  1 Organism|P~ Acic~ simula~       0 s     Time         0  µg/l  Concen~      NA
#>  2 Organism|P~ Acic~ simula~      60 s     Time       733. µg/l  Concen~      NA
#>  3 Organism|P~ Acic~ simula~     120 s     Time      2050. µg/l  Concen~      NA
#>  4 Organism|P~ Acic~ simula~     180 s     Time      3382. µg/l  Concen~      NA
#>  5 Organism|P~ Acic~ simula~     240 s     Time      4668. µg/l  Concen~      NA
#>  6 Organism|P~ Acic~ simula~     300 s     Time      5901. µg/l  Concen~      NA
#>  7 Organism|P~ Acic~ simula~     360 s     Time      7077. µg/l  Concen~      NA
#>  8 Organism|P~ Acic~ simula~     420 s     Time      8194. µg/l  Concen~      NA
#>  9 Organism|P~ Acic~ simula~     480 s     Time      9249. µg/l  Concen~      NA
#> 10 Organism|P~ Acic~ simula~     540 s     Time     10242. µg/l  Concen~      NA
#> # ... with 494 more rows, 17 more variables: yErrorType <chr>,
#> #   yErrorUnit <chr>, IndividualId <int>, molWeight <dbl>, lloq <dbl>,
#> #   Source <chr>, File <chr>, Sheet <chr>, Molecule <chr>, Species <chr>,
#> #   Organ <chr>, Compartment <chr>, `Study Id` <chr>, Gender <chr>, Dose <chr>,
#> #   Route <chr>, `Patient Id` <chr>, and abbreviated variable names
#> #   1: dataType, 2: xDimension, 3: yDimension, 4: yErrorValues