addobservable
Syntax
Description
adds an obsObj
= addobservable(modelObj
,obsName
,obsExpression
)observable
object
to a SimBiology® model modelObj
. The inputs obsName
and obsExpression
are the observable object name and its expression,
respectively.
sets the property values of obsObj
= addobservable(modelObj
,obsName
,obsExpression
,Name,Value
)obsObj
using one or more name-value pair
arguments. Name
is the property name and Value
is the
corresponding value Name
must appear inside quotes. You can specify
several name and value pair arguments in any order as
Name1,Value1,...,NameN,ValueN
. For a list of properties, see observable object
properties.
Examples
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');
Input Arguments
modelObj
— SimBiology model
SimBiology model object
SimBiology model, specified as a SimBiology model object
.
obsName
— Name of observable object
character vector | string
Name of the observable object, specified as a character vector or string.
The name
Cannot contain the characters
[ ]
,->
, or<->
.Cannot be empty, the word time, the word null, or all whitespace.
Must be unique in a model, meaning no observable object can have the same name as another observable, species, compartment, parameter, reaction, variant, or dose in the model.
For details, see Guidelines for Naming Model Components.
Example: 'AUC_obs'
Data Types: char
| string
obsExpression
— Expression of observable object
character vector | string
Expression of the observable object, specified as a character vector or string.
Example: 'trapz(time,drug)'
Data Types: char
| string
Output Arguments
obsObj
— Observable object
Observable
object
Observable object, returned as an observable
object.
Version History
Introduced in R2020aR2024a: Having duplicate model component names is no longer allowed
When you load a model that contains duplicate names, SimBiology automatically updates those names. SimBiology disambiguates the duplicate names by adding a suffix
"_N"
, where N is the first positive integer that results in a unique name. If there is an existing suffix, N will be incremented from that suffix. For example, if there are two model components named x_3, the function updates one of the names to x_4. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if x_003 is a duplicate name, it gets renamed to x_4. However, the function assumes that names with leading zeros and without leading zeros are different. For instance, x_005 and x_5 are considered to be different names.SimBiology issues an error if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. Within a single model, these components are required to have unique names even when they are of different types with the following two exceptions:
Species in different compartments can have the same name.
Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.
For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.
R2022b: Having duplicate model component names issues a warning
SimBiology issues a warning if multiple model components have the same name.
R2022a: Having duplicate model component names will not be allowed in a future release
SimBiology will not allow you to have duplicate names for model components within a model.
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)