[Implemented] Specification for plotObservedVsSimulated()

[IndrajeetPatil]

Related to #674

Signature

# `...` will be parameters to control annotations and aesthetics of the plot
plotObservedVsPredicted(dataCombined, ...)

Implementation plan

data <- toObservedVsPredictedDataFrame(dataCombined)

tlf::plotObsVsPred(data, ...) 

Rough expected output:

Decision points:

N.B. The option already rejected by the team is scratched out.

• Pairing non-existing data: threshold versus interpolation
• Nature of the needed function to extract needed dataframe: Member method versus function
• Data format returned by respective function: wide versus tidy

Tasks

Each task will get its own PR.

• Implement toObservedVsPredictedDataFrame() function
• Implement plotObservedVsSimulated()

[IndrajeetPatil]

As for wide versus tidy, you need the data to be in the wide format irrespective of what package you choose, doesn't matter if it's tlf, ggplot2, or base. Paired data that needs to be plotted as a scatterplot will always have to be in wide format. It will be confusing for the users for it not to be.

# tlf
plotObsVsPred(
  data = df,
  dataMapping = ObsVsPredDataMapping$new(
    x = "yValuesObserved",
    y = "yValuesPredicted",
  )
)

# ggplot2

ggplot(df, aes(yValuesObserved, yValuesPredicted)) + 
  geom_point()

# base

plot(df$yValuesObserved, df$yValuesPredicted)

[IndrajeetPatil]

@PavelBal Should the labels for this plot contain information about dimensions and units, like in profile plots?
E.g., Observed values (Fraction [%]) and Simulated values (Fraction [%]).

[PavelBal]

Should the labels for this plot contain information about dimensions and units, like in profile plots?

Yes

And let's rename it to plotObservedVsSimulated.

[IndrajeetPatil]

In profile plots, datasets that are not part of any group are assigned to their own group.

But, in case of the current function, those datasets should be left out of the plot, correct?

In the example plot, e.g., there are no datasets included in the plot that don't belong to any group.

[PavelBal]

Each plotted "data set" is a combination of simulation results and observed data.

So even in case of multiple observed data are assigned to the same group, but no simulatio result, these data are not to be plotted.

The same goes for simulated results - if multiple simulated results are in one group, but no observed data - do not consider.

Maybe like this:

Name	Type	Group
Sim1	Simulated	GroupA
Sim2	Simulated	GroupA
Obs1	Observed	GroupB
Obs2	Observed	GroupB
Sim3	Simulated	GroupC
Obs3	Observed	GroupC
Sim4	Simulated	GroupD
Obs4	Observed	GroupD
Obs5	Observed	GroupD
Sim5	Simulated	GroupE
Sim6	Simulated	GroupE
Obs7	Observed	GroupE
Sim7	Simulated	GroupF
Sim8	Simulated	GroupF
Obs8	Observed	GroupF
Obs9	Observed	GroupF
Sim9	Simulated
Obs10	Observed

Will result in following pairs:

• Sim3 - Obs3
• Sim4 - Obs4
• Sim4 - Obs5
• Sim5 - Obs7
• Sim6 - Obs7
• Sim7 - Obs8
• Sim8 - Obs8
• Sim7 - Obs9
• Sim8 - Obs9

[msevestre]

What about a warning when the dataset are being discarded so that the user knows, that something is not quite right?

[PavelBal]

I personally do not see a necessity for a warning, but if you think so..

[msevestre]

Well the user is doing something that in the context of the function, does not make sense. While I don't think error is necessary, warning can help learning the API better.

[IndrajeetPatil]

How about the following?

The .removeUnpairableDatasets() will be internally used by plotObservedVsSimulated().

library(dplyr)

df <- dplyr::tribble(
  ~name, ~dataType, ~group,
  "Sim1", "Simulated", "GroupA",
  "Sim2", "Simulated", "GroupA",
  "Obs1", "Observed", "GroupB",
  "Obs2", "Observed", "GroupB",
  "Sim3", "Simulated", "GroupC",
  "Obs3", "Observed", "GroupC",
  "Sim4", "Simulated", "GroupD",
  "Obs4", "Observed", "GroupD",
  "Obs5", "Observed", "GroupD",
  "Sim5", "Simulated", "GroupE",
  "Sim6", "Simulated", "GroupE",
  "Obs7", "Observed", "GroupE",
  "Sim7", "Simulated", "GroupF",
  "Sim8", "Simulated", "GroupF",
  "Obs8", "Observed", "GroupF",
  "Obs9", "Observed", "GroupF",
  "Sim9", "Simulated", NA,
  "Obs10", "Observed", NA
)

.removeUnpairableDatasets <- function(data) {
  # How many rows were originally present
  originalDatasets <- unique(data$name)
  
  # Remove datasets that don't belong to any group.
  data <- dplyr::filter(data, !is.na(group))
  
  # Remove groups (and the datasets therein) with only one type (either only
  # observed or only simulated) of dataset.
  data <- data %>%
    dplyr::group_by(group) %>%
    dplyr::filter(length(unique(dataType)) > 1L) %>%
    dplyr::ungroup()
  
  # How many rows are present after filtering
  finalDatasets <- unique(data$name)
  
  # Warn the user about the filtering if it took place
  if (length(finalDatasets) < length(originalDatasets)) {
    missingDatasets <- originalDatasets[!originalDatasets %in% finalDatasets]
    
    message(
      "Following non-grouped or unpairable datasets have been removed:\n",
      paste0(missingDatasets, collapse = "\n")
    )
  }
  
  return(data)
}

df <- .removeUnpairableDatasets(df)
#> Following non-grouped or unpairable datasets have been removed:
#> Sim1
#> Sim2
#> Obs1
#> Obs2
#> Sim9
#> Obs10

df
#> # A tibble: 12 x 3
#>    name  dataType  group 
#>    <chr> <chr>     <chr> 
#>  1 Sim3  Simulated GroupC
#>  2 Obs3  Observed  GroupC
#>  3 Sim4  Simulated GroupD
#>  4 Obs4  Observed  GroupD
#>  5 Obs5  Observed  GroupD
#>  6 Sim5  Simulated GroupE
#>  7 Sim6  Simulated GroupE
#>  8 Obs7  Observed  GroupE
#>  9 Sim7  Simulated GroupF
#> 10 Sim8  Simulated GroupF
#> 11 Obs8  Observed  GroupF
#> 12 Obs9  Observed  GroupF

^{Created on 2022-05-09 by the reprex package (v2.0.1.9000)}

Also, to be consistent with DataCombined, I am producing a message instead of a warning (cf.

OSPSuite-R/R/data-combined.R

Lines 544 to 555 in e2e1e65

	specifiedNames <- unique(groupData$name)
	currentNames <- unique(private$.dataCombined$name)
	# Inform the user about which datasets are missing
	if (!isIncluded(specifiedNames, currentNames)) {
	missingNames <- specifiedNames[!specifiedNames %in% currentNames]
	message(
	"Following datasets were specified to be grouped but not found:\n",
	paste0(missingNames, collapse = "\n")
	)
	}

).

[msevestre]

Message vs warning? What's the difference?
And why not a warning?

[IndrajeetPatil]

Message vs warning? What's the difference?

cf. https://adv-r.hadley.nz/conditions.html#signalling-conditions

And why not a warning?

Because nothing has gone wrong in these functions. We are just informing users that we did something on their behalf. They could have removed these datasets before using this function. But, since they didn't, we are doing it for them. So this should be a message.

[msevestre]

I think it's not a clear line. Something has gone wrong because the function could not process the input. At any rate, this is fine. But make sure to move, as always, the message to the constant files

[IndrajeetPatil]

Is this in the ballpark of what you had in mind?
(The pattern for distal group looks odd, but I am not sure if it's due to interpolation not working as expected or because the dataset itself is messy.)

library(ospsuite)

# load the simulation
sim <- loadTestSimulation("MinimalModel")
simResults <- importResultsFromCSV(
  simulation = sim,
  filePaths = getTestDataFilePath("Stevens_2012_placebo_indiv_results.csv")
)

# import observed data (will return a list of DataSet objects)
dataSet <- loadDataSetsFromExcel(
  xlsFilePath = getTestDataFilePath("CompiledDataSetStevens2012.xlsx"),
  importerConfiguration = loadDataImporterConfiguration(getTestDataFilePath("ImporterConfiguration.xml"))
)

# create a new instance and add datasets
myCombDat <- DataCombined$new()
myCombDat$addSimulationResults(
  simResults,
  quantitiesOrPaths = c(
    "Organism|Lumen|Stomach|Dapagliflozin|Gastric retention",
    "Organism|Lumen|Stomach|Dapagliflozin|Gastric emptying",
    "Organism|Lumen|Stomach|Metformin|Gastric retention"
  )
)

myCombDat$addDataSets(dataSet)

myCombDat$setGroups(
  names = c(
    "Organism|Lumen|Stomach|Dapagliflozin|Gastric emptying",
    "Stevens_2012_placebo.Sita_dist",
    "Organism|Lumen|Stomach|Dapagliflozin|Gastric retention",
    "Stevens_2012_placebo.Sita_proximal",
    "Organism|Lumen|Stomach|Metformin|Gastric retention",
    "Stevens_2012_placebo.Sita_total"
  ),
  groups = c("distal", "distal", "proximal", "proximal", "total", "total")
)

# default
plotObservedVsSimulated(myCombDat)

[pchelle]

@PavelBal
What should be the expected behaviour for linear scaled obs vs pred plots ?

• 1. Keep a fold distance approach with additional lines looking like this
     
• 2. Using an absolute error instead of fold distance (with potential change of input argument e.g. errorRange ?) as below
     

[PavelBal]

@pchelle i.

[IndrajeetPatil]

@pchelle Any update on this? Will you be making these changes in tlf itself? Thanks.