The chart component is used in PK-Sim® as well as in MoBi® . It consists of two views, the chart display and the chart editor. The chart display displays a chart, the chart editor is used to create and edit charts.
By default, the chart editor is auto hidden; when you hover over the vertical chart editor button on the right, the chart editor opens and you can edit the chart settings. To dock the chart editor click the auto hide button
. The button icon then changes to
, and the chart editor is docked. Afterwards, you are able to move the chart editor to other edges as well. To auto hide the chart editor, click the auto hide button
The chart editor consists of several subviews that depend on the number of tabs specified in the chart layout and that comprise:
- the data browser table for browsing and selecting data to be displayed in a chart,
- the curves table and the axis table in the tab Curves and Axis Options for editing curve and axis properties,
- the tab Chart Options for editing chart properties like title, legend position or back color.
- the tab Chart Export Options for editing chart and font sizes used when exporting a chart.
The most frequently edited chart elements, axes and curves, can be edited directly from the chart display without using the chart editor. Just double click the axis or curve you want to edit or right click and select Edit from context menu.
For a better understanding of the workflows and features of the chart component, we briefly introduce some chart basics. Charts are used to visualize data. In the Open Systems Pharmacology Suite, data consists of time series from simulation and measurements. Charts consist of axes and curves. Typically, the x-axis has the dimension time and the y-axis to dimension concentration.
Curves are based on time series, mostly one curve corresponds to a single time series, in this case the x-values represent the time axis and the y-values are the corresponding functional values of the time series. However, curves can also correspond to two time series with the same time scale, in this case the x-values are the values of the first time series and the y-values are the values of the second time series. Thus, for example, concentrations can be plotted against other concentrations.
Creating a chart consists of selecting the data and editing the curve / axis / chart settings. The chart settings and chart export settings can be reused to create uniform charts for a sequence of simulation projects.
In the next sections, we describe the basic workflow and the subviews in detail.
Creating a chart consists of two steps:
- 1.Select the data for the curves in the data browser.
- 2.Edit the chart settings
- Edit curve options,
- Edit axis options,
- Edit chart options.
We describe these steps in the following subsections.
The data browser contains one row for each available time series. Depending on the complexity of your model, there can be thousands of rows. (For convenience, trivial time series with the constant value 0 are automatically excluded.)
Properties of the time series are displayed in the columns of the data browser, e.g., Organ/Container, Compartment, Molecule, Name, Dimension, Used.
To organize these data there are three concepts, which we describe here only briefly.
- Grouping - you can group by a column by dragging it from the column headers to the so called grouping area and vice versa.
- Sorting - you can sort by a column by just clicking on the column header.
- Filtering - you can filter a column by moving the mouse to the right side of the column header and clicking on the filter symbol, which appears.
Right-click on the column header to get a context menu with more options.
In the figure below, data are grouped hierarchically by organ and compartment, they are sorted by molecule and filtered by the condition Dimension = 'Concentration'.
To select data:
- 1.organize your data according to your needs,
- 2.do one of the following:
- Check the checkboxof a row in the used column,
- Drag a row from the data browser to the curves table,
- Select multiple rows by holding the CTRL or the SHIFT key when clicking them and drag them together to the curves table or check the checkbox Use selected in the right upper corner of the Chart Editor.
- 1.Repeat step 2 until your data selection is complete.
The creation of charts with alternative x-values, e.g., other concentrations, is explained in “Using Alternative X-Values”.
After selection, the corresponding curves are automatically shown and listed in the curves table.
To deselect data, do one of the following:
- Uncheck the checkboxof the row in the used column of the data browser,
- Click the Delete buttonon the right side of the curve row in the curves table.
- Click the row header on the left side of the row to select the curve row and press Delete.
When a Parameter Identification or Simulation chart is open, the data are first grouped by their category and the checkbox Link Data to Simulations is displayed. Selecting this check box links the observed data to the simulation outputs they are mapped to. When the checkbox is selected, (un)selecting a simulation output will result in the (un)selecting corresponding observed data.
The view for PI and Simulation Charts
The properties of the curves can be edited in the curves table. Each curve is displayed in one row, and the properties of the curves are displayed in different columns.
The most important columns are:
If a row header or cell content cannot be fully displayed, the full content is shown in a tooltip when you hover with the mouse over that field, as shown below:
In the “Curves and Axis Settings” Tab of the Chart Editor a new context menu item has been added called “Edit options for selected”. It is only visible when the user has selected at least two rows in the curves table.
Edit Multiple Curves Context Menu
Selecting this option opens a new dialog listing the common options of the curves. Initially the values for the options are not set, and if the user leaves one of the options in this initial state, that option will not be edited – meaning that the selected curves will retain for that option the value they had before opening the dialog.
Edit Options Dialog
Often you may want to use the same color for different curves, e.g. for curves of the same molecule or organ or for observed data.
You can easily copy the color from one curve to another by just dragging the color symbol from one curve to the color field of another curve. During the dragging process, a + symbol is shown.
If you want to color different curves - for instance of observed data - with the same color, you can also use the Default Color of the y-Axis.
- 1.In the axes table, select the column Default Color in the column chooser (right click on column header).
- 2.Change the Default Color for the corresponding y-Axis to the intended color.
- 3.Select the curves from the data browser.
- 4.Reset the Default Color for the y-Axis to White which deactivates default color.
A tab called "Curves Color Grouping" is displayed in the charts with observed data sets. In the tab the user can select one or more metadata, according to which the observed data sets will be grouped and given the same color. Clicking the “Apply Color Grouping” button changes the color of the observed data sets in the chart according to the selection, and then the selection is cleared. The user can then choose a new selection of metadata and change the coloring once again.
Color Grouping Tab
When adding observed data sets to a chart via drag-and-drop of a folder (or multiple folders), all data sets within one folder can be assigned to a single color. This behavior is optional and can be changed by (un)selecting the checkbox "Color by folder when adding to chart" in the context menu of the “Observed Data” entry of the building blocks explorer. This setting is a central configuration and applies for all subfolders.
Color Grouping Option Context Menu
Alternatively, this feature can be toggled on and off from the User Settings, under “Utilities” -> “Options” -> “General” -> “Colors”:
Color Grouping Option In Settings
When this option is selected and whole folders are dragged and dropped into a plot, the observed data from the same folders will be assigned the same color. However, when the user selects individual observed data sets instead of folders and drags and drops them on the plot, then each one will be assigned a new color, and they should not be grouped according to the folder they belong to.
To make you legends clear and readable - especially when exporting them - you can do the following
- Edit the curve name.
Curve names are automatically composed (in MoBi you can control the curve name composition via some settings in the Chart Options). Mostly, not all information contained by default is relevant in a certain situation and therefore the names should manually be reduced or renamed to contain the relevant information.
(If, after renaming you, are in doubt about the data of your curve you can always identify it by selecting the column y-Data from the column chooser of the curves table.)
- Hide needless legend entries in particular for multiple observed data sets.
If you do not intend to refer to single individuals, uncheck the checkbox In Legend for all but one observed data set.
- Reorder your legend entries to show the most important entries on top.
You can reorder them directly in the legend by dragging the line symbol to another symbol which moves the legend entry of the dragged curve just above the entry where it is dropped.
You can reorder them also by dragging the row headers (the small gray area on the left of a row) in the curves table.
You can edit properties of axes in the axes table. There is always one unique x- axis and one y-axis. You can add up to 2 additional y-axes by clicking the button on the right end of the y-axis row. Each axis is displayed in one row, and the properties of the axes are displayed in different columns.
You can select columns which are hidden by default using the Column Chooser and right click on the column header. The most important columns are:
The Min and Max values are overridden by zooming the chart.
You can edit the properties of the chart in the chart options tab.
You can export charts to the Working Journal or other applications by copy & paste. To copy the chart, just right click into the chart area and select Copy to clipboard.
You can define the size of the exported chart in the Chart Export Options. Then, the exported chart is independent of the current size of the application window. You can also define the font sizes of the exported chart to get readable legend entries in your slides for example.
In the Chart Export Options tab, you can select Preview these settings in Chart Display to preview any changes you have made in the settings of the Chart Export Options. You can select Include origin data and show the title of the PK-Sim® or MoBi® file, the name of simulation and the date of creation beneath the Chart®, as illustrated in the image below. This can be useful for example, if you want to refer to the simulation state used in a chart in a presentation.
Chart Export Options
You can edit the following properties of the exported chart in the tab Chart Export Options.
To zoom into the chart, do one of the following:
- Hover the mouse over the chart. A zoom symbol appears. Press the left mouse button and drag the mouse to select a rectangle. Release the mouse button to zoom into the selected rectangle.Image
- Explicitly define the range to be displayed in the Min and Max columns in the Axis Options.
- Use the mouse wheel while the mouse pointer is located in the chart area.
To reset the zoom right click on the chart area and select Reset Zoom (Ctrl+0) or use the shortcut Ctrl+0 (Do not use the 0-key from the numeric block, but from the typewriter keys.).
You can save the chart settings (Chart Options and Chart Export Options, Curve and Axes Options) in different Chart Templates and reuse them in a simulation. This is useful for example, if you want to switch between different settings. You can also save and load these Chart Templates to files and reuse them in other simulations.
- in PK-Sim®, the Chart Templates are reusable in any clone of a simulation,
- in MoBi®, the Chart Templates and Curves Selection are part of the Building Block Simulation Settings and can be reused like any other Building Blocks.
The chart manager can be accessed directly from the chart editor after running a simulation. The following options are available:
- Apply Template: choose from a list of saved templates,
- Create New: create a new template based on current settings for data, curves, axis and chart options,
- Update Existing: changes the settings for the template to the current settings for data, curves, axis and chart options,
- Manage Templates: brings you directly to the chart template manager that displays an overview of all settings in a template which can all be edited.
Accessing chart templates and chart manager from the chart editor
In the chart manager, templates can be managed in the left hand side window and settings for an individual template can be edited in the two right hand side windows.
Management and editing of chart templates in the chart manager
The following options are available for managing templates:
- Clone: useful when changing specific settings based on an existing template.
- Save template to file: allows you to reuse this template in another simulation settings building block, simulation or project.
- Delete template
In addition, a template can be loaded as .xml file using the
In the right panel, the user can specify which curve will be selected as output and how it will be displayed.
An automated algorithm is implemented that decides which curves are selected when a certain template is chosen. Decision criteria are based on the output path (Y-Path) and the output type (Y-Type). The following decision scenarios are feasible:
- If a selected output matches both, Y-Path and Y-Type, it will be selected and the curve name will be used as is.
- A selected output matches the Y-type, but not the Y-Path of a template. The Y- Path of the output is for example Organism|Venous|Blood|Plasma|Diclofenac. The algorithm will then try to find all output located in the container Organism| Venous|Blood|Plasma. If only one output is found, the curve name will be used as is. If two or more outputs are found, the curve name will be ignored and a new unique name will be generated based on the actual path of the output. Sometimes, this heuristic approach might result in many selected curves at once. If more than ten curves will be selected, the user will be asked whether be wants to proceed or choose a different template for display of the selected output curves.
All changes to a template or selection of output are made at the level of an individual simulation. The simulation settings for the project remain unchanged, until the user explicitly updates the changes to the project simulation settings building block using the context menu as shown below.
Changes in the simulation setting can be committed to the settings at the project level
You can select one of the following predefined editor layouts:
Save your preferred Editor Layout to your user settings. Just select Save to User Settings from the Layout menu at the top of the Chart Editor.
In this layout are stored the selected view and column settings in the subviews like visibility, order, column width and grouping.
As mentioned in the introduction of this section, typically one curve corresponds to a single time series in which the x-values represent the time axis and the y- values are the corresponding functional values, such as concentration.
Concentration versus Time Plot
However, curves can also correspond to two time series with the same time scale. In this case, the x-values are the values of the first time series and the y-values are the values of the second time series. Thus, concentrations can be plotted against another concentration or a fraction of the dose, for example.
To select other x-values than the default ones, do the following (you can skip steps 1 and 2 when using the editor layout Variable x-Axis View):
- 1.Show the x-Data column in the curves table. In detail:
- 1.Right-click on the columns header row of the curves table.
- 2.Select Column Chooser.
- 3.Drag the x-Data (and y-Data, if you like) to a position between two other column headers in the header row.
- 4.Close the Column Chooser.
- 2.Show the dimension column in the axis table (like in step 1) and in the data browser.
- 3.Drag the time series with same the time scale and the intended values from the data browser to the x-Data field of the desired curve in the curves table.An error symbol appears at the x-Data field, because now the x-Data and the x-axis have different dimensions, which cannot be resolved automatically.Image
- 4.Change the Dimension of the x-axis in the Axis Table to the dimension of the x-values manually.
- 5.Change curve or x-axis caption according to your needs. Now the concentration is plotted against the selected x-values.
Concentration versus Concentration Plot
In MoBi®, you can change the default editor layout and the default curve name generation in the Chart Options tab within the User Settings dialog (click
Options in the Utilities ribbon tab).
All options here are stored in the user settings and apply for newly opened charts and curves.