Skip to contents

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

Inherited methods


    Method addDataSets()

    Adds observed data.

    Usage

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

    Arguments

    dataSets

    Instance (or a list of instances) of the DataSet class.

    names

    A string or a list of strings assigning new names to the list of instances of the DataSet class. If a dataset is not to be renamed, this can be specified as NULL in the list. For example, in names = list("dataName" = "dataNewName", "dataName2" = NULL)), dataset with name "dataName2" will not be renamed.

    groups

    A string or a list of strings assigning the data set to a group. 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.

    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 to the quantities or paths present in the entered SimulationResults object. If a dataset is not to be renamed, this can be specified as NULL in the list. For example, in names = list("dataName" = "dataNewName", "dataName2" = NULL)), dataset with name "dataName2" will not be renamed.

    groups

    A string or a list of strings assigning the data set to a group. 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 datsets are named "x", "y", "z", and the desired groupings for them are, respectively, "a", "b", and no grouping, 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 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 (previously specified) 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
    )

    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 names argument.

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

    
    # load the simulation
    simFilePath <- system.file("extdata", "Aciclovir.pkml", package = "ospsuite")
    sim <- loadSimulation(simFilePath)
    simulationResults <- runSimulation(simulation = sim)
    
    # create a new dataset object
    dataSet <- DataSet$new(name = "DS")
    
    # created object with datasets combined
    myCombDat <- DataCombined$new()
    myCombDat$addSimulationResults(simulationResults)
    myCombDat$addDataSets(dataSet)
    
    # print the object
    myCombDat
    #> DataCombined: 
    #> Datasets and groupings: 
    #> 
    #> # A tibble: 1 x 3
    #>   group name                                                            dataType
    #>   <chr> <chr>                                                           <chr>   
    #> 1 NA    Organism|PeripheralVenousBlood|Aciclovir|Plasma (Peripheral Ve~ simulat~