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 the following ways.
Return a
SimData
object after simulating a model usingsbiosimulate
.Return a
SimData
object after simulating a model using aSimFunction object
.Return an array of
SimData
objects after multiple stochastic ensemble runs usingsbioensemblerun
.Export the simulation results to the command line after simulating a model using the SimBiology Model Analyzer app.
Properties
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 |
|
Parameter |
|
Compartment |
|
Sensitivity |
|
Observable |
|
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
empty character array (default) | character vector | string
Additional information that you can add for SimData
, 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
— Astruct
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 usingsbiosimulate
orsbioensemblerun
. The default is''
.Variant
— Astruct
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 |
display | Display summary of SimBiology object |
getdata | Get simulation data from SimData object |
getsensmatrix | Get 3-D sensitivity matrix from SimData object |
remove | Remove simulation data from SimData object using
expressions |
removebyname | Remove simulation data by name from SimData object |
renameobservable | Rename observables in SimData |
resample | Resample simulation data onto new time vector |
select | Select simulation data from SimData object using
expressions |
selectbyname | Select simulation data by name from SimData object |
updateobservable | Update observable expressions or units in SimData |
Examples
Initialize Simulation Using Previous Simulation Results
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
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');
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
as the simulation output.
% Suppress informational warnings that are issued during simulation. warning('off','SimBiology:SimFunction:DOSES_NOT_EMPTY'); f = createSimFunction(m1,doseSamples,'TO',d)
f = SimFunction Parameters: Name Value Type Units _______________ _____ _____________ ____________ {'AmountParam'} 1 {'parameter'} {'nanomole'} Observables: Name Type Units ______ _____________ _________________ {'TO'} {'parameter'} {'dimensionless'} Dosed: TargetName TargetDimension Amount AmountValue AmountUnits _______________ ___________________________________ _______________ ___________ ____________ {'Plasma.Drug'} {'Amount (e.g., mole or molecule)'} {'AmountParam'} 1 {'nanomole'} TimeUnits: day
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: 0
Plot the simulation results. Also add two reference lines 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.
h = sbioplot(sd); time = sd(1).Time; h.NextPlot = 'add'; safetyThreshold = plot(h,[min(time), max(time)],[0.85, 0.85],'DisplayName','Safety Threshold'); efficacyThreshold = plot(h,[min(time), max(time)],[0.15, 0.15],'DisplayName','Efficacy Threshold');
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: 1
The addobservable function evaluates the new observable expression for each SimData
in sd
and returns the evaluated results as a new SimData
array, newSD
, which now has 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); figure 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');
Version History
Introduced in R2007bR2022a: delete
function of SimData
has been removed
The delete
function of the SimData
object has been
removed.
See Also
Model
| Parameter
| Species
| Compartment
| Reaction
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)