SimData

Simulation data

Description

The SimData object contains simulation data, which includes time and state data, as well as metadata, such as the types and names for the logged states or the configuration set used during simulation.

You can access time data, state data, and metadata stored in the object through the object properties. Use dot notation to query the object properties or change properties that are not read-only. You can also use the get and set commands.

You can store data from multiple simulation runs as an array of SimData objects. You can use any SimData function on an array of SimData objects.

Creation

Create a SimData object in one of three ways.

Return a SimData object after simulating a model using sbiosimulate.
Return a SimData object after simulating a model using a SimFunction object.
Return an array of SimData objects after multiple stochastic ensemble runs using sbioensemblerun.
Export the simulation results to the command line after simulating a model using the SimBiology Model Analyzer app.

Properties

expand all

`Data` — Simulation data
`mx0` empty double matrix (default) | matrix

This property is read-only.

Simulation data, specified as an m-by-n matrix. m is the number of time steps in the simulation and n is the number of quantities and sensitivities logged during the simulation. View the corresponding time steps by accessing the Time property, and view the corresponding logged quantity information by accessing the DataInfo property.

Data Types: double

`DataCount` — Number of species, compartments, parameters, and sensitivities
structure

This property is read-only.

Number of species, compartments, parameters, and sensitivities, specified as a structure. The structure contains the fields Species, Compartment, Parameter, and Sensitivity. The default value for each field is 0.

Data Types: struct

`DataInfo` — Metadata labels for simulation data
`0-by-1` empty cell array (default) | cell array of structures

This property is read-only.

Metadata labels for simulation data, specified as an n-by-1 cell array of structures. n is the number of quantities and sensitivities logged during simulation. The ith cell contains metadata labeling the ith column of the matrix in the Data property.

The possible types of structures follow.

Type	Fields
Species	Type — `'species'` Name — Species name Compartment — Compartment that the species is in Units — Species unit
Parameter	Type — `'parameter'` Name — Parameter name Reaction — Name of the reaction that the parameter is scoped to, or `''` if the parameter is scoped to the model Units — Parameter unit
Compartment	Type — `'compartment'` Owner — Compartment `Owner` Name — Compartment name Units — Compartment unit
Sensitivity	Type — `'sensitivity'` Name — Sensitivity name, for example, `'d[tumor_weight]/d[k2]'` OutputType — Sensitivity output type (`'species'` or `'parameter'`). OutputName — Sensitivity output name OutputQualifier — Sensitivity output qualifier. If the output is a species, its output qualifier is the name of the compartment that the species is in. If the output is a model-scoped parameter, its output qualifier is `''`. If the output is a reaction-scoped parameter, its output qualifier is the name of the reaction that the parameter is scoped to. InputType — Sensitivity input type (`'species'`, `'parameter'`, or `'compartment'`) InputName — Sensitivity input name InputQualifier — Sensitivity input qualifier. If the input is a species, its input qualifier is the name of the compartment that the species is in. If the input is a model-scoped parameter, its input qualifier is `''`. If the input is a reaction-scoped parameter, its input qualifier is the name of the reaction that the parameter is scoped to. If the input is a compartment, its input qualifier is either `''` or name of the parent compartment. Units — Sensitivity unit
Observable	Scalar — Flag to indicate if the observable is scalar-valued or vector-valued. Expression — Observable expression Type — `'observable'` Name — Observable name Units — Observable unit

Data Types: cell

`DataNames` — Labels for simulation data
`0-by-1` empty cell array (default) | n-by-1 cell array of character vectors

This property is read-only.

Labels for simulation data, specified as an n-by-1 cell array of character vectors. n is the number of logged quantities and sensitivities. In other words, the DataNames property contains the names that label the columns of the data matrix in the Data property.

Data Types: cell

`ScalarObservables` — Results from scalar-valued observable expressions
table

This property is read-only.

Results from scalar-valued observable expressions, specified as a table. Each table variable corresponds to each observable. The name of a variable is the same as that of a scalar-valued observable. However, if the observable name is too long, it is truncated and used as the table variable name. A suffix '_N' is also added, where N is a positive integer. The VariableDescriptions property of the table contains the untruncated names.

If you specified any units for the observable, the units are copied to the VariableUnits property of the table.

Data Types: table

`VectorObservables` — Results from vector-valued observable expressions
table

This property is read-only.

Results from vector-valued observable expressions, specified as a table. Each table variable corresponds to each observable. The name of a variable is the same as that of a vector-valued observable. However, if the observable name is too long, it is truncated and used as the table variable name. A suffix '_N' is also added, where N is a positive integer. The VariableDescriptions property of the table contains the untruncated names.

If you specified any units for the observable, the units are copied to the VariableUnits property of the table.

Data Types: table

`ModelName` — Name of model
`''` (default) | character vector

This property is read-only.

Name of the simulated model, specified as a character vector.

Data Types: char

`Name` — `SimData` object name
`0-by-0` empty character array (default) | character vector | string

SimData object name, specified as a character vector or string.

Data Types: char | string

`Notes` — Additional information
`0-by-0` empty character array (default) | character vector | string

Additional information that you can add for the SimData object, specified as a character vector or string.

Data Types: char | string

`RunInfo` — Information about simulation run
structure

This property is read-only.

Information about the simulation run that generated the simulation data, specified as a structure. The structure contains the following fields.

Configset — A struct form of the configuration set used during simulation. The configuration set corresponds to the model active configset. The default is [].
SimulationDate — The date and time of simulation. The default is ''.
SimulationType — Either 'single run' or 'ensemble run', depending on whether you create the object using sbiosimulate or sbioensemblerun. The default is ''.
Variant — A struct form of the variant(s) used during simulation. The default is [].

Data Types: struct

`Time` — Simulation time steps
column vector

This property is read-only.

Simulation time steps, specified as a column vector.

Data Types: double

`TimeUnits` — Simulation time units
`'second'` (default) | character vector

This property is read-only.

Simulation time units, specified as a character vector.

If you simulate a model created using sbiomodel, the default TimeUnits value of the corresponding SimData object is 'second'.

If you simulate model created using PKModelDesign, the default TimeUnits value is 'hour'.

Data Types: char

`UserData` — Data to associate with object
`[]` (default) | any supported data type

Data to associate with the object, specified as any supported data type.

Object Functions

`addobservable`	Add observable expressions to SimData
`updateobservable`	Update observable expressions or units in SimData
`renameobservable`	Rename observables in SimData
`getdata`	Get simulation data from `SimData` object
`getsensmatrix`	Get 3-D sensitivity matrix from `SimData` object
`select`	Select simulation data from `SimData` object using expressions
`selectbyname`	Select simulation data by name from `SimData` object
`resample`	Resample simulation data onto new time vector
`get`	Get SimBiology object properties
`set`	Set SimBiology object properties
`delete`	Delete SimBiology object
`display`	Display summary of SimBiology object

Examples

collapse all

Initialize Simulation Using Previous Simulation Results

Open Live Script

Load the G protein model.

sbioloadproject gprotein.sbproj;

Check the initial amounts of species.

m1.Species

ans = 
   SimBiology Species Array

   Index:    Compartment:    Name:    Value:       Units:
   1         unnamed         G        7000               
   2         unnamed         Gd       3000               
   3         unnamed         Ga       0                  
   4         unnamed         RL       0                  
   5         unnamed         L        6.022e+17          
   6         unnamed         R        10000              
   7         unnamed         Gbg      3000

Select only the species as the states to log for simulation.

cs = getconfigset(m1);
allspecies = sbioselect(m1,'Type','species');
cs.RuntimeOptions.StatesToLog = allspecies;

Simulate the model.

sd = sbiosimulate(m1);

Use the Data property of the SimData object sd to get the states at the final time point. The Data property is an m-by-n matrix, where m is the number of time steps and n is the number of quantities logged.

finalData = sd.Data(end,:);

Use the DataInfo property to get the names of logged states.

info = sd.DataInfo;

Loop through the species and set their initial values.

numSpecies = length(info);
vObj = addvariant(m1,'initCond');
for i = 1:numSpecies
    addcontent(vObj,{'species',info{i}.Name,'Value',finalData(i)});
end
commit(vObj,m1);

Verify the species initial amounts.

m1.Species

ans = 
   SimBiology Species Array

   Index:    Compartment:    Name:    Value:       Units:
   1         unnamed         G        8562.5             
   2         unnamed         Gd       0.109565           
   3         unnamed         Ga       1437.39            
   4         unnamed         RL       1820.54            
   5         unnamed         L        6.022e+17          
   6         unnamed         R        11.1125            
   7         unnamed         Gbg      1437.5

Calculate Statistics After Model Simulation Using Observables

Open Live Script

Load the Target-Mediated Drug Disposition (TMDD) Model.

sbioloadproject tmdd_with_TO.sbproj

Set the target occupancy (TO) as a response.

cs = getconfigset(m1);
cs.RuntimeOptions.StatesToLog = 'TO';

Get the dosing information.

d = getdose(m1,'Daily Dose');

Add two scalar observables that represent the safety and efficacy thresholds for TO. In this example, suppose that any TO value above 0.85 is unsafe, and any TO value below 0.15 has no efficacy.

safetyTO = addobservable(m1,'SafetyThreshold','0.85','Unit','dimensionless');
efficacyTO = addobservable(m1,'EfficacyThreshold','0.15','Unit','dimensionless');

Scan over different dose amounts using a SimBiology.Scenarios object. To do so, first parameterize the Amount property of the dose. Then vary the corresponding parameter value using the Scenarios object.

amountParam = addparameter(m1,'AmountParam','Units',d.AmountUnits);
d.Amount = 'AmountParam';
d.Active = 1;
doseSamples = SimBiology.Scenarios('AmountParam',linspace(0,300,31));

Create a SimFunction to simulate the model. Set TO and two thresholds (observables) as the simulation outputs.

% Suppress informational warnings that are issued during simulation.
warning('off','SimBiology:SimFunction:DOSES_NOT_EMPTY');
f = createSimFunction(m1,doseSamples,{'TO','SafetyThreshold','EfficacyThreshold'},d)

f = 
SimFunction

Parameters:

         Name          Value        Type            Units    
    _______________    _____    _____________    ____________

    {'AmountParam'}      1      {'parameter'}    {'nanomole'}

Observables: 

            Name                  Type               Units      
    _____________________    ______________    _________________

    {'TO'               }    {'parameter' }    {'dimensionless'}
    {'SafetyThreshold'  }    {'observable'}    {'dimensionless'}
    {'EfficacyThreshold'}    {'observable'}    {'dimensionless'}

Dosed: 

      TargetName                 TargetDimension                  Amount         AmountValue    AmountUnits 
    _______________    ___________________________________    _______________    ___________    ____________

    {'Plasma.Drug'}    {'Amount (e.g., mole or molecule)'}    {'AmountParam'}         1         {'nanomole'}

warning('on','SimBiology:SimFunction:DOSES_NOT_EMPTY');

Simulate the model using the dose amounts generated by the Scenarios object. In this case, the object generates 31 different doses; hence the model is simulated 31 times and generates a SimData array.

doseTable = getTable(d);
sd = f(doseSamples,cs.StopTime,doseTable)

 
   SimBiology Simulation Data Array: 31-by-1
 
   ModelName:        TMDD
   Logged Data:
     Species:        0
     Compartment:    0
     Parameter:      1
     Sensitivity:    0
     Observable:     2

Plot the simulation results. The two horizontal lines represent the safety and efficacy thresholds. Note that certain TO responses either exceed the safety threshold or dip below the efficacy threshold.

sbioplot(sd);

Postprocess the simulation results. Find out which dose amounts are effective, corresponding to the TO responses within the safety and efficacy thresholds. To do so, add an observable expression to the simulation data.

% Suppress informational warnings that are issued during simulation.
warning('off','SimBiology:sbservices:SB_DIMANALYSISNOTDONE_MATLABFCN_UCON');
newSD = addobservable(sd,'stat1','max(TO) < 0.85 & min(TO) > 0.15','Units','dimensionless')

 
   SimBiology Simulation Data Array: 31-by-1
 
   ModelName:        TMDD
   Logged Data:
     Species:        0
     Compartment:    0
     Parameter:      1
     Sensitivity:    0
     Observable:     3

The addobservable function evaluates the new observable expression for each SimData in sd and returns the evaluated results as a new SimData array. newSD has three observables. The first two correspond to the safety and efficacy thresholds. The third is the added observable (stat1).

SimBiology stores the observable results in two different properties of a SimData object. If the results are scalar-valued, they are stored in SimData.ScalarObservables. Otherwise, they are stored in SimData.VectorObservables. In this example, the stat1 observable expression is scalar-valued.

Extract the scalar observable values and plot them against the dose amounts.

scalarObs = vertcat(newSD.ScalarObservables);
doseAmounts = generate(doseSamples);
plot(doseAmounts.AmountParam,scalarObs.stat1,'o','MarkerFaceColor','b')

The plot shows that dose amounts ranging from 50 to 180 nanomoles provide TO responses that lie within the target efficacy and safety thresholds.

You can update the observable expression with different threshold amounts. The function recalculates the expression and returns the results in a new SimData object array.

newSD2 = updateobservable(newSD,'stat1','max(TO) < 0.75 & min(TO) > 0.30');

Rename the observable expression. The function renames the observable, updates any expressions that reference the renamed observable (if applicable), and returns the results in a new SimData object array.

newSD3 = renameobservable(newSD2,'stat1','EffectiveDose');

Restore the warning settings.

warning('on','SimBiology:sbservices:SB_DIMANALYSISNOTDONE_MATLABFCN_UCON');

Documentation

SimData

Description

Creation

Properties

`Data` — Simulation data
`mx0` empty double matrix (default) | matrix

`DataCount` — Number of species, compartments, parameters, and sensitivities
structure

`DataInfo` — Metadata labels for simulation data
`0-by-1` empty cell array (default) | cell array of structures

`DataNames` — Labels for simulation data
`0-by-1` empty cell array (default) | n-by-1 cell array of character vectors

`ScalarObservables` — Results from scalar-valued observable expressions
table

`VectorObservables` — Results from vector-valued observable expressions
table

`ModelName` — Name of model
`''` (default) | character vector

`Name` — `SimData` object name
`0-by-0` empty character array (default) | character vector | string

`Notes` — Additional information
`0-by-0` empty character array (default) | character vector | string

`RunInfo` — Information about simulation run
structure

`Time` — Simulation time steps
column vector

`TimeUnits` — Simulation time units
`'second'` (default) | character vector

`UserData` — Data to associate with object
`[]` (default) | any supported data type

Object Functions

Examples

Initialize Simulation Using Previous Simulation Results

Calculate Statistics After Model Simulation Using Observables

See Also

SimBiology Documentation

Support

Documentation

SimData

Description

Creation

Properties

Data — Simulation data mx0 empty double matrix (default) | matrix

DataCount — Number of species, compartments, parameters, and sensitivities structure

DataInfo — Metadata labels for simulation data 0-by-1 empty cell array (default) | cell array of structures

DataNames — Labels for simulation data 0-by-1 empty cell array (default) | n-by-1 cell array of character vectors

ScalarObservables — Results from scalar-valued observable expressions table

VectorObservables — Results from vector-valued observable expressions table

ModelName — Name of model '' (default) | character vector

Name — SimData object name 0-by-0 empty character array (default) | character vector | string

Notes — Additional information 0-by-0 empty character array (default) | character vector | string

RunInfo — Information about simulation run structure

Time — Simulation time steps column vector

TimeUnits — Simulation time units 'second' (default) | character vector

UserData — Data to associate with object [] (default) | any supported data type

Object Functions

Examples

Initialize Simulation Using Previous Simulation Results

Calculate Statistics After Model Simulation Using Observables

See Also

SimBiology Documentation

Support

`Data` — Simulation data
`mx0` empty double matrix (default) | matrix

`DataCount` — Number of species, compartments, parameters, and sensitivities
structure

`DataInfo` — Metadata labels for simulation data
`0-by-1` empty cell array (default) | cell array of structures

`DataNames` — Labels for simulation data
`0-by-1` empty cell array (default) | n-by-1 cell array of character vectors

`ScalarObservables` — Results from scalar-valued observable expressions
table

`VectorObservables` — Results from vector-valued observable expressions
table

`ModelName` — Name of model
`''` (default) | character vector

`Name` — `SimData` object name
`0-by-0` empty character array (default) | character vector | string

`Notes` — Additional information
`0-by-0` empty character array (default) | character vector | string

`RunInfo` — Information about simulation run
structure

`Time` — Simulation time steps
column vector

`TimeUnits` — Simulation time units
`'second'` (default) | character vector

`UserData` — Data to associate with object
`[]` (default) | any supported data type