Figure for reporting engine: plot time profile

[KatrinCoboeken]

Figure: plot time profile

Figure is used to compare simulated time profiles with observed data,

Additional it provides a table which contains the simulated properties in numeric format

Arguments:

Data

· Simulation result of one or more individuals

simulationResult = Data.frame/data.table with following columns

o Time (double) vector of time value in unit of display, so no unit conversion is needed

As all individuals of one group will be merged, they should have the same time values

o Value (double) value of the output to show in the unit of display, so no unit conversion is needed

o MinValue (double) optional column for aggregated results, aggregated results may be a mean model prediction with a prediction interval from parameter identification. In this case we would have only one individual per group

o MaxValue (double) optional column for aggregated results

o Individual_ID (Integer) must be unique per group

o Group (ordered factor) (character)

it is used to group individual results,

it is also used for legend (e.g. “Pediatric population”,”Adult Population” or “BAYXXX Parent”, “Bay XXY Metabolit 1”, “BAY XXX Metabolit 2”)

order of factor is used for legend order

· simulationResult.Metadata metada of Simulation Result

List with following entries:

o Time_unit: character (same strings as used by OSP-Suite) s,min,h,day(s),week(s),month(s),year(s),ks

o Value_unit: character

o Aggregation_text: character (default NULL) only used for aggregated data

· Observered Data of one or more individuals or aggregated data sets

Default NULL (-> no observed data available, only simulation results will be plotted)

observeredData = Dataframe/data.table with following columns

o Time (double) vector of time value in same unit of simulation result, so no unit conversion is needed

Data individuals won’t be merged so they can have different time values

o Value (double) value of the output to show in same unit of simulation result, so no unit conversion is needed

o MinValue (double) optional column for aggregated data

o MaxValue (double) optional column for aggregated data

o Identifier (ordered factor) (character) used for legend

o Group (ordered factor) observed data and simulation with corresponding groups will be plotted in the same color

· observeredData.Metadata Metadata of Observed Data

Default NULL (-> no observed data available, only simulation results will be plotted)

List with following entries

o AggregationText : Text which will be added to describe aggregation of data, e.g “data is displayed as mean + SD”

o LLOQ: lower limit of quantification, if not NAN all data values below equal LLOQ will be displayed differently and the LLOQ will be plotted as lien over the time range

FigureConfiguration:

· Xlabel: character ( e.g ‘Time after dose’)

· Xlim: vector of length 2 (e.g c(0,24)), default NULL time range to display, if null range is calculated to cover whole range of simulated results and observed data

· Xticks (vector default NULL)

· Ylabel (e.g. ‘Plasmaconcentration’)

· Yscale: character (default ‘lin’)

· Ylim vector of length 2 (e.g c(0,24)), default NULL time range to display, if null range is calculated to cover whole range of simulated results and observed data

· aggregationMethode_for_mean: rule to aggregate mean of simulated results,

character out of list, see Details aggregationMethode_for_mean

· aggregationMethode_for_range: rule to aggregate plot range of simulated results,

character out of list, see Details aggregationMethode_for_range

· aggregationText (default NULL) only used for aggregated simulation results

· colorscale_groups (default NULL, then take R defaults) defines colors for different groups

· shape_vector (default NULL, then take default) defines shape of data set per identifier

Return:

List with entries

· Figure: Figure object

· Table: table object

Details:

Aggregation of simulated results

Consistency check: For each individual of each group only one value per time point is allowed, else error.

· aggregationMethode_for_mean:

o ‘median’ (default) : calculate median per timepoint and per group

o ‘mean’ : calculate aritmetric mean per timepoint and per group

o ‘geomean’ : calculate geometric per timepoint and per group

o ‘none’ used for simulations of individuals or already aggregated simulation results,

In this case mean is equal value,

Consistency check needed: only one individual per group, else error

· aggregationMethode_for_range: rule to aggregate plot range of simulated results,

character out of list

o ‘90percentRange’: (default) range is defined by 5th-to 95th percentile

o ‘95percentRange’: range is defined by 2.5th-to 97.5th percentile

o ‘MeanPlusSD’: range is defined by arithmetric mean minus standard deviation - arithmetric mean plus standard deviation,

Consistencycheck: should only be used in combination with aggregationMethode_for_mean = ‘mean’, print warning if not

o ‘geoMeanPlusGSD’, geometric mean divided by geometric standard deviation - geometric mean multiplied by geometric standard deviation,

Consistencycheck: should only be used in combination with aggregationMethode_for_mean = ‘geomean’, print warning if not

o ‘none’ used for simulations of individuals, or if only mean without range should be plotted

o ‘usePrecalculated’ used for already aggregated simulation results, range is given in column minValue and maxValue

Consistencycheck: only one individual per group, columns MinValue,MaxValue must exist, else error

Plotting of simulated results

· Plot mean values as line (e.g. geom_line)

· Plot range as area (e.g. geom_area)

· Select color according to group

Plotting of data (optional)

· Plot data as symbols on top of simulated results

· If data are aggregated plot range (e.g. geom_crossbar)

· Set color according to group

· Set shape according to identifier

Legend should contain

· group name of simulation result and data set

· identifier of observed data

· aggregation method of simulated results

· aggregation txt of observed data

Xlabel and Ylabel

· constructed out of arguments Xlabel and X_unit of simulated results ‘Xlabel’ [Unit] if units is empty only ‘Xlabel’

· constructed out of arguments Ylabel and Y_unit of simulated results ‘Ylabel’ [Unit] if units is empty only ‘Ylabel’

Xticks for Time

· Xticks should be set according to x_unit,

e.g if unit is hours use ticks like 6,12,24,…

if unit is second use ticks like 30,60,..

if unit is months use ticks like 12,24,…

see also function setTicksForTimeUnit in file setAxesScaling.m of the Matlab Core Toolbox

Table construction

Construct data.frame with following columns for each group

· simulated time vector, if all groups have the same time vector keep only one

· aggregated mean of group

· Lower Range of aggregated range

· Upper Range of aggregated range

Set meaningful colum names out of X and Y labels and legend entries

[ju-rgen]

From values of one group a set of curves (mean, quantiles, ...) are computed and displayed in the same plot.
E.g. from 20 values for group "study 1" at time 49 h the corresponding values for mean, 90%range are computed and displayed.

"Aggregation text" in Figure configuration may be a doublette of "Aggregation text" in simulation result metadata.

Examples

[msevestre]

@KatrinCoboeken @Yuri05 @ju-rgen I feel that this is NOT the definition of a time profile plot. Rather what is being described here seems to be a much more complicated set of functions.

I think it might be useful to try to split this complex plot into multiple simple plot that could be combined together.

@KatrinCoboeken The description is hardly readable because of peculiar formatting. Could you please reorganize it to use markdown? Thanks

[ThomasGaub]

It would be helpfull to have functions that create automatically this plots from simulated plot result data.

Plotting of simulated population results

• X-Axis: time
• Plot median values as line (y).
• Plot 5th & 95th percentile range as area (yMin, yMax)
• y-Label => from y varianle incl. unit
  plothandle <- plotDefaultPopulationResults(simulationResults, outputPath)
  (later there may be added some simple configuration)

Plotting of data

• X-Axis: time
• Y-Axis: multiple sets of Data
• Plot data as symbols
  plothandle <- plotExperimentaldata(experimentalData) or
  plothandle <- plotExperimentaldata(time,yData)
  also here may adde some simple configuration (e.g. symbol ).

[Yuri05]

@ThomasGaub Please put this in separate feature request(s)