Object combining simulated and observed data

A class for storing simulated and/or observed in a single data frame, which can be further used in data wrangling or data visualization pipelines.

Additionally, it allows:

Grouping different simulated and/or observed datasets.
Transforming data with given offsets and scale factors.

Note

The molecular weight (in molWeight column) is in g/mol units.

Super class

ospsuite.utils::Printable -> DataCombined

Active bindings

names: A vector of unique names of datasets contained in the DataCombined class instance.
groupMap: A data frame specifying which datasets have been grouped together and the name and the nature (observed or simulated?) of the data. If a dataset was not assigned to any group, this is denoted by NA in the data frame.
dataTransformations: A data frame with offset and scale factor values were specified by the user for each dataset.

Methods

Method `addDataSets()`

Adds observed data.

Usage

DataCombined$addDataSets(dataSets, names = NULL, groups = NULL)

Arguments

dataSets: An instance (or a list of instances) of the DataSet class.
names: A string or a list of strings assigning new names. These new names can be either for renaming DataSet objects, or for renaming quantities/paths in SimulationResults object. If an entity is not to be renamed, this can be specified as NULL. E.g., in names = list("oldName1" = "newName1", "oldName2" = NULL)), dataset with name "oldName2" will not be renamed. The list can either be named or unnamed. Names act as unique identifiers for data sets in the DataCombined object and, therefore, duplicate names are not allowed.
groups: A string or a list of strings specifying group name corresponding to each data set. If an entry within the list is NULL, the corresponding data set is not assigned to any group (and the corresponding entry in the group column will be an NA). If provided, groups must have the same length as dataSets and/or simulationResults$quantityPath. If no grouping is specified for any of the dataset, the column group in the data frame output will be all NA.

Returns

DataCombined object containing observed data.

Method `addSimulationResults()`

Add simulated data using instance of SimulationResults class.

Usage

DataCombined$addSimulationResults(
  simulationResults,
  quantitiesOrPaths = NULL,
  population = NULL,
  individualIds = NULL,
  names = NULL,
  groups = NULL
)

Arguments

simulationResults: Object of type SimulationResults produced by calling runSimulation() on a Simulation object. Only a single instance is allowed in a given $addSimulationResults() method call.
quantitiesOrPaths: Quantity instances (element or list) typically retrieved using getAllQuantitiesMatching() or quantity path (element or list of strings) for which the results are to be returned. (optional) When providing the paths, only absolute full paths are supported (i.e., no matching with '*' possible). If quantitiesOrPaths is NULL (default value), returns the results for all output defined in the results.
population: Population used to calculate the simulationResults (optional). This is used only to add the population covariates to the resulting data frame.
individualIds: Numeric IDs of individuals for which the results should be extracted. By default, all individuals from the results are considered. If the individual with the provided ID is not found, the ID is ignored.
names: A string or a list of strings assigning new names. These new names can be either for renaming DataSet objects, or for renaming quantities/paths in SimulationResults object. If an entity is not to be renamed, this can be specified as NULL. E.g., in names = list("oldName1" = "newName1", "oldName2" = NULL)), dataset with name "oldName2" will not be renamed. The list can either be named or unnamed. Names act as unique identifiers for data sets in the DataCombined object and, therefore, duplicate names are not allowed.
groups: A string or a list of strings specifying group name corresponding to each data set. If an entry within the list is NULL, the corresponding data set is not assigned to any group (and the corresponding entry in the group column will be an NA). If provided, groups must have the same length as dataSets and/or simulationResults$quantityPath. If no grouping is specified for any of the dataset, the column group in the data frame output will be all NA.

Returns

DataCombined object containing simulated data.

Method `setGroups()`

Adds grouping information to (observed and/or simulated) datasets.

Usage

DataCombined$setGroups(names, groups)

Arguments

names: A list of dataset names which need to be grouped. Note that if you have specified new names while adding datasets (using $addDataSets() and $addSimulationResults() methods), you will need to use these new names to specify group assignment. The same dataset can't be assigned to two different groupings in the same $setGroups() call. In other words, elements of names argument should be unique.
groups: A list specifying which datasets belong to which group(s). Please note that the order in which groups are specified should match the order in which datasets were specified for names parameter. For example, if data sets are named "x", "y", "z", and the desired groupings for them are, respectively, "a", "b", this can be specified as names = list("x", "y"), groups = list("a", "b"). Datasets for which no grouping is to be specified, can be left out of the groups argument. The column group in the data frame output will be NA for such datasets. If you wish to remove an existing grouping assignment for a given dataset, you can specify it as following: list("x" = NA) or list("x" = NULL). This will not change any of the other groupings.

Returns

DataCombined object with grouped datasets.

Method `removeGroupAssignment()`

Remove existing groupings for (observed and/or simulated) datasets.

Usage

DataCombined$removeGroupAssignment(names)

Arguments

names: A list of dataset names whose group assignment needs to be removed. Note that if you have specified new names while adding datasets (using $addDataSets() and $addSimulationResults() methods), you will need to use these new names to specify group assignment. The elements of names argument should be unique.

Returns

DataCombined object with updated group assignments.

Method `setDataTransformations()`

Transform raw data with required offsets and scale factors.

Usage

DataCombined$setDataTransformations(
  forNames = NULL,
  xOffsets = 0,
  yOffsets = 0,
  xScaleFactors = 1,
  yScaleFactors = 1,
  reset = FALSE
)

Arguments

forNames: A list of names specifying which observed datasets and/or paths in simulated dataset to transform with the specified transformations. Default is NULL, i.e., the transformations, if any specified, will be applied to all rows of the data frame.
xOffsets, yOffsets, xScaleFactors, yScaleFactors: Either a single numeric value or a list of numeric values specifying offsets and scale factors to apply to raw values. The default offset is 0, while default scale factor is 1, i.e., the data will not be modified. If a list is specified, it should be the same length as forNames argument.
reset: IF TRUE, only data transformations that are specified will be retained. Not specified transformations will be reset to their defaults. Default behavior is FALSE, e.g., setting only xOffsets will not reset xScaleFactors if those have been set previously.

Details

A data frame with respective raw quantities transformed using specified offset and scale factor values.

For X and Y variables: newValue = (rawValue + offset) * scaleFactor
For error term: newErrorValue = rawErrorValue * scaleFactor

Method `toDataFrame()`

A method to extract a tibble data frame of simulated and/or observed data (depending on instances of which classes have been added to the object).

Note that the order in which you enter different object doesn't matter because the returned data frame is arranged alphabetically by dataset name.

Usage

DataCombined$toDataFrame()

Returns

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

Method `print()`

Print the object to the console.

Usage

DataCombined$print()

Method `clone()`

The objects of this class are cloneable with this method.

Usage

DataCombined$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

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")

# Looking at group mappings
myDataCombined$groupMap
#> # A tibble: 2 x 3
#>   group         name                                                     dataT~1
#>   <chr>         <chr>                                                    <chr>  
#> 1 Aciclovir PVB Organism|PeripheralVenousBlood|Aciclovir|Plasma (Periph~ simula~
#> 2 Aciclovir PVB Vergin 1995.Iv                                           observ~
#> # ... with abbreviated variable name 1: dataType

# Looking at the applied transformations
myDataCombined$dataTransformations
#> # A tibble: 2 x 5
#>   name                                           xOffs~1 yOffs~2 xScal~3 yScal~4
#>   <chr>                                            <dbl>   <dbl>   <dbl>   <dbl>
#> 1 Organism|PeripheralVenousBlood|Aciclovir|Plas~       0       0       1       1
#> 2 Vergin 1995.Iv                                       0       0       1       1
#> # ... with abbreviated variable names 1: xOffsets, 2: yOffsets,
#> #   3: xScaleFactors, 4: yScaleFactors

# Accessing the combined data frame
myDataCombined$toDataFrame()
#> # 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 min   Time       0    µmol~ Concen~      NA
#>  2 Organism|P~ Acic~ simula~       1 min   Time       3.25 µmol~ Concen~      NA
#>  3 Organism|P~ Acic~ simula~       2 min   Time       9.10 µmol~ Concen~      NA
#>  4 Organism|P~ Acic~ simula~       3 min   Time      15.0  µmol~ Concen~      NA
#>  5 Organism|P~ Acic~ simula~       4 min   Time      20.7  µmol~ Concen~      NA
#>  6 Organism|P~ Acic~ simula~       5 min   Time      26.2  µmol~ Concen~      NA
#>  7 Organism|P~ Acic~ simula~       6 min   Time      31.4  µmol~ Concen~      NA
#>  8 Organism|P~ Acic~ simula~       7 min   Time      36.4  µmol~ Concen~      NA
#>  9 Organism|P~ Acic~ simula~       8 min   Time      41.1  µmol~ Concen~      NA
#> 10 Organism|P~ Acic~ simula~       9 min   Time      45.5  µmol~ 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

Object combining simulated and observed data

Note

See also

Super class

Active bindings

Methods

Public methods

Method addDataSets()

Usage

Arguments

Returns

Method addSimulationResults()

Usage

Arguments

Returns

Method setGroups()

Usage

Arguments

Returns

Method removeGroupAssignment()

Usage

Arguments

Returns

Method setDataTransformations()

Usage

Arguments

Details

Method toDataFrame()

Usage

Returns

Method print()

Usage

Method clone()

Usage

Arguments

Examples

Method `addDataSets()`

Method `addSimulationResults()`

Method `setGroups()`

Method `removeGroupAssignment()`

Method `setDataTransformations()`

Method `toDataFrame()`

Method `print()`

Method `clone()`