External Data and Task Results

SimBiology® lets you build models of dynamic systems and perform model analyses using available research data. For instance, you can import time-course data from experiments, preprocess data, and use data in analysis tasks, such as parameter estimation. Task results are generated by each task after it finishes running, and consist of simulation data, summary of simulation options and task settings used during the task run, and plots for data visualization and exploration.

You can import data from several file formats, such as Excel files (.xls, .xlsx), text files (.csv, .txt), and SAS® XPORT files (.xpt). NONMEM®-formatted data are also supported, and SimBiology interprets the columns according to the NONMEM definitions. For details, see Importing Data-Supported Files and Data Types. You can also import grouped data which have multiple groups of observations, such as measured concentrations from multiple patients.

In addition, SimBiology lets you import variables from the MATLAB® workspace. If variables have the same dimension, you can concatenate them horizontally by multiple selection (Ctrl + click or Command + click on a Mac).

You can edit column names while importing. After imported, the names are final, and SimBiology refers to the columns by those names in subsequent workflows such as plotting or fitting the data. To edit, double-click the name of a column in the Data Preview section of the Import dialog box.

Both external data and task results are saved in a SimBiology project (*.sbproj). They are accessible from the project panel in the workspace area of the desktop. Select Project in the address bar and double-click the data set or task result to open it. The desktop then displays the corresponding contents in the workspace area. The next figure shows an example of the project workspace and an external data set when open.

You can visualize data using various built-in plots, such as time or scatter plots. First open the data and select the plot type from the drop-down menu on the Define Plot tab. Then define the corresponding input arguments for the plot. If you have grouped data, you can create a trellis plot where each group is plotted on a separate axis.

To add more plots, select Blank Figure on the Define Plot tab. Plots are shown as separate figure tabs in the workspace area. You can open and close the tabs. To reopen any closed tab, select it from the Open drop-down menu. To remove a figure from the project permanently, select Delete Figure.

The desktop provides built-in tools to help you explore data. For instance, you can take a closer look at a particular area of the plot by zooming in. To query the values of data points, select Data Cursor on the Define Plot tab and then click a data point.

You can also export data to MATLAB workspace as separate variables, a dataset, or SimData object. In addition, you can export task results to a MAT or Excel® file.

External Data

You can open any imported data set from the project panel. Each external data set appears as a table on the Raw Data tab in the workspace area. The table shows the values of each data column. You can classify the columns as a group variable, independent variable, dependent variable, covariate, dose amount, and dose rate variables from the drop-down menu of each column. You can also specify the corresponding unit for each column. SimBiology uses these data classifications accordingly in analysis tasks. For instance, the Group Simulation task uses the independent and dependent variables to plot the data while applying the dose amounts from the dose column to each group during simulation.

The desktop lets you preprocess data by excluding data points, such as outliers. Excluded data points are not used during model analyses such as data fitting. The excluded rows in the data are grayed out on the Raw Data tab. If you have any plots, these data points are labeled as Excluded data. To define exclusion rules or edit existing ones, select Edit Exclusions on the Explore Data tab and enter a valid MATLAB expression. You can refer to the column names in your expressions. Alternatively, you can use the drop-down menus from the exclusion editor to select a column and operator to define the expression. For instance, the next figure shows an expression rule to exclude any data points recorded after Time > 5.

You can transform data to make them easier to visualize or improve interpretability. To add a new column of derived data from one or more existing columns using a MATLAB expression, select Edit Derived Data on the Explore Data tab and enter the expression. For instance, if you want to log-transform the measured drug concentrations, enter log(Conc) where Conc is the name of the concentration column in your data.

The desktop also lets you compare time-course data to simulation results. To compare, add the data to the time plot of simulated quantities in the Live Plots area of the task editor. Right-click the time plot and select Define External Data to Plot.

If you have the time course of measured drug concentrations, you can calculate pharmacokinetic (PK) parameters of the drug using non-compartmental analysis (NCA). To see a table of PK parameters, select Open > NCA on the Define Plot tab. For details, see NCA.

Task Results

Task results are saved as Last Run (task name - model name) after each run. If you rerun the same task, the results are overwritten. To avoid overwriting them, save the results with a different name. Right-click the Last Run result of the task from the project panel in the workspace area and select Save Data.

When you open task results, the desktop shows the Summary tab and other figure tabs in the workspace area. The Summary tab contains the details of the task, such as simulation and compile options used during the task run. Generated plots, that is, plots specified in the Plots to Generate section of the task, are shown in separate tabs. To edit properties of each plot, such as changing x-axis or y-axis to a log scale, select Edit Properties on the Define Plot tab.

In addition to generated plots, you can add new plots to visualize the results in different ways and gain additional insight. For instance, you can explore the relationship between two variables by adding an XY plot or check the quality of a fit with additional residual plots.

To view or export simulation data, select View or Export on the Define Plot tab. You can export the results to the MATLAB workspace and other files, such as MAT or Excel files.

The next figure is an example of simulation task results from a two-compartment model showing the concentration–time profile of a drug in the Central and Peripheral compartments.


You can navigate to the task results panel from the task editor by selecting Go To on the Editor tab. You can also save the task results by selecting Save.

Related Topics