Mathworks SIMBIOLOGY 3 Reference

Download

SimBiology

Reference

How to Contact The MathWorks

www.mathworks. comp.soft-sys.matlab Newsgroup www.mathworks.com/contact_TS.html T echnical Support

suggest@mathworks.com Product enhancement suggestions

bugs@mathwo doc@mathworks.com Documentation error reports service@mathworks.com Order status, license renewals, passcodes

info@mathwo

com

rks.com

Web

Bug reports

Sales, prici

ng, and general information

508-647-7000 (Phone)

508-647-7001 (Fax)

The MathWorks, Inc. 3 Apple Hill Drive Natick, MA 01760-2098

For contact information about worldwide offices, see the MathWorks Web site.

SimBiology

The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form without prior written consent from The MathW orks, Inc.

FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through the federal government of the United States. By accepting delivery of the Program or Documentation, the government hereby agrees that this software or documentation qualifies as commercial computer software or commercial computer software documentation as such terms are used or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern theuse,modification,reproduction,release,performance,display,anddisclosureoftheProgramand Documentation by the federal government (or other entity acquiring for or through the federal government) and shall supersede any conflicting contractual terms or conditions. If this License fails to meet the government’s needs or is inconsistent in any respect with federal procurement law, the government agrees to return the Program and Docu mentation, unused, to The MathWorks, Inc.

Trademarks

MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See

www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand

names may be trademarks or registered trademarks of their respective holders.

Patents

The MathWorks products are protected by one or more U.S. patents. Please see

www.mathworks.com/patents for more information.

Reference

Revision History

September 2005 Online only New for Version 1.0 ( Release 14SP3+) March 2006 Online only Updated for Version 1.0.1 (Release 2006a) May 2006 Online only Updated for Version 2.0 (Release 2006a+) September 2006 Online only Updated for Version 2.0.1 (Release 2006b) March 2007 Online only Rereleased for Version 2.1.1 (Release 2007a) September 2007 Online only Rereleased for Version 2.1.2 (Release 2007b) October 2007 Online only Updated for Version 2.2 (Release 2007b+) March 2008 Online only Updated for Version 2.3 (Release 2008a) October 2008 Online only Updated for Version 2.4 (Release 2008b) March 2009 Online only Updated for Version 3.0 (Release 2009a) September 2009 Online only Updated for Version 3.1 (Release 2009b) March 2010 Online only Updated for Version 3.2 (Release 2010a)

Function Reference

Modeling, Simulation, and Analysis Tools ............ 1-2

Contents

Project Opening and Saving

SBML Model Reading and Writing

Object Construction

Pharmacokinetic Modeling

Units and Unit Prefixes

............................... 1-6

Functions — Alphabetical List

........................ 1-4

.................. 1-5

......................... 1-7

............................ 1-8

Method Reference

Objects ........................................... 3-3

Abstract Kinetic Laws

Compartments

Configuration Sets

.................................... 3-5

.............................. 3-4

................................. 3-6

Events ............................................ 3-6

Kinetic Laws

Models

Parameters

Pharmacokinetic Modeling

Reactions

RepeatDose

Root

Rules

ScheduleDose

SimData

............................................ 3-8

.............................................. 3-14

............................................. 3-15

...................................... 3-7

....................................... 3-11

......................................... 3-13

....................................... 3-13

..................................... 3-15

.......................................... 3-16

......................... 3-12

vi Contents

Species

Units and Unit Prefixes

Variants

Using Object Methods

Constructing (Creating) Objects Using Object Methods Help for Objects, Methods, and Properties

........................................... 3-17

............................ 3-17

.......................................... 3-17

............................. 3-19

...................... 3-19

.............................. 3-19

............. 3-20

Methods — Alphabetical List

Property Reference

Abstract Kinetic Law .............................. 5-3

Compartments

Configuration Sets

Events

Kinetic Laws

Models

NMFileDef

Parameters

PKCompartment

PKData

PKModelDesign

............................................ 5-6

............................................ 5-8

........................................... 5-12

.................................... 5-4

...................................... 5-7

........................................ 5-9

....................................... 5-10

................................. 5-5

.................................. 5-11

................................... 5-13

PKModelMap

Reactions

RepeatDose

......................................... 5-15

...................................... 5-14

....................................... 5-16

vii

Root .............................................. 5-17

Rules

ScheduleDose

SimData

Species

Unit

Unit Prefix

Variant

Using Object Properties

............................................. 5-18

..................................... 5-19

.......................................... 5-20

........................................... 5-21

.............................................. 5-21

........................................ 5-22

........................................... 5-22

........................... 5-24

Entering Property Values Retrieving Property Values Help for Objects, Methods, and Properties

........................... 5-24

......................... 5-24

............. 5-25

viii Contents

Properties — Alphabetical List

Index

Function Reference

Modeling, Simulation, and Analysis Tools (p. 1-2)

Project Opening and Saving (p. 1-4) Save and open projects in MATLAB

SBML Model Reading and Writing (p. 1-5)

Object Construction (p. 1-6) Create SimBiology

Pharmacokinetic Modeling (p. 1-7) Tools for pharmacokinetic modeling

Units and Unit Prefixes (p. 1-8) Perform unit conversion and create

Modeling, simulation, and analysis tools

Export and import SBML models

objects

user-defined units

1 Function Reference

Modeling, Simulation, and Analysis Tools

sbioaccelerate

sbioconsmoiety

sbiodesktop

sbioensembleplot

sbioensemblerun

sbioensemblestats

sbiogetmodel

sbiogetnamedstate

sbiohelp

sbiolasterror

sbiolastwarning

sbionlinfit

ionlmefit

bionlmefitsa

sbioparamestim

sbioplot

sbioreset

Prepare model object fo r accelerated simulations

Find conserved moieties in SimBiology model

Open SimBiology modeling and simulation GUI

Show results of ensemble run using 2-D or 3-D plots

Multiple stochastic ensemble runs of SimBiology model

Get statistics from ensemble run data

Get model object that generated simulation data

Get state and time data from simulation results

Help for SimBiology functions

SimBiology last error message

SimBiology last warning message

linear least-squares regression

Non

ng SimBiology models

usi

timate nonlinear mixed effects

ing SimBiology models

stimate nonlinear mixed effects

ith stochastic EM algorithm

erform parameter es timation

Plot simulation results in one figure

Delete all model and simulation objects

1-2

Modeling, Simulation, and Analysis Tools

sbioselect

sbiosimulate

sbiosubplot

sbiotrellis

sbioupdate

simbiology

Search for objects with specified constraints

Simulate model object

Plot simulation results in subplots

Plot simulation results in trellis plot

Update SimBiology model version

Open SimBiology modeling and simulation GUI

1-3

1 Function Reference

Project Opening and Saving

sbioaddtolibrary

sbiocopylibrary

sbioloadproject

sbioremovefromlibrary

sbiosaveproject

sbiowhos

Add to user-defined library

Copy library to disk

Load project from file

Remove kinetic law, unit, or unit prefix from library

Save all models in root object

Show contents of project file, library file, or SimBiology root object

1-4

SBML Model Reading and Writing

sbmlexport

sbmlimport

Export SimBiology model to SBML file

Import SB ML-formatted file

1-5

1 Function Reference

Object Construction

sbioabstractkineticlaw

sbiodose

sbiomodel

sbioroot

sbiovariant

Create kinetic law definition

Construct dose object

Construct model object

Return SimBiology root object

Construct variant object

1-6

Pharmacokinetic Modeling

sbiofitstatusplot

sbionlinfit

sbionlmefit

sbionlmefitsa

sbionmfiledef

sbionmimport

Plot status of sbionlmefit

Nonlinear least-squares regression using SimBiology models

Estimate nonlinear mixed effects using SimBiology models

Estimate nonlinear mixed effects with stochastic EM algorithm

NONMEM®file definition object for sbionmimport

Import NONMEM formatted data

1-7

1 Function Reference

Units and Unit Prefixes

sbioconvertunits

sbioregisterunitprefix

sbioshowunitprefixes

sbioshowunits

sbiounit

sbiounitcalculator

sbiounitprefix

Convert unit and unit value to new unit

Create user-defined unit prefix

Show unit prefixes in library

Show units in library

Create user-defined unit

Convert value between units

Create user-defined unit prefix

1-8

Functions — Alphabetical List

sbioabstractkineticlaw

Purpose Create kinetic law definition

Syntax abstkineticlawObj = sbioabstractkineticlaw('Name')

abstkineticlawObj = sbioabstractkineticlaw('Name',

'Expression')

abstkineticlawObj = sbioabstractkineticlaw(...'PropertyName', PropertyValue...)

Arguments

Name

Expression

Description abstkineticlawObj = sbioabstractkineticlaw('Name') creates an

abstract kinetic law object, with the name

abstkineticlawObj. Use the abstract kinetic law object to specify a

kinetic law definition.

Enteranameforthekineticlawdefinition.

Name must be unique in the user-defined

kinetic law library.

kineticlawObj.

Name is referenced by

The mathematical expression that defines the kinetic law.

Name and returns it to

2-2

The kinetic law definition provides a mechanism for applying a specific rate law to multiple reactions. It acts as a mapping template for the reaction rate. The kinetic law definition defines a reaction rate expression, which is shown in the property

Expression,andthespecies

and parameter variables used in the expression. The species variables are defined in the variables are defined in the

SpeciesVariables property, and the parameter

ParameterVariables property of the

abstract kinetic law object.

In order to use the kinetic law definition, it must be added to the user-defined library with the

sbioaddtolibrary function. To get the

kinetic law definitions in the user-defined library, use the command

get(sbioroot, 'UserDefinedKineticLaws').

abstkineticlawObj = sbioabstractkineticlaw('Name','Expression')

constructs a SimBiology abstract kinetic law object, abstkineticlawObj

sbioabstractkineticlaw

with the name 'Name' and with the expression 'Expression' and returns it to

abstkineticlawObj = sbioabstractkineticlaw(...'PropertyName', PropertyValue...)

name/property value pairs can be in any format supported by the function name-value cell array pairs).

abstkineticlawObj.

defines optional properties. The property

set (for example, name-value string pairs, structures, and

Method Summary

Property Summary

Additional command. abstkineticlawObj properties can be modified with the

set command.

delete (any object) Delete SimBiology object

display(anyobject) DisplaysummaryofSimBiology

get (any object) Get object properties

set (any object) Set object properties

Annotation

Expression

Name

Notes

ParameterVariables

Parent

SpeciesVariables

abstkineticlawObj properties can be viewed with the get

object

Store link to URL or file

Expression to determine reaction rate equation

Specify name of object

HTML text describing SimBiology object

Parameters in kinetic law definition

Indicate parent object

Species in abstract kinetic law

2-3

sbioabstractkineticlaw

Tag

Type

UserData

Examples 1 Create a kinetic law definition.

abstkineticlawObj = sbioabstractkineticlaw('ex_mylaw1', '(k1*s)/(k2+k1+s)');

2 Assign the parameter and species variables in the expression.

set (abstkineticlawObj, 'SpeciesVariables', {'s'}); set (abstkineticlawObj, 'ParameterVariables', {'k1', 'k2'});

3 Add the new kinetic l aw definition to the user-defined library.

sbioaddtolibrary(abstkineticlawObj);

sbioaddtolibrary

library. You can verify this using

adds the kinetic law definition to the user-defined

Specify label for SimBiology object

Display top-level SimBiology object type

Specifydatatoassociatewith object

sbiowhos.

2-4

sbiowhos -kineticlaw -userdefined

SimBiology Abstract Kinetic Law Array

Index: Library: Name: Expression: 1 UserDefined ex_mylaw1 (k1*s)/(k2+k1+s)

4 Use the new kinetic law definition when defining a reaction’s kinetic

law.

modelObj = sbiomodel('cell'); reactionObj = addreaction(modelObj, 'A + B <-> B + C'); kineticlawObj = addkineticlaw(reactionObj, 'ex_mylaw1');

sbioabstractkineticlaw

Note Remember to specify the SpeciesVariableNames and the

ParameterVariableNames in kineticlawObj to fully define the ReactionRate of the reaction.

See Also addkineticlaw, addparameter, addreaction, sbiomodel

2-5

sbioaccelerate

Purpose Prepare model object for accelerated simulations

Syntax sbioaccelerate(modelObj)

sbioaccelerate(modelObj, configsetObj) sbioaccelerate(modelObj, variantObj) sbioaccelerate(modelObj, doseObj) sbioaccelerate(modelObj, configsetObj, variantObj) sbioaccelerate(modelObj, configsetObj, doseObj) sbioaccelerate(modelObj, configsetObj, variantObj, doseObj)

Description Use the same arguments in sbioaccelerate that you will use in the

subsequent call to

sbioaccelerate(modelObj) prepares a model object (modelObj)for

accelerated simulation using its active configset, active variants and active dos es. A SimBiology model can contain multip le configsets with one being active at any given time. The active configset contains the settings that will be used to prepare the model for acceleration.

sbioaccelerate(modelObj, configsetObj) uses the configset

configsetObj. Aconfigsetobjectstoressimulation specific information.

sbiosimulate.

2-6

sbioaccelerate(modelObj, variantObj) uses the variant object or array

of variant objects

variantObj. A variant object’s settings supersede

model property-values.

sbioaccelerate(modelObj, doseObj) simulates modelObj using the

dose obje ct or array of dose objects

doseObj. A SimBiology Dose object

defines additions that are made to species amounts or parameter values.

sbioaccelerate(modelObj, configsetObj, variantObj), sbioaccelerate(modelObj, configsetObj, doseObj) uses the configset

configsetObj and variant object or variant array variantObj or dose

object or dose array assumed to be

sbioaccelerate(modelObj, configsetObj, variantObj, doseObj)

doseObj. N ote if the third argument is empty it is

variantObj.

sbioaccelerate

Input Arguments

modelObj

SimBiology model object.

configsetObj

Specify the configuration set object to use in the simulation. For more inform ation about configuration sets, see

object

variantObj

Configset

Specify the variant object to apply to the model during the simulation. For more information about variant objects, see

Variant object.

doseObj

Specify the dose object to apply to the model during the simulation. For more information about do se objects, see

object

and RepeatDose object.

ScheduleDose

Examples This example shows how to prepare a model for accelerated simulation.

% Create a SimBiology model from an SBML file.

m = sbmlimport('lotka.xml');

% Prepare the model for accelerated simulation.

sbioaccelerate(m);

% Simulate the model for different initial amounts of x.

x = sbioselect(m, 'type', 'species', 'name', 'x');

for i=1:10

x.initialAmount = i; sd(i) = sbiosimulate(m);

end

% Plot the results.

sbioplot(sd);

2-7

sbioaccelerate

See Also sbiolasterror, verify

diagstruct).

2-50

sbioloadproject

Purpose Load project from file

Syntax sbioloadproject('projFilename')

sbioloadproject ('projFilename','variableName') sbioloadproject projFilename variableName1 variableName2...

s=sbioloadproject (...)

Description sbioloadproject('projFilename') loads a SimBiology project

from a project file (

sbioloadproject assumes a default extension of .sbproj.

Alternatively, the command syntax is

sbioloadproject ('projFilename','variableName') loads only the

variable

sbioloadproject projFilename variableName1 variableName2... loads

the specified variables from the project.

s=sbioloadproject (...) returns the contents of projFilename in

a variable retrieved from the SimBiology project.

variableName from the project file.

s. s is a struct containing fields matching the variables

projFilename). If no extension is specified,

sbioloadproject projFilename.

You can display the contents of the project file using the command.

sbiowhos

See Also sbioaddtolibrary, sbioremovefromlibrary, sbiosaveproject,

sbiowhos

2-51

sbiomodel

Purpose Construct model object

Syntax modelObj = sbiomodel(’NameValue')

modelObj = sbiomodel(...’PropertyName', PropertyValue...)

Arguments

NameValue

PropertyName

PropertyValue

Description modelObj = sbiomodel(’NameValue') creates a model object and

returns the model object ( assigns a value (

modelObj = sbiomodel(...’PropertyName', PropertyValue...) defines

optional pro perties. The property name/property value pairs can be in any format supported by the function string pairs, structures, and name-value cell array pairs).

NameValue) to the property Name.

Required property to specify a unique name for a

model object. Enter a character string.

Property name for a Model object from “Property Summary” on page 2-54.

Property value. Valid value for the specified property.

modelObj). In the model object, this method

set (for example, name-value

Method Summary

2-52

Simulate

Add objects to a model object using the methods

addmodel, addparameter, addreaction, addrule,andaddspecies.

All SimBiology model objects can be retrieved from the SimBiology root object. A SimBiology model object has its the SimBiology root object.

addcompartment (model, compartment)

addconfigset (model) Create configuration set object

modelObj with the function sbiosimulate.

addkineticlaw,

Parent property set to

Create compartment object

and add to model object

sbiomodel

adddose (model) Add d os e object to model

addevent (model) Add event object to model object

addparameter (model, kineticlaw) Create parameter object and add

to model or kinetic law object

addreaction (model) Create reaction object and add to

model object

addrule (model) Create rule object and add to

model object

addvariant (model) Add variant to model

copyobj (any object) Copy SimBiology object and its

children

delete (any object) Delete SimBiology object

display(anyobject) DisplaysummaryofSimBiology

object

get (any object) Get object properties

getadjacencymatrix (model) Get adjacency matrix from model

object

getconfigset (model) Get configuration set object from

model object

getdose (model) Return S i mBiology dose object

getstoichmatrix (model) Get stoichiometry matrix from

model object

getvariant (model) Get variant from model

removeconfigset (model) Remove configuration set from

model

removedose (model) Add dose object to model

removevariant (model) Remove variant from model

reorder (model, compartment)

Reorder component lists

2-53

sbiomodel

set (any object) Set object properties

setactiveconfigset (model) Set active configuration set for

model object

verify (model, variant) Validate and verify SimBiology

model

Property Summary

Annotation

Compartments

Events

Models

Name

Notes

Parameters

Parent

Reactions

Rules

Tag

Type

UserData

Store link to URL or file

Array of compartments in model or compartment

Contain all event objects

Contain all model objects

Specify name of object

HTML text describing SimBiology object

Array of parameter objects

Indicate parent object

Array o f reaction objects

Array of rules in model object

Specify label for SimBiology object

Display top-level SimBiology object type

Specifydatatoassociatewith object

Examples 1 Create a SimBiology model object.

modelObj = sbiomodel('cell', 'Tag', 'mymodel');

2-54

2 List all modelObj properties and the current values.

get(modelObj)

MATLAB returns:

Annotation: ''

Models: [0x1 double]

Name: 'cell'

Notes: ''

Parameters: [0x1 double]

Parent: [1x1 SimBiology.Root]

Species: [0x1 double]

Reactions: [0x1 double]

Rules: [0x1 double]

Tag: 'mymodel'

Type: 'sbiomodel'

UserData: []

sbiomodel

3 Display a summary of modelObj contents.

modelObj

SimBiology Model - cell

Model Components:

Models: 0 Parameters: 0 Reactions: 0 Rules: 0 Species: 0

See Also addcompartment, addconfigset, addevent, addkineticlaw, addmodel,

addparameter, addreaction, addrule, addspecies, copyobj, get, sbioroot, sbiosimulate, set

2-55

sbionlinfit

Purpose Nonlinear least-squares regression using SimBiology models

Syntax results = sbionlinfit(modelObj, pkModelMapObject, pkDataObj,

Beta0)

results = sbionlmefit(modelObj, pkModelMapObject,

pkDataObject, Beta0,'ParameterName',ParameterValue)

results = sbionlinfit(modelObj, pkModelMapObject, pkDataObj,

Beta0, ...)

[results, SimDataI] = sbionlinfit(...)

Description

Note This function requires nlinfit in Statistics T oolbox™ (Version

7.0 or later).

results = sbionlinfit(modelObj, pkModelMapObject, pkDataObj, Beta0)

modelObj and returns estimated results in the r esu lts structure.

results = sbionlmefit(modelObj, pkModelMapObject, pkDataObject, Beta0,'ParameterName',ParameterValue)

comma-separated parameter name/value pairs that are accepted by

nlinfit. In addition, lets you specify a transformation function for each

of the estimated parameters using

performs least-squares regression using the SimBiology model,

accepts one or more

ParamTransform.

Input Arguments

2-56

results = sbionlinfit(modelObj, pkModelMapObject, pkDataObj, Beta0, ...)

See

nlinfit in the Statistics Toolbox User’s Guide for information on

lets you supply additional arguments accepted by nlinfit.

the accepted properties.

[results, SimDataI] = sbionlinfit(...) returns simulations of

the SimBiology model,

modelObj, using the estimated values of the

parameters.

modelObj

SimBiology model object used to fit observed data.

pkModelMapObject

sbionlinfit

PKModelMap object that defines the roles of the model components

in the estimation. For more information, see

pkDataObj

PKData object that defines the data to use in fitting, and the roles

of the data columns used for estimation. For more information, see

PKData object.

Beta0

A vector of initial estimates for the f ix ed effects. The length of

modelMapObject.Estimated. The final estimates for the fixed

effects defined in

Beta0 must equal at least the length of

Beta0 are log transformed in the results.

For more information on specifying initial estimates, see “Setting Initial Estimates” in the SimBiology documentation.

Parameter Name/Value Pairs

This section contains a partial list of supported name/value pairs. For a complete list, see

nlinfit in the Statistics Toolbox documentation.

PKModelMap object.

ParamTransform

A vector of values specifying a transformation function f() for each of the estimated parameters:

estimate = f(Beta). Each

element of the vector must be one of the following integer codes specifying the transformation f or the corresponding value of estimate:

•

0 – estimate = Beta

• 1 – log(estimate) = Beta (default for all parameters).

2 – probit(estimate) = beta

•

• 3 – logit(estimate) = beta

For more information, see “Specifying Parameter Transformations” in the SimBiology documentation.

2-57

sbionlinfit

Output Arguments

results

A structure with the following fields:

•

estimate — Fitted coefficients

beta — Fitted coefficients in transformed space

•

R —Residuals

•

J —Jacobianofthemodel

•

COVB — Estimated covariance matrix for the fitted coefficients

•

mse — Estimate of the error of the variance term

•

SimDataI

SimDataI contains simulation results for individuals.

See Also PKData object | PKModelDesign object | PKModelDesign object |

PKModelMap object | Model object | sbionlmefit | nlinfit

2-58

Purpose Estimate nonlinear mixed effects using SimBiology models

Syntax results = sbionlmefit(modelObj, pkModelMapObject,

pkDataObject, Beta0)

results = sbionlmefit(modelObj, pkModelMapObject,

pkDataObject, Beta0,'ParameterName',ParameterValue) ... = sbionlmefit(..., optionStruct) [results, SimDataI, SimDataP] = sbionlmefit(...)

Description

Note This function requires nlmefit in Statistics Toolbox (Version

7.0 or later).

results = sbionlmefit(modelObj, pkModelMapObject, pkDataObject, Beta0)

SimBiology model,

results structure.

results = sbionlmefit(modelObj, pkModelMapObject, pkDataObject, Beta0,'ParameterName',ParameterValue)

comma-separated parameter name/value pairs that are accepted by

nlmefit.SpecifyParameterName inside s ingle quotes.

performs nonlinear mixed effects estimation using the

modelObj and returns estimated results in the

accepts one or more

sbionlmefit

... = sbionlmefit(..., optionStruct) where optionStruct lets you

construct a names accepted by

struct that contains field names that are the parameter

nlmefit and field values that are the associated

parameter values.

SimBiology software contains a function (

sbiofitstatusplot)thatyou

can specify in the options structure. This function lets you monitor the status of fitting.

[results, SimDataI, SimDataP] = sbionlmefit(...) returns

simulation data of the SimBiology model,

modelObj, using the estimated

values of the parameters.

2-59

sbionlmefit

Input Arguments

modelObject

SimBiology model object used to fit observed data.

pkModelMapObject

PKModelMap object that defines the roles of the model components

used for estimation. For more information, see

object

pkDataObject

PKData object that defines the data to use in fitting and the roles

of the columns used for estimation.

pkDataObject must define

PKModelMap

target data for at least two groups. For more information, see

PKData object.

Beta0

A vector of initial estimates for the fixed effects. The first P elements of Beta0 correspond to the fixed effects for each of the

P elements of modelMapObject.Estimated.Additional

elements correspond to the fixed effects for covariate factors. The first

P elements of Beta0 are transformed as specified by the

ParamTransform nlmefit option (log transformed by default).

For more information on specifying initial estimates see in the SimBiology documentation.

optionStruct

2-60

A struct that can contain fields and values where the field names are the parameter-names accepted by

nlmefit and the field

values are the associated parameter-values.

Parameter Name/Value Pairs

This section contains a partial list of supported name/value pairs. For a complete list, see

FEGroupDesign

nlmefit in the Statistics Toolbox documentation.

Specify the design matrix for each of the groups. See “Specifying the Covariate Model” in the SimBiology documentation.

ParamTransform

Specify how the parameters are distributed. The available distributions are: Parameter Transformations” in the SimBiology documentation.

none, log, probit,andlogit.See“Specifying

sbionlmefit

Output Arguments

Default:

See nlmefit in the Statistics Toolbox documentation for information on all the accepted properties including

ParamTransform.

The following parameter name/value pairs are not supported:

•

FEConstDesign

• FEObsDesign

• FEParamsSelect

• REConstDesign

• REGroupDesign

• REObsDesign

• Vectorization

• Jacobian

results

A structure with the following fields:

• A

log

FEGroupDesign,and

results structure containing

- estimate — Estimates for the fixed effects.

- phiP — Estimated parameter values for the population

- phiI — Estimated parameter values for individuals

- beta — Esti m ates for the fixed effects in transformed s pace

as specified in the

ParamTransform option.

2-61

sbionlmefit

- psi — Estimated covariance matrix of the random effects

- stats — Structure with statistics such as AIC, and BIC.

For a complete list see documentation.

- b — Estimated random effects for each group in

observedData

SimDataI

SimDataI contains the data from simulating the model using the

estimated parameter values, for individuals.

SimDataP

SimDataP contains the data from simulating the model using the

estimated parameter values, for the population.

See Also PKData object | PKModelDesign object | PKModelMap object |

Model object | sbiofitstatusplot | sbionlinfit | sbionlmefitsa

| nlmefit

nlmefit in the Statistics Toolbox

How To • “Fitting Pharmacokinetic Model Parameters at the Command Line”

2-62

sbionlmefitsa

Purpose Estimate nonlinear mixed effects with stochastic EM algorithm

Syntax results = sbionlmefitsa(modelObj, pkModelMapObject,

pkDataObject, Beta0) results = sbionlmefitsa(modelObj, pkModelMapObject,

pkDataObject, Beta0,'ParameterName',ParameterValue) ... = sbionlmefitsa(..., optionStruct) [results, SimDataI, SimDataP] = sbionlmefitsa(...)

Description

Note This function requires nlmefitsa in Statistics Toolbox (Version

7.0 or later).

results = sbionlmefitsa(modelObj, pkModelMapObject, pkDataObject, Beta0)

Expectation-Maximization (SAEM) algorithm for fitting p opulation data w ith the SimBiology model, results in the

estimations using the Stochastic Approximation

modelObj and returns the estimated

results structure.

results = sbionlmefitsa(modelObj, pkModelMapObject, pkDataObject, Beta0,'ParameterName',ParameterValue)

accepts one or more

comma-separated parameter name/value pairs that are accepted by

nlmefitsa.SpecifyParameterName inside single quotes.

... = sbionlmefitsa(..., optionStruct) lets you construct a struct

that contains field names that are the parameter names accepted by

nlmefitsa and field values that are the associated param eter values.

SimBiology software contains a function (

sbiofitstatusplot)thatyou

can specify in the options structure. This function lets you monitor the status of fitting.

[results, SimDataI, SimDataP] = sbionlmefitsa(...) returns

simulation data of the SimBiology model,

modelObj, using the estimated

values of the parameters.

2-63

sbionlmefitsa

Input Arguments

modelObject

SimBiology model object used to fit observed data.

pkModelMapObject

PKModelMap object that defines the roles of the model components

used for estimation. For more information, see

object

pkDataObject

PKData object that defines the data to use in fitting and the roles

of the columns used for estimation.

pkDataObject must define

PKModelMap

target data for at least two groups. For more information, see

PKData object.

Beta0

A vector of initial estimates for the fixed effects. The first P elements of Beta0 correspond to the fixed effects for each of the

P elements of modelMapObject.Estimated.Additional

elements correspond to the fixed effects for covariate factors. The first

P elements of Beta0 are transformed as specified by the

ParamTransform nlmefit option (log transformed by default).

For more information on specifying initial estimates see in the SimBiology documentation.

optionStruct

2-64

A struct that can contain fields and values where the field names are the parameter names accepted by

nlmefitsa and the field

values are the associated parameter v alu es.

Parameter Name/Value Pairs

This section contains a partial list of supported name/value pairs. For a complete list, see

ErrorModel

nlmefitsa in the Statistics Toolbox documentation.

Specify the error term. The available error models are:

sbionlmefitsa

• constant

• proportional

• combined

• exponential

See “Specifying an Error Model” in the SimBiology documentation.

Default:

FEGroupDesign

Specify the design matrix for each of the groups. S ee in the SimBiology documentation.

ParamTransform

Specify parameter transformations. The available transformations are: Transformations” in the SimBiology documentation.

Default:

See nlmefitsa in the Statistics Toolbox documentation for information on all the a ccepted properties including

ParamTransform and ErrorModel.

The following parameter name/value pairs are not supported:

•

FEConstDesign

• FEObsDesign

• FEParamsSelect

• REConstDesign

constant

none, log, probit,andlogit. See “Specifying Parameter

log

FEGroupDesign,

• REGroupDesign

• REObsDesign

2-65

sbionlmefitsa

• Vectorization

• Jacobian

Output Arguments

results

A structure with the following fields:

• A

results structure containing

- estimate — Estimates for the fixed effects.

- phiP — Estimated parameter values for the population

- phiI — Estimated parameter values for individuals

- beta — Esti m ates for the fixed effects in transformed s pace

as specified in the

ParamTransform option.

- psi — Estimated covariance matrix of the random effects

- stats — Structure with statistics such as AIC, and BIC.

For a complete list see documentation.

nlmefitsa in the Statistics Toolbox

- b — Estimated random effects for each group in

observedData

SimDataI

SimDataI contains the data from simulating the model using the

estimated parameter values, for individuals.

SimDataP

SimDataP contains the data from simulating the model using the

estimated parameter values, for the population.

See Also PKData object | PKModelDesign object | PKModelMap object |

Model object | sbiofitstatusplot | sbionlinfit | sbionlmefit

| nlmefit

2-66

How To •

sbionlmefitsa

2-67

sbionmfiledef

Purpose NONMEM file definition object for sbionmimport

Syntax nmdefObj = sbionmfiledef

nmdefObj = sbionmfiledef('PropertyName', PropertyValue)

Description nmdefObj = sbionmfiledef creates an NONMEM file definition object.

The NONMEM file definition object contains properties for specifying the NONMEM data items such as group, time, and dependent variable. The NONMEM file definition object lets you configure the properties to the column heading or the index of the column. Use the NONMEM file definition object in conjunction with the import NONMEM formatted files for use in fitting.

nmdefObj = sbionmfiledef('PropertyName', PropertyValue)

accepts one or more comma-separated property name/value pairs. Specify interpretations for NONMEM formatted files see “Support for Importing NONMEM F ormatted Files” in the SimBiology documentation.

PropertyName inside single quotes. To see the default

sbionmimport function to

Tips • Use sbionmfiledef with sbionmimport if you want to apply

NONMEM interpretation of headers, and the data file has column header labels different from the table shown in “Support for Importing NONMEM Formatted Files”

Input Arguments

2-68

• Use

Filename

Property Name/Value Pairs

CompartmentLabel

sbionmimport if the data file has column header labels identical

to the table shown in “Support for Importing NONMEM Formatted Files”.

If Filename extension is .xls or .xlsx it is assumed to be an Excel

sbionmfiledef file reads the file using the dataset constructor.

file, otherwise it is assumed to be a text file.

sbionmfiledef

Identifies the column in the NONMEM formatted file that contains the compartment. Specify the header name as a

string

the

or specify the index number of the header. During import

sbionmimport function uses the information in the column

to interpret which compartment receives a dose or measured an observation. The

EventIDLabel property specifies whether the

value is a dose or an observation.

char

Default:

ContinuousCovariateLabels

Identifies the column in the NONMEM formatted file that contains continuous covariates. Specify the header name as a

char string or specify the index number of the header.

Default:

DateLabel

{}

Identifies the column in the NONMEM formatted file that contains the date. Specify the header name as a

char string

or specify the index number of the header. During import the

sbionmimport function uses the information in the column to

interpret time information for each dose, response and covariate measurements.

Default:

DependentVariableLabel

Identifies the column in the NONMEM formatted file that contains observations. S pecify the header name as a or specify the index number of the header. During import the

sbionmimport function uses the information in the column to

interpret date and time information for each dose and response.

char string

Default:

2-69

sbionmfiledef

DoseLabel

Identifies the column in the NONMEM formatted file that contains the dosing information. Specify the header name as a

char string or specify the index number of the header.

Default:

DoseIntervalLabel

Identifies the column in the NONMEM formatted file that contains the time between doses. Specify the header name as a

char string or specify the index number of the header.

Default:

DoseRepeatLabel

Identifies the column in the NONMEM formatted file that contains the number of times (excluding the initial dose) that the dose is repeated. Specify the header name as a

char string or

specify the index number of the header.

Default:

EventIDLabel

Identifies the column in the NONMEM formatted file that contains the event identification specifying whether the value is a dose, observation, or covariate. Specify the header name as a

char string or specify the index number of the header.

2-70

Default:

GroupLabel

Identifies the column in the NONMEM formatted file that contains the Group ID. Specify the h eader name as a or specify the index number of the header.

char string

sbionmfiledef

Default: ''

MissingDependentVariableLabel

Identifies the column in the NONMEM formatted file that contains information about whether a row contains an observation event ( or specify the index number of the header.

0), or not (1). Specify the header name as a char string

Output Arguments

Default:

RateLabel

Identifies the column in the NONMEM formatted file that contains the rate of infusion. Specify the header name as a

string

Default:

TimeLabel

or specify the index number of the header.

Identifies the column in the NONMEM formatted file that containsthetimeordateofobservation. Duringimportthe

sbionmimport function uses this information to interpret when

a dose was given, an observation or covariate measurement recorded. Specify the header name as a

char string or specify

the index number of the header.

Default:

Type

Identifies the object as 'NMFileDef',(Read-only).

nmdefObj

Defines the meanings of the file column headings. It contains properties for specifying data items such as group, time and date.

TimeLabel and DependentVariableLabel must be specified.

char

2-71

sbionmfiledef

Examples Configure a NONMEM file definition object and import data from a

NONMEM formatted file.

% Configure a NMFileDef object.

def = sbionmfiledef; def.CompartmentLabel = 'CPT'; def.DoseLabel = 'AMT'; def.DoseIntervalLabel = 'II'; def.DoseRepeatLabel = 'ADDL'; def.GroupLabel = 'ID'; def.TimeLabel = 'TIME'; def.DependentVariableLabel = 'DV'; def.EventIDLabel = 'EVID';

filename = 'C:\work\datafiles\dose.xls'; ds = sbionmimport(filename, def);

Mathworks SIMBIOLOGY 3 Reference

Specifications and Main Features

Frequently Asked Questions

User Manual