Figure for reportinge engine: PK Ratio plot

Scatter plot showing {X-value; predicted/observed value} data pairs and X-fold range bounds.Example plots:

grafik grafik

Inputs:

Data: list of groups. Per group: list of value triples (All values will be plotted AS IS (no unit conversion etc.)
- X-value (typically Age; othe dimensions possible)
- predicted value
- observed value
Meta data:
- Per data group:
- Symbol
- Colour
- Caption for plot legend
- Plot configuration:
- Plot caption
- Optional: plot size (always in pixels or allow other units?)
  - Width (if not given: use "page width" - if such setting vailable in R)
  - Height (if not given: use default (what should it be?))
- Optional: fonts properties
  - Axis captions font size
  - Legend captions font size
  - Watermark font size
- Optional: Watermark (text) (should it be defined here or only during printing to the target output device, s. #34 ?)
- Optional: Legend position (None, Inside top right, Inside bottom right, ...)
- X-Axis settings
  - Caption
  - Scaling (Log/Lin)
  - Optional: MinValue (Default: Minimum over all X-Values)
  - Optional: MaxValue (Default: Maximum over all X-Values)
  - Optional: X-ticks
- Y-Axis settings
  - Caption
  - Scaling (Log/Lin/Log AND Lin). If Log AND Lin is selected: 2 plots will be created, one with Y-axis in log scale and one with Y-axis in lin scale
  - Optional: MinValue
  - Default: in Lin-scale: 0
  - Default in Log scale:
    - 0.1 if minimum over all predicted/observed is > 0.1
    - next lowest logarithmic tic smaller than minimum over all predicted/observed, otherwise
  - If MinValue passed by the user is bigger than the default above: use default! (with warning?)
  - Optional: MaxValue
  - Default (both Lin and Log scale):
    - 3 if maxmum over all predicted/observed is <3
    - next highest tic bigger than maximum over all predicted/observed, otherwise
  - If MaxValue passed by the user is smaller than the default above: use default! (with warning?)
  - Optional: Y-ticks

Output plot(s):

solid line const 1
dashed lines const 0.67 and 1.5 (1.5 fold)
dashed lines const 1.5 and 2 (2 fold)
pairs {X_i; Predicted_i/Observed_i}

Dataframe Probably one dataframe with observed and simulated values (needs alignment with QP) Standardization of the most often used columnnames is welcome (e.g. to define Time as default for X axis), but in principal free choice of column names.

Jürgens opinion: aggregation of values from different rows for e.g. box whisker plots is ok, but calculation of values from different parameters should be done before plot. Each parameter to be displayed should be contained in one column, then metadata can be attached to that column or each data column corresponds to one row in a metadata dataframe. Juri: perhaps computation of e.g. ratio should be possible.

Datatable could e.g. have columns: (Time), IndividualID, Gender, Age, Compound, Dose, PKParameterType, Observed, Predicted, (Ratio)

For Concentration profile e.g. columns (Time), IndividualID, Gender, Age, Compound, Dose, Compartment, Concentration Observed, Concentration Simulated,

There are other options for a table: Not one column per parameter, but a column ParameterValue (or two columns SimulatedValue, ObservedValue) and a column ParameterName. But at least two challenges with this format exist:

Metadata cannot be stored per column, but needs to be integrated into table,
In ggplot seems to be required, one column per displayed(!) parameter.

Data mapping

X - Age
Color - (Compound, Dose) : For grouping a general concept is important, because it is used in many plot types
Symbol - Gender
Size - Gender
Y - Ratio

Metadata Metadata is necessary to describe data, to make information out of the data; Configuration just how(!) the information is displayed. ? Metadata in dateframe or at some column properties/attributes ?

Default template for X axis caption should be " []" could be overridden by user. In PK Ratio plot no units for y Axis seem to be used (which is exceptional) When grouping by Gender, codeDecodeList can/should be used for labels of groups

Example: dataframe for metadata with columns columnName, dimension, unit, LLOQ, codeDecodeList, aggregationMethod Age time years NA NA NA Gender NA NA NA 1,MALE;2,FEMALE NA AUC observed, ?AUC?

Question to both(!) groups QP and SPM: Could we save the codeDecodeList by requesting Decode values in the data table. Jürgen assume: QP will insist on code values as this is the principle in Nonmem Files.

Plot configuration

Configuration CoordinateSystem Values-Layout-Mappings (e.g. (Compound, Dose) - Color, Gender - Symbol/Size) ....

CoordinateSystem XAxis : Axis YAxis : Axis

Axis Scaling Range ...

Range Mode (to allow automatic computation from values or computation from values with minimal/maximal bounds or .... ) Min Max ...

Legend Font Position N_Columns ? (for multicolumn display) Autosize ? ...

Watermark Font Transparency ...

Font Family (Arial, ...) Size Face (Bold, Italic, ...) Color ...

By default there should be used fixed lists, e.g. for color, symbol, etc. But it should be possible to specify e.g. colors for the possible group values Idea: TLF-Library has a function to return values-mapping for (composed) group values after defining dataframe and datamapping User then should be able to modify this values-mapping and pass it to the configuration object.

For Legend build one list of all value combination (here for all ((Compound,Dose),Gender) combinations will a colored and sized symbol computed and displayed) The user can define a string template with tags to override the default: " - - ",

plotPKRatio <- function( data, metadata, datamapping, plotconfiguration )

data

1 to N tables (data frames) with arbitrary columns.

all tables must have the same structure (column names, column data types)
Usage (interpretation) of columns and data is given by metadata, data mapping and plot configuration as described below

example for PK Ratio plot: 2 tables; the first one for AUC Ratio, the second for CMAX Ratio

_IndividualID	_Population	_Gender	_Age	_Compound	_Dose	_Organ	_Compartment	_Simulated	_Observed	_Ratio
₁	_Asian	_M	₁	_Aspirin	₂	_VenousBlood	_Plasma	₂	₄	_0.5
₂	_Asian	_F	₂	_Aspirin	₃	_VenousBlood	_Plasma	₃	₄	_0.75

_IndividualID	_Population	_Gender	_Age	_Compound	_Dose	_Organ	_Compartment	_Simulated	_Observed	_Ratio
₁	_Asian	_M	₁	_Aspirin	₂	_VenousBlood	_Plasma	₁₂	₁₀	_1.2
₂	_Asian	_F	₂	_Aspirin	₃	_VenousBlood	_Plasma	₉	₈	_1.125
₃	_Asian	_F	₃	_Aspirin	₄	_VenousBlood	_Plasma	₅	₅	₁

Metadata

("per column" attributes describing the data)

Units and Dimensions (always assuming the same unit per column!; dimensions are used for display only! Thus not necessarily the internal names should be used )
- "Table1.Age"▶️ {"Age"; "days"}
- "Table2.Age"▶️ {"Age"; "days"}
- "Table1.Dose"▶️ {"Dose"; "mg/kg"}
- "Table2.Dose"▶️ {"Dose"; "mg/kg"}
- "Table1.Simulated" ▶️ {"AUC; "mg*min/ml"}
- "Table2.Simulated" ▶️ {"Concentration; "mg/ml"}
- "Table1.Observed" ▶️ {"AUC; "mg*min/ml"}
- "Table2.Observed" ▶️ {"Concentration; "mg/ml"}
- "Table1.Ratio" ▶️ {"Dimensionless; "mg/ml"}
- "Table2.Ratio" ▶️ {"Dimensionless; "mg/ml"}
- ...
LLOQ
- "Table1.Observed" ▶️ 0.1 (ALWAYS assuming the same unit as in the Units-section!!!)
- "Table2.Observed" ▶️ 1.3
- …
Value Mappings (or do it BEFORE calling the plot function?)
- "Table1.Gender": {"M"▶️"Male", "F"▶️"Female"}
- "Table2.Gender": {"M"▶️"Male", "F"▶️"Female"}

Data Mapping

Axes (defines which columns of the data table(s) should be plotted)
- "X"▶️"Age" (exactly one column)
- "Y"▶️{"Ratio"} (multiple columns possible)

Unit for the x-axis-column must be the same in all tables. Question: how many axes would we like to allow for Y? 2? 3? arbitrary?

Groupings and Value<=>Layout Mapping (defines combination of columns which identify graphical properties such as color, symbol, line width, symbol size, ...) e.g.
- Colour ▶️ {"Compound", "Dose"}
Compound Dose Colour

Aspirin 2 Blue

Aspirin 3 Red
- Symbol ==> {"Gender"}
Gender Symbol

M Circle

F Asterisk
- Size ==> {"Age"}
- … (Line style, line thickness, …)

Compound	Dose	Colour
Aspirin	2	Blue
Aspirin	3	Red

Gender	Symbol
M	Circle
F	Asterisk

Remarks

Value<=>Layout Mapping is based on Grouping-Information
For each property above (Color; symbol, …)
- User can define only PARTS of Value<=>Layout Mapping (or no mapping at all).
- All missing entries will be automatically filled by the TLF Library
TLF library should provide functions, which would retrieve the default mapping for a data table, property and grouping. E.g. for the data table above getDefaultLayoutMapping(data, "Colour", {"Compound", "Dose"}) would return something like

Compound Dose Colour

Aspirin 2 Green

Aspirin 3 Blue

Compound	Dose	Colour
Aspirin	2	Green
Aspirin	3	Blue

With that, user could e.g. adjust just a few entries in the layout table and pass it to the plot function

Plot configuration

Legend
- Captions
- Option 1: select general caption based on placeholders using all (or some) of the Grouping columns
  - e.g. {Compound}-{Dose}-{Gender}-{Age} or {Compound}-{Dose}-{Gender}
- Option 2: provide captions table for all combinations, e.g.
  
  Compound Dose Gender Age Caption
  
  Aspirin 2 M 1 Aspirin-2mg-Male
  
  Aspirin 3 F 2 Aspirin-3mg-Female
- Position (inside/Outside/None, left/right, top/bottom)
- Font
- Autosize?
- Remarks
- Similar to Value<=>Layout Mapping, user can define only PARTS of legend captions (or no captions at all).
- All missing entries will be automatically filled by the TLF Library
- TLF library should provide functions, which would retrieve the default captions for a data table and all grouping columns. E.g. for the data table above getDefaultCaptions(data, {"Compound", "Dose", "Gender", "Age"}) would return something like
  
  Compound Dose Gender Age Caption
  
  Aspirin 2 M 1 {Compound}-{Dose}-{Gender}-{Age}
  
  Aspirin 3 F 2 {Compound}-{Dose}-{Gender}-{Age}

Compound	Dose	Gender	Age	Caption
Aspirin	2	M	1	Aspirin-2mg-Male
Aspirin	3	F	2	Aspirin-3mg-Female

Compound	Dose	Gender	Age	Caption
Aspirin	2	M	1	{Compound}-{Dose}-{Gender}-{Age}
Aspirin	3	F	2	{Compound}-{Dose}-{Gender}-{Age}

With that, user could e.g. adjust just a few entries in the captions table and pass it to the plot function

Axes
- X-Axis:
- Scaling (Log/Lin)
- Caption
  - If not set: e.g. {Column} [{Unit}] (to be discussed)
  - Can be set using place holders (e.g. {Column} [{Unit}] or {Dimension} [{Unit}] )
- Ticks (Optional)
- Range
  - Min: if empty, min(data) will be used
  - Max: if empty, max(data) will be used
  - Mode
  - Data_And_Bounds (TODO find a good name)
  - Bounds_Only (TODO find a good name) E.g. in PK-Ratio it could be [min(0; min(data))..max(3; max(data))]
- X-Axis: same as X (with the exception, that MULTIPLE columns can be mapped, thus {Column}Placeholder is not possible?)
Watermark (not sure, if it's a plott-setting or global TLF-Library-setting)
- Text (optional)
- Font
- Angle?
- Position? (not required in my opinion, should be always centered)

I really would suggest to use as often as possible the philosophy used by the R function ggplot. If I understand it correctly, this is not done for the legend. E:g. If you have in a plot 10 age Groups and 2 genders and Age is specified by Color and gender by shape ggplot would generate a combined legend with 10 entries for Color and 2 for shape with short descriptions, where as in the current implementation a legend with 20 entries with Long combined description. The ggplot implementation has following pros:

It is easier to understand for the user
It uses less space
It is already implemented and validated
If you add another layer to the ggplot object, it will be automatically updated.

@KatrinCoboeken I do not understand what you mean. Can you show us an example of what you think is happening and what should happen?

This is what the current implementation creates at the moment

when using the following configuration PKRatioDataMapping$new(colorGrouping = "Gender", shapeGrouping = c("Dose", "Compound"))

Great, That’s exactly what I want to have. I had a discussion with Juri where I got another impression. But this is perfect.

Best, Katrin

Von: Michael Sevestre [mailto:notifications@github.com] Gesendet: Dienstag, 17. September 2019 15:23 An: Open-Systems-Pharmacology/TLF-Library Cc: Katrin Coboeken; Mention Betreff: Re: [Open-Systems-Pharmacology/TLF-Library] Figure for reportinge engine: PK Ratio plot (#12)

@KatrinCoboekenhttps://github.com/KatrinCoboeken I do not understand what you mean. Can you show us an example of what you think is happening and what should happen?

This is what the current implementation creates at the moment [image]https://user-images.githubusercontent.com/1041237/65045412-ba5dab00-d92c-11e9-9bfc-9835cf63dd3d.png

when using the following configuration PKRatioDataMapping$new(colorGrouping = "Gender", shapeGrouping = c("Dose", "Compound"))

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/Open-Systems-Pharmacology/TLF-Library/issues/12?email_source=notifications&email_token=AGZ5W2MDCTCMBKTVVHOCSBDQKDK4JA5CNFSM4H55PJAKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD64QFCQ#issuecomment-532218506, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AGZ5W2PORZT7OSHFPVE7ID3QKDK4JANCNFSM4H55PJAA.

From what I tested you can do both:

if you specify color, size and shape from separate variables, you can have separate legends as done above.
if you specify the same input or use the input group from ggplot it will plot only one legend

Open-Systems-Pharmacology / TLF-Library