Home

GNUMCSim: A Monte Carlo Simulation Program

1. 41 SimType specification 45 6 2 4 Specifying basic conditions to simulate 45 Simulation sections 45 StartTime specification 46 Print specification 46 PrintStep specification 46 6 2 5 Setting up statistical models 46 Level secti0n8 noRpui d den ee e Hee RR ada 48 Data specification 50 6 3 Analyzing simulation output 50 6 4 Error handimg eee ees 51 7T Common Pittallsisvcc ccsoceaasecgncwnarkernavs 53 B NCSI RE 55 Bibliographic References 57 Appendix Keywords List 59 Appendix B Examples 61 Bal linear Model isis correr geo biis de eg 61 B 2 1cpt model sample model description file 61 B 3 perc model sample model description file 63 B4 perc lsodes in veces e e SEENEN EX AE 68 Concept INd X 0006454 Ab bt n tor m OE nt 69
2. 20 VeGLOIS suk nee ar mareh ec bebe e pla EIER 19 W Working Through an Example 15 X XMCS EE 55 Table of Contents 1 Software and Documentation Licenses 1 1 1 Software license 1 1 2 Documentation license 1 2 OVERVIEW Pau durae Dok ados adole dca cp e mines 9 2 1 General procedure 9 2 2 Types of simulations 10 2 3 Major changes introduced with version 5 4 0 10 2 4 Major changes introduced with version 5 5 0 10 3 Installation e ch tte kh RR RR Rb ds 11 3 1 System requirements 11 SSC WER Ee ee DEE 11 3 3 Machine specific installation 12 3 3 1 Unix and GNU Linux operating systems 12 3 3 2 Other operating systems 13 4 Working Through an Example 15 5 Setting up Structural Models 17 5 1 Using mod to preprocess model description files 17 5 2 Using makemcsim to fully process model files 17 5 3 Syntax of the model description file 18 5 3 1 General syntax 18 5 3 2 Global variable declarations
3. 21 Installation get H Integrate specification ssi s54 36 Integration routine Euler 36 Integration routine Lsodes 36 Integration variable 27 Inverse gamma distribution 42 InvGamma distribution 42 InvGGammaRandom function 24 InvTemperature specification 39 K Keyword Compartment 30 Keywords lists same 59 L Eeyel ectlons ieskeseeewe exc eer uec ep vet 48 Hicenses sisi ile reve ni Pla RISE 1 Likelihood specification 43 lnDFNormal function 24 lnGamma function 24 Logical TES ESS ste ss Rhet tees ands 19 Lognormal distribution 42 LogNormal_v distribution 42 LogNormalRandom function 24 LogUniform distribution 42 LogUniformRandom function 24 Lsod s integrabor fee px eR ree RUSSE 36 M Major changes in version 5 4 0 10 Major changes in version 5 5 0 10 makemcsim SCript der Markov chain Monte Carlo simulations 10 37 MCMC simulations 10 37 MCMC specification Er m d BACHER ead Air ES 18 mod HE
4. 25 35 Square brackets 19 StartTime specification 46 State variables 21 Statistical models 46 Structural models 17522 StudentT distribution 43 StudentTRandom function 24 e inerte ads ie 27 ee WEE 18 Syntax of simulation files 34 T Template models 28 Tests logical 12 4 19 Triangular distribution 43 Truncated Inverse gamma distribution 43 Truncated lognormal distribution 43 Truncated normal distribution 43 TruncInvGamma distribution 43 TruncInvGGammaRandom function 24 TruncLogNormal distribution 43 TruncLogNormal_v distribution 43 TruncLogNormalRandom function 24 TruncNormal distribution 43 72 TruncNormal_v distribution 43 TruncNormalRandom function 24 U Underscore syntax for vectors 21 Underscore use for template models 30 Uniform distribution 43 UniformRandom function 24 GNU MCSim User s Manual y Variable names 19 Vectorization
5. 43 Distribution Uniform 43 Documentation license 1 Dt ee 27 Dynamics section 26 E erfc function WEE 23 Error function complementary 23 Error handling ie Ier rete ERE ERG 51 Euler integrator o l ccr as Rb een 36 Examples sisi mieu 17 61 Experiment sections 45 Experimental design optimization 10 Exponential distribution 42 70 ExpRandom function 23 F Function BetaRandom 23 Function BinomialBetaRandom 23 Function BinomialRandom 23 Function CauchyRandom 23 Function CDFNormal 23 Function Chi2Random 23 Function erfeC Se ue mms Ee 23 Function ExpRandom 23 Function GammaRandom 23 Function GetSeed 23 Function GGammaRandom 24 Function Inline in line 26 Function Inputs exse i etRkEGGheen eene RR 19 Function InvGGammaRandom 24 Function lnDFNormalO 24 Function InGamma 24 Function LogNormalRandom 24 Function LogUniformRandom 24
6. 22 Distrib specification 41 Distribution Beta 42 Distribution Binomial 42 Distribution Cauchy 42 Distribution Chi square 42 Distribution Chi2 42 Distribution Exponential 42 Distribution Gamma 42 Distribution HalfCauchy 42 Distribution HalfNormal 42 Distribution inverse gamma 42 Distribution InvGamma 42 Distribution Lognormal 42 Distribution Lognormal_v 42 Distribution Loguniform 42 Distribution Normal 42 Distribution Normal v 42 Distribution Piecewise 43 Distribution Poisson 43 Distribution StudentT 43 Distribution triangular 43 Distribution truncated inverse gamma 43 Distribution truncated lognormal 43 Distribution truncated normal 43 Distribution TruncInvGamma 43 Distribution TruncLogNormal 43 Distribution Trunclognormal v 43 Distribution TruncNormal 43 Distribution Truncnormal_v
7. 21 5 3 3 Model types 22 5 3 4 Special functions 23 5 3 5 Input functions 25 5 3 6 Inline functions 26 5 3 7 Model initialization 26 5 3 8 Dynamics section 26 5 3 9 Output calculations 2 5 3 10 Comments on style 2 5 4 Reading SBML models and applying a template 28 6 Running Simulations 33 6 1 Using the compiled program 33 6 2 Syntax of the simulation definition file 34 6 2 1 General input file syntax 35 6 2 2 Input functions revisited 35 6 2 3 Global specifications 35 ii GNU MCSim User s Manual OutputFile specification 36 Integrate specification 36 MonteCarlo specification 37 MCMC specification 37 SetPoints specification 39 OptimalDesign specification 40 Distrib specification
8. MCMC linear MCMC out 50000 0 5 40000 63453 1961 Level Distrib Alpha Normal v O 10000 Distrib Beta Normal v 0 10000 Distrib Sigma2 InvGamma 0 01 0 01 Likelihood Data y Normal v Prediction y Sigma2 Simulation x bar 3 0 PrintStep y 1 5 1 Data y 1 3 3 3 5 end Level End Semen a a The file begins with MCMC see MCMC specification page 37 The keyword Level comes next Level is used to specify hierarchical dependences between model parameters There should be at least one Level in every MCMC input file even for a non hierarchical model like the one above See below for further discussion of the Level keyword You can also look at the MCMC input files provided as examples with GNU MC Sim source code The Distrib statements define the parameter priors Normal_v specifications are used since we use variances instead of standard deviations The inverse Gamma distribution is used for the variance component since the precision is supposed to be Gamma distributed The like lihood is the distribution of the data given the model it is specified by a Likelihood specification valid for every y data point Again note that the p variable is not used Instead the Prediction y specification designates the linear model output The distribu tions and likelihoods specified are
9. 42 BetaRandom function 23 Bibliographic references 57 Binomial distribution 42 BinomialBetaRandom function 23 BinomialRandom function 23 Blank lines NENNEN NEEN stars 18 C CalcOutputs output section 27 Cauchy distribution 42 CauchyRandom function 23 CDFNormal function 23 Chi square distribution 42 Chi2 distribution ere Kuer br rr prede 42 Chi2Random function 23 Colon conditional assignment 19 Comments ege de ele EE AE EEN 18 Common pitfalls 53 Comparison operators 19 Compartment keyword 30 Complementary error function 23 Conditional assignment 19 Cumulative density function Normal 23 69 D Data qualifier for use in Distrib 43 Data specification 50 DEAN se sn eee ERR RAESURE SER 10 Defining models 17 Density function Normal 24 Density specification 43 Derivative specification Kn Differential models 22 Discrete time models
10. C central NormalRandom 0 C central CV C cen true AUC AUC NormalRandom 0 AUC CV AUC true 1n C central C central gt 0 log C central 100 1n AUC AUC gt O log AUC 100 SD C computed C central gt O C central CV C cen 1e 10 SD A computed AUC gt O AUC CV AUC 1e 10 End of output calculations Appendix B Examples 63 B 3 perc model sample model description file perc model A four compartment model of Tetrachloroethylene PERC and total metabolites CE PE SRE SRE EE EE States are quantities of PERC and metabolite formed they can be output States Q_fat Quantity of PERC in the fat Q wp in the well perfused compartment Q_pp ae in the poorly perfused compartment H liv in the liver Q_exh exhaled Qmet Quantity of metabolite formed Extra outputs are concentrations at various points Outputs C liv mg l in the liver C alv in the alveolar air C_exh in the exhaled air C_ven in the venous blood Pct_metabolized of the dose metabolized C_exh_ug ug l in the exhaled air Inputs C_inh Concentration inhaled Constants Conversions from to ppm 72 ppm 488 mg l PPM per mg per 1 72 0 0 488 mg per 1l per PPM 1 PPM per mg per 1 nn Es Nominal values for parameters Units Volumes liter Vmax mg minute Weights kg Km mg minute Time minute Flows Liter
11. Mod lets the user create and modify models without having to maintain C code Under Unix or GNU Linux the command line syntax for the mod program is mod input file output file where the brackets indicate that the input and output filenames are optional If the input filename is not specified the program will prompt for both If only the input filename is specified the output is written by default to the file model c Unless you feel like doing some makefile programming we recommend using this default since the makefile for GNU MCSim assumes the C language model file to have this name You have to have prepared a text file containing a description of the model following the syntax described in the following see Section 5 3 Syntax of mod files page 18 The following options are available h H gives a short online help R generate a C file of the format requested for use by the deSolve package of the R software for statistical analysis deSolve implements differential equations solvers with interesting capabilities Most error messages given by mod are self explanatory Where appropriate they also give the line number in the model file where the error occurred Beware however of cascades of errors generated as a consequence of a first one so don t panic start by fixing the first one and rerun mod If you get really stuck you can send a message to the help mailing list see Chapter 3 Installation page 11 or to the authors of th
12. The parameter vector alpha is defined with range 0 to 2 each component being initialized to value 1 For parameter beta components 0 1 and 2 to 4 are initialized separately components 2 to 4 are initialized with default value 0 Accessing vectors components After declaration vector s components can be accessed individually using the square bracket syntax lt variable name gt integer For example Outputs x 0 1 beta 0 0 beta 1 beta 0 1 CalcOutputs x 0 beta 0 t x 1 beta 1 t In the above example beta 0 beta 1 x 0 and x 1 are accessed individu ally The variable t refers to the implicit variable time Vectorization of equations The equations specifying the model which consist in assign ments can be vectorized in the Initialize Dynamics and CalcOutputs sections but not in the global section see Section 5 3 2 Global variable declarations page 21 Vectorization allows you to specify an operation for an entire vector or parts of it The following syntax should be used lt var name gt lt integer gt lt integer gt lt vectorized expression gt On the right hand side the vectorized expression should be a valid C mathematical expression including numerical constants already defined state input output other parameter variables or vectors and standard ANSI C mathematical functions or special functi
13. in the vari ous original documents forming one section Entitled History likewise combine any sections Entitled Acknowledgements and any sections Entitled Dedications You must delete all sections Entitled Endorsements GNU MCSim User s Manual COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License and replace the individual copies of this License in the various documents with a single copy that is included in the collection provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects You may extract a single document from such a collection and distribute it individu ally under this License provided you insert a copy of this License into the extracted document and follow this License in all other respects regarding verbatim copying of that document AGGREGATION WITH INDEPENDENT WORKS compilation of the Document or its derivatives with other separate and independent documents or works in or on a volume of a storage or distribution medium is called an aggregate if the copyright resulting from the compilation is not used to limit the legal rights of the compilation s users beyond what the individual works permit When the Document is included in an aggregate this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document
14. minute 64 GNU MCSim User s Manual Period 0 0 Exposure 0 0 C inh PerDose InhMag Period 0 0 Exposure LeanBodyWt 55 lean body weight Percent mass of tissues with ranges shown Pct M fat 16 total body mass Pct LM liv 03 liver of lean mass Pct LM wp 17 well perfused tissue of lean mass Pct LN pp 70 poorly perfused tissue recomputed in scale Percent blood flows to tissues Pct Flow fat 09 Pct Flow liv 34 Pct Flow wp 50 will be recomputed in scale Pct Flow pp 07 Tissue blood partition coeficients PC fat 144 PC liv 4 6 PC wp 8 7 PC pp 1 4 PC art 12 0 Flow pul 8 0 Pulmonary ventilation rate minute volume Vent Perf 1 14 ventilation over perfusion ratio sc Vmax 0026 scaling coeficient of body weight for Vmax Km 1 0 The following parameters are calculated from the above values in the Scale section before the start of each simulation They are left uninitialized here BodyWt 0 V fat Actual volume of tissues V liv V wp V pp l ee Il we Appendix B Examples 65 Flow fat 0 Actual blood flows through tissues Flow liv 0 Flow wp 0 Flow pp 0 Flow tot 0 Total blood flow Flow alv 0 Alveolar ventilation rate Vmax 0 kg minute SSeS Se ee Se Se eae nn Dynamics Define the dynamics of the simulation This section is calcula
15. or distribute the Document except as expressly provided for under this License Any other attempt to copy modify sublicense or distribute the Document is void and will automatically terminate your rights under this License However parties who have received copies or rights from you under this License will not have their licenses terminated so long as such parties remain in full compliance Chapter 1 Software and Documentation Licenses 7 10 FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new revised versions of the GNU Free Documentation License from time to time Such new versions will be similar in spirit to the present version but may differ in detail to address new problems or concerns See http www gnu org copyleft Each version of the License is given a distinguishing version number If the Document specifies that a particular numbered version of this License or any later version applies to it you have the option of following the terms and conditions either of that specified version or of any later version that has been published not as a draft by the Free Software Foundation If the Document does not specify a version number of this License you may choose any version ever published not as a draft by the Free Software Foundation Chapter 2 Overview 9 2 Overview GNU MCSim is a simulation and statistical inference tool for algebraic or differential equa tion systems Other programs
16. Dynamics section Time t is the integration variable but here again t can be used to represent anything you want For partial differen tial equations some problems might be solved by implementing line methods see examples in mcsim samples pde1 and mcsim samples pde2 You can use GNU MCSim for discrete time dynamic models or difference models That is a bit tricky Assignments in the CalcOutputs section are volatile not memorized so the model equations have to be given in a Dynamics section But the model variables should still be declared as outputs because they should not be updated by integration However you need at least one true differential equation in the Dynamics section so you should declare a dummy state variable and assign to its derivative a constant value of zero You also want the calls to Dynamics to be precisely scheduled so it is best to use the Euler integration routine see Integrate specification page 36 which uses a constant step Since Euler may call repeatedly Dynamics at any given time you want to guard against untimely updating Altogether we recommend that you examine the sample files in the mcsim samples discrete directory provided with the source code for GNU MCSim 5 3 4 Special functions The following special functions whose name is case sensitive are available to the user for assignment of parameters and variables in the model definition file e BetaRandom alpha beta a b returns a Be
17. If the Cover Text requirement of section 3 is applicable to these copies of the Document then if the Document is less than one half of the entire aggregate the Document s Cover Texts may be placed on covers that bracket the Document within the aggregate or the electronic equivalent of covers if the Document is in electronic form Otherwise they must appear on printed covers that bracket the whole aggregate TRANSLATION Iranslation is considered a kind of modification so you may distribute translations of the Document under the terms of section 4 Replacing Invariant Sections with translations requires special permission from their copyright holders but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections You may include a translation of this License and all the license notices in the Document and any Warranty Disclaimers provided that you also include the original English version of this License and the original versions of those notices and disclaimers In case of a disagreement between the translation and the original version of this License or a notice or disclaimer the original version will prevail If a section in the Document is Entitled Acknowledgements Dedications or His tory the requirement section 4 to Preserve its Title section 1 will typically require changing the actual title TERMINATION You may not copy modify sublicense
18. M 1991 Bayesian computational methods Philosophical Transactions of the Royal Society of London Series A 337 369 386 Smith A F M and Roberts G O 1993 Bayesian computation via the Gibbs sampler and related Markov chain Monte Carlo methods Journal of the Royal Statistical Society Series B 55 3 23 58 GNU MCSim User s Manual Vattulainen L Ala Nissila T and Kankaala K 1994 Physical tests for random num bers in simulations Physical Review Letters 73 2513 2516 Appendix A Keywords List 59 Appendix A Keywords List You should avoid using the following reserved keywords when building your models Beta BetaRandom Binomial BinomialBetaRandom BinomialRandom CDFNormal CalcOutputs CauchyRandom Chi2 Chi2Random Data DefaultSim Density Distrib dt Dynamics End Euler ExpRandom Experiment Exponential GGammaRandom Gamma GammaRandom GetSeed Gibbs IFN Initialize Inputs Integrate InvGGammaRandom InvGamma Level Likelihood InDF Normal InGamma LogNormal LogNormalRandom LogNormal_v LogUniform LogUniformRandom Lsodes MCMC MonteCarlo NDoses Normal NormalRandom Normal_v OptimalDesign OutputFile Outputs PerDose PerExp Piecewise PiecewiseRandom Poisson PoissonRandom Prediction Print PrintStep Scale SetPoints SetSeed SimType Simulation Spikes Start Time States StudentTRandom t TruncLogNormal TruncLogNormalRandom TruncLogNormal_v TruncNormal TruncNormalR
19. Preserve all the Invariant Sections of the Document unaltered in their text and in their titles Section numbers or the equivalent are not considered part of the section titles M Delete any section Entitled Endorsements Such a section may not be included in the Modified Version N Do not retitle any existing section to be Entitled Endorsements or to conflict in title with any Invariant Section O Preserve any Warranty Disclaimers If the Modified Version includes new front matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document you may at your option designate some or all of these sections as invariant To do this add their titles to the list of Invariant Sections in the Modified Version s license notice These titles must be distinct from any other section titles You may add a section Entitled Endorsements provided it contains nothing but endorsements of your Modified Version by various parties for example statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard You may add a passage of up to five words as a Front Cover Text and a passage of up to 25 words as a Back Cover Text to the end of the list of Cover Texts in the Modified Version Only one passage of Front Cover Text and one of Back Cover Text may be added by or through arrangements made by any one entity If the Document already includes
20. a b returns a truncated normal variate with pre scribed mean and standard deviation in the range a b Explicit specification of a b is required UniformRandom min max returns a uniformly distributed random variable sampled between min and max The algorithm used is that of Park and Miller Barry 1996 Park and Miller 1988 Vattulainen et al 1994 see Bibliographic References page 57 A default random generator seed 314159265 3589793 is used Note for all the above random number generating functions a default random generator seed is used It can be changed with the function SetSeed Note also that assignment of a random number generating function to a state variable derivative will define a form of stochastic differential equation GNU MCSim s integration routines are not particularly suited to the resolution of such equations If you wish to try it anyway you may want to consider using the robust Euler method see Integrate specification page 36 Chapter 5 Setting up Structural Models 25 5 3 5 Input functions These functions can be used in special assignments valid only for input variables Inputs can be initialized to a constant or to a standard mathematical expression or assigned one of the following input functions e PerDose specifies a periodic input of constant magnitude The input begins at lt initial time gt in the period and lasts for lt exposure time gt time units Syntax PerDo
21. are strictly positive e InvGamma inverse gamma distribution needs two strictly positive real parameters the shape and the scale e LogNormal takes two reals numbers as parameters the geometric mean exponential of the mean in log space and the geometric standard deviation exponential strictly superior to 1 of the standard deviation in log space e LogNormal v is the lognormal distribution with the variance in log space instead of the standard deviation as second parameter You can use it to specify a hierarchical model with a conjugate prior on the variance see Section 6 2 5 Setting up statistical models page 46 e LogUniform with two shape parameters the minimum and the maximum of the sam pling range real numbers in natural space e Normal takes two reals numbers as parameters the mean and the standard deviation the latter being strictly positive e Normal v is also the normal distribution with the variance instead of the standard deviation as second parameter You can use it to specify a hierarchical model with a conjugate prior on the variance see Section 6 2 5 Setting up statistical models page 46 Chapter 6 Running Simulations 43 e Piecewise uses four reals as parameters the minimum A B and the maximum The distribution has the form of a truncated triangle with a plateau between A and B If A B the distribution is the triangular distribution e Poisson needs a strictly positive real the
22. be valid filenames Give that file as input to mod by typing in mod SBML List in on your shell com mand line A model c file is produced suitable for further compilation by makemcsim SBML model files are typically ASCII text files with a xml extension for examples see mcsim sim samples SBML SBML Level 1 and Level 2 are recognized but some features of Level 2 are not yet understood by mod such as functionDefinition unit rateRule and a few others Omitted reaction stoichiometries are set to value 1 by default Com partments are ignored unless a model template for circulating species is given see below If two or more of the SBML files define a same chemical species mod merges the models namely the rate equation for that species will be the sum of the rate equations implied by each model In fact mod constructs the rate equations from the reaction descriptions given by the SBML format State variables and parameters keep the same name after merging so they should be unique from the start to each SBML model to avoid confusion To automatically extend SBML level 2 models e g with transport component terms an example which will be used throughout this part of the manual a template model can be applied to all the species defined in SBML which are placed in the default compartment conventionally called compartment and outside of other compartments whose names are specified by the template itself Specifically the template model
23. can be assigned all the input functions defined previously see Section 5 3 5 Input functions page 25 Briefly these are e PerDose PerDose lt magnitude gt period lt initial time gt lt exposure time gt e PerExp PerExp lt magnitude gt lt period gt lt initial time gt lt decay constant gt e NDoses NDoses lt n gt lt list of magnitudes gt lt list of initial times gt e Spikes Spikes lt n gt lt list of magnitudes gt lt list of times gt 6 2 3 Global specifications In the global section you can modify by assignment the value of already defined state or input model variables or parameters you cannot assign a value to an output variable These assignments will be in effect throughout the input file unless they are overridden later in the file Here is an exemple of assignment assuming that x and Pi have been properly defined in the model definition file x 10 set the initial value if x is a state variable Pi 3 to stop worrying about little decimals 36 GNU MCSim User s Manual In the global section you can also give specifications relevant to all Simulation or Level sections These specifications are not needed if you just want to perform simple simulations They should also not appear inside Simulation or Level sections with the notable exception of Distrib specifications which can appear inside Level sections They are used to call for and define the par
24. mcsim directory just created and issue the following commands configure make make check The first command above checks for the availability of the tools needed for installation and proper running of the software The second compiles the mod program and the dynamic libmcsim so library and eventually compiles this manual in various formats The third checks whether the software is running and producing meaningful results in test cases In case of error messages don t panic check the actual differences between the culprit output file and the file sim out produced by the checking Small differences may occur from different machine precision This can happen for random numbers in which case the Markov chain simulations MCMC can diverge greatly after a while If you are logged in as root or have sufficient access rights you can then install the software in common directories in usr by typing at the shell prompt make install If this system wide installation is successful the executable files nod makemcsim xmcsim are installed in usr local bin The library libmcsim is placed in usr local lib A copy of the mcsim source directory with the mod sim doc samples and xmcsim subdirectories is placed in usr local share If you have the GNU info system available an mcsim node is added to the main info menu so that info mcsim will show you this manual Finally a symbolic link to usr local share mcsim doc which contains the documentat
25. parameters in this section causes an error message like the following to be issued Error line 48 YourParm used in invalid context Parameters cannot be defined in Dynamics section 5 3 9 Output calculations The output calculation section begins with the keyword CalcOutputs and is enclosed in curly braces The equations given in this section will be called by the simulation pro gram at each output time specified by a Print or PrintStep statement see Print specification page 46 and see PrintStep specification page 46 In this way output computations are done efficiently only when values are to be saved Only variables that have been declared with the keyword Outputs or local temporary variables can receive assignments in this section Assignments to other types of variables cause an error message like the following to be issued Error line 56 Up fat used in invalid context Only output and local variables can be defined in CalcOutputs section Any reference to an input or state variable will use the current value at the time of output The dt O operator can appear in the right hand side of equations and refers to current values of the derivatives see Section 5 3 8 Dynamics section page 26 Like in the Dynamics section the integration variable can be accessed if referred to as t as in Us out DQx t 5 3 10 Comments on style For your model file to be readable and understandable it is useful to u
26. pde2 directory Alternative underscore _ syntax Individual vector components can be declared and used everywhere in the model file with the following syntax lt variable name gt _ lt integer gt The integer indicates which component of the vector is referred to For example x_1 is strictly equivalent to x 1 Note No space are allowed between the variable name the underscore and the integer Note also This syntax is the only one that can be used in simulation specification files If you declare a parameter beta 1 10 in your model definition file the only way to refer to it in the simulation input file will be through its individual components beta_1 beta_2 etc This limitation will be removed in a future release of the software 5 3 2 Global variable declarations Commands not specified within the delimiting braces of another section are considered to be global declarations In the global section you first declare the state input and output variables There should be at least one state or output variable in your model e States are variables for which a first order differential equation is defined in the Dynamics section see Section 5 3 8 Dynamics section page 26 higher orders or partial differential equations are not allowed e Inputs are variables independent of the others variables but eventually varying with time for example an exposure concentration to a chemic
27. preprocess your structural model description file Mod creates a C file called model c 3 You compile and link the newly created model c file together with a library containing the other C routines or with the other C files of the mcsim sim directory GNU MCSim C code is standard so you should be able to compile it with any standard C compiler for example GNU gcc After compiling and linking an executable simula tion program is created specific of your particular model These preprocessing and compilation steps can be performed in Unix with a single shell command makemcsim in which case the model c is created only temporarily and erased afterward This produces the most efficient code for your particular machine 4 You then write any number of simulation specification files and run them with the compiled mcsim program These simulation files describe the kind of simulation to run simple simulations Monte Carlo etc various settings for the integration algorithm if needed and a description of one or several simulation conditions eventually with a statistical model and data to fit see Chapter 6 Running Simulations page 33 The simulation output is written to standard ASCII files Little or no knowledge of computer programming is required unless you want to tailor the program to special needs beyond what is described in this manual in which case you may want to contact us Under Unix a graphical user interface written in
28. should define compart ments and differential equations terms for the transport of an unspecified species between those compartments the syntax for that will be described below For each species placed in SBML outside one of the defined compartments a differential equations is created for each compartment using the template transport terms The differentials for the compart ments found in both the template and the SBML models will contain both transport and kinetic terms With the exception of the generic compartment the SBML models merged can only use the compartments defined by the template compartment name recognition is case sensitive Species placed in SBML inside one of the defined compartments are not transported and stay local to that compartment Their differentials will contain only the reaction kinetics terms defined by the SBML models For simplicity the default initial values of the model state variables species specified by the user are ignored and set to Zero There might be many applications of the template mechanism and they are left to the reader to imagine The template model is specified with PKTemplate keyword followed by an equal sign and the file name of a template model file of maximum size MAX FILENAMESIZE 80 characters as defined in mod h enclosed in curly braces like in SBML List in Use it as mod SBML List in PKTemplate input_f 2cpt_PBPK model SBMLModels C_central xml C_periph x
29. the error occurred Beware however of cascades of errors generated as a consequence of a first one also errors may be detected after the line in which they really occur and the line number shown will be unhelpful don t panic start by fixing the first error in the input file and rerun your executable You should not need to recompile your executable unless you have changed the model itself If you get really stuck you can send a message to the mailing list help mcsim prep ai mit edu see Chapter 3 Installation page 11 or to the authors of this manual The program ends if everything is fine by giving you the name of the output file generated If you want to run the program in batch mode in the background you may want to redirect the screen output and error messages refer for this to the man pages for your shell 34 GNU MCSim User s Manual 6 2 Syntax of the simulation definition file A simulation specification file is a text ASCII file that consists of several sections starting with global specifications and assignments valid throughout the file followed by a number of Simulation sections see Simulation sections page 45 eventually enclosed in Level sections The keyword Experiment is now obsolete but can still be used as a synonym for Simulation Each Simulation section defines simulation conditions from an initial time or whatever the dependent variable represents see Section 5 3 3 Model types page 22 to a fin
30. the log of the returned variate is normally distributed with mean In mean standard deviation In sd LogUniformRandom a b returns variate log uniformly distributed on the interval a b NormalRandom mean sd returns a normally distributed random variable with pre scribed mean and standard deviation PiecewiseRandom min a b max the distribution of the returned variate has the form of a truncated triangle with base from min to max and a plateau between a and b If a b the distribution is the triangular distribution PoissonRandom mu returns a Poisson distributed random variate of rate mu SetSeed seed sets the current value of the pseudo random generator seed to the specified seed That seed can be any positive real number Seeds between 1 0 and 2147483646 0 are used as is the others are rescaled within those bounds and a warning is issued StudentTRandom dof mean sd returns a Student t distributed random variate with dof degrees of freedom and given mean and standard deviation TruncInvGGammaRandom alpha beta a b returns a truncated inverse gamma dis tributed random variate with shape parameter alpha and scale beta in the range a b Explicit specification of a b is required TruncLogNormalRandom mean sd a b returns a truncated lognormal variate with geometric mean mean and geometric standard deviation sd in the range a b Explicit specification of a b is required TruncNormalRandom mean sd
31. the parameter to sample The distribution name and the corresponding shape parameters indicate the sampling distribution to use Bernardo and Smith 1994 Gelman et al 1995 see Bibliographic References page 57 They are specified as follow e Beta takes at least two strictly positive real shape parameters and B By default the Beta distribution is defined over the interval 0 1 If a range is given for the beta distribution the 0 1 interval is mapped onto the specified range e Binomial needs two strictly positive numbers the probability p a real in the interval 0 1 and the sample size N an integer If N is not given as an integer it will be rounded down during the computations e Cauchy takes one strictly positive real number as parameter its scale s e Chi2 takes one strictly positive real number as parameter n This distribution is the same as Gamma n 2 1 2 e Exponential uses one strictly positive real number the inverse scale b The density of this distribution is equal to be hr e Gamma uses two strictly positive real parameter the shape and the inverse scale e HalfCauchy takes one strictly positive real number as parameter the scale s The mode is at zero on the lower boundary The random variates returned are strictly positive e HalfNormal takes one reals number as parameter the standard deviation strictly positive The mode is at zero on the lower boundary The random variates returned
32. to state variables affect initial values only In this section state variables outputs and parameters but not input variables can also appear at the the right hand side of equations The integration variable can be accessed if referred to as t Additional parameters to those declared in the global section may be used within the section They will be declared as local temporary variables and their scope will be limited to the Initialize section 1 e their value and existence will be forgotten outside the section The dt O operator see Section 5 3 8 Dynamics section page 26 cannot be used in this section since derivatives have not yet been computed when the scaling function is called 5 3 8 Dynamics section The dynamics specification section begins with the keyword Dynamics and is enclosed in curly braces The equations given in this section will be called by the integration routines at each integration step Dynamics must be used if the model includes differential equations Additional parameters to those declared in the global section may be used for any calculations within the section They will be declared as local temporary variables Note for example the use of Cout_fat and Cout_wp in the perc model sample file Local variables are not accessible from the simulation program or from other sections of the model definition file so don t try to output them Each state variable declared in the global section must
33. underscore _ and followed by any number of alpha numeric characters or underscores up to a maximum of 80 Variable names are case sensitive Note that the name IFN in capital letters is reserved by the program and should not be used as parameter or variable name e Variable assignments have the following syntax lt variable name gt lt constant value or expression gt The equal sign is needed The right hand side expression can be a valid C mathematical expression including numerical constants already defined variables standard ANSI C mathematical functions and GNU MCSim s special functions see Section 5 3 4 Special functions page 23 or input functions see Section 5 3 5 Input functions page 25 Special functions can take already defined variables constant values or expressions as parameters Input functions can only be used on the right hand side of assignments to input variables Colon conditional assignments have the following syntax lt variable name gt lt test gt lt value if true gt lt value if false gt For example Adjusted_Param Input_Var gt 0 0 Param 1 1 Param In this example if Input_Var is greater than 0 the parameter Adjusted_Param is computed as the product of Param by 1 1 otherwise Adjusted_Param is equal to Param Note that conditional assignments can be nested ie lt value if true gt or lt value if false gt can themselve
34. with all words of the title equally prominent and visible You may add other material on the covers in addition Copying with changes limited to the covers as long as they preserve the title of the Document and satisfy these conditions can be treated as verbatim copying in other respects If the required texts for either cover are too voluminous to fit legibly you should put the first ones listed as many as fit reasonably on the actual cover and continue the rest onto adjacent pages If you publish or distribute Opaque copies of the Document numbering more than 100 you must either include a machine readable Transparent copy along with each Opaque copy or state in or with each Opaque copy a computer network location from which the general network using public has access to download using public standard network protocols a complete Transparent copy of the Document free of added material If you use the latter option you must take reasonably prudent steps when you begin distribution of Opaque copies in quantity to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy directly or through your agents or retailers of that edition to the public GNU MCSim User s Manual It is requested but not required that you contact the authors of the Document well before redistributing any large number of copies to give them a chance to provide yo
35. EE 18 SetPoints simulations 10 SetPoints specification 39 SetSeed function 24 Setting up statistical models 46 Setting up structural models 17 SimType specification 45 Simulation definition files 33 Simulation file syntax 34 Simulation sections 45 Software license dl Special functions 19 23 Specification Data 50 Specification Density 43 Specification Distrib 41 Specification Integrate 36 Specification InvTemperature 39 Specification Likelihood 43 Specification MCMC 37 Specification MonteCarlo 37 Specification OptimalDesign 40 Specification OutputFile 36 Specification Print 46 Specification PrintStep 46 Specification SetPoints 39 Specification SimType 45 Specification StartTime 46 Specifications global 39 Specifying simulations 33 Spikes function
36. Function NDoses 25 35 Function NormalRandom 24 Function PerDose 25 35 Function PerExp 20 g 2 SEELEN 25 35 Function PiecewiseRandom 24 Function PoissonRandom 24 Function SetSeed 24 Function special 4 ege ele RR es 19 Function Spikes 25 35 Function StudentTRandom 24 Function TruncInvGGammaRandom 24 Function TruncLogNormalRandom 24 Function TruncNormalRandom 24 Function UniformRandom 24 Functions input 25 35 Functions special 23 G Gamma distribution 42 Gamma function 24 GammaRandom function 29 General input file syntax 35 GetSeed function 23 GGammaRandom function 24 Global specifications 35 H HalfCauchy distribution 42 HalfNormal distribution 42 I Initialize initialization section 26 Inline in line functions 26 GNU MCSim User s Manual Input functions 19 25 35 Input variables
37. GNUMCSim A Monte Carlo Simulation Program by Fr d ric Y Bois and Don R Maszle User s Manual software version 5 5 0 Copyright c 1997 2000 2004 2007 2011 Free Software Foundation Inc Permission is granted to copy distribute and or modify this document under the terms of the GNU Free Documentation License Version 1 2 or any later version published by the Free Software Foundation with no Invariant Sections no Front Cover Texts and no Back Cover Texts copy of the license is included in the section entitled GNU Free Documentation License contact Frederic Bois fbois amp member fsf org Chapter 1 Software and Documentation Licenses 1 1 Software and Documentation Licenses 1 1 Software license GNU MCSim is free software you can redistribute it and or modify it under the terms of the GNU General Public License as published by the Free Software Foundation either version 3 of the License or at your option any later version This program is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE See the GNU General Public License for more details 1 2 Documentation license The GNU Free Documentation License Version 1 2 November 2002 Copyright c 2000 2001 2002 Free Software Foundation Inc 51 Franklin St Fifth Floor Boston MA 02110 1301 USA Everyone is permitted to copy and distribute v
38. Installation 3 1 System requirements GNU MCSim is written in ANSI standard C language We are distributing the source code and you should be able to compile it for any system provided you have an ANSI C compliant compiler Starting with version 5 0 0 GNU MCSim is using routines from the GNU Scientific Library libgsl We recommend that you install version 1 5 or higher of the shared GSL library gslcblas library and GSL include files on your system Version 5 4 0 and higher of GNU MCSim can take advantage of 1ibSBML to read SBML models If you choose to install HbSBML on your system we recommend that you use version 3 3 2 or higher of libSBML LibSBML needs an XML parser library either Expat Xerces or libxml2 The Expat library has worked well for us under Linux On any system we recommend the GNU gcc compiler freeware The automated instal lation script checks for the availability on your system of the tools needed for compilation and proper running of the software It should warn you of missing component and even tually adapt the installation to your needs for example by installing the package locally if you do not have superuser s priviledges To run the graphical user interface XMCsim you need a GNU Linux or Unix system with XWindows Tcl Tk and wish installed 3 2 Distribution GNU MCSim source code is available on Internet through http savannah gnu org projects mcsim Packaged distributions are availab
39. RE deg Ee et eR die S as oes I es 17 Model definition files 17 Model types scie meer mere eyes 22 Models algebraic 22 Models differential 22 Models discrete time 22 Models statistical 46 Monte Carlo simulations 10 Ar MonteCarlo specification 3T N NDoses function 25 35 Normal cumulative density function 23 Normal density function 24 Normal distribution 42 Normal_v distribution 42 Concept Index NormalRandom function 24 O OptimalDesign O specification 40 Output specification 27 Output variables 21 OutputFile specification 36 Overview EE qb Ee der ERE E 9 P Parameter declaration 21 Parameter scaling EN NENNEN os 26 PerDose function 25 35 PerExp function 25 35 Piecewise distribution 43 PiecewiseRandom function 24 teller dike s Me t M RP LIE REI 53 Poisson distribution 43 PoissonRandom function 24 Prediction qualifier for use i
40. Tcl Tk XMCSim called by the com mand xmcsim is also provided This menu driven interface automatizes the compilation 10 GNU MCSim User s Manual and running tasks It also offers a convenient interface to 2 D and 3 D plotting of the simulation results 2 2 Types of simulations Five types of simulations are available A simple simulation will solve eventually integrate the equations you specified using the default parameter values eventually overridden in the simulation specification file User requested outputs are sent to an output file of your choice Monte Carlo simulations will perform repeated stochastic simulations across a ran domly sampled region of the model parameter space see MonteCarlo specification page 37 A Markov chain Monte Carlo MCMC simulation performs a series of simulations along a Markov chain in the model parameter space see MCMC specification page 37 In MCMC simulations the random choice of a new parameter value is in fluenced by the current value They can be used to obtain the Bayesian posterior distribution of the model parameters given a statistical model prior parameter dis tributions that you need to specify and data for which a likelihood function can be computed The program handles hierarchical e g random effects and mixed effects statistical models see Section 6 2 5 Setting up statistical models page 46 SetPoints simulation solves the model for a series
41. a cover text for the same cover previously added by you or by arrangement made by the same entity you are acting on behalf of you may not add another but you may replace the old one on explicit permission from the previous publisher that added the old one The author s and publisher s of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version 5 COMBINING DOCUMENTS You may combine the Document with other documents released under this License under the terms defined in section 4 above for modified versions provided that you include in the combination all of the Invariant Sections of all of the original documents unmodified and list them all as Invariant Sections of your combined work in its license notice and that you preserve all their Warranty Disclaimers The combined work need only contain one copy of this License and multiple identical Invariant Sections may be replaced with a single copy If there are multiple Invariant Sections with the same name but different contents make the title of each such section unique by adding at the end of it in parentheses the name of the original author or publisher of that section if known or else a unique number Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work In the combination you must combine any sections Entitled History
42. ain where you left it since an MCMC output file can be used as a restart file with no change Note that the first line of the file which typically contains column headers is skipped Also the number of lines in the file must be less than or equal to lt nRuns gt The first column of the file should be integers and the following columns tab or space separated should give the various parameters in the same order as specified in the list of Distrib specifications in the input file If a data file name is given the observed data values for the simulated outputs will be read from that file in ASCII format otherwise Data specifications see Data speci fication page 50 should be provided We recommend that you use Data specifications rather that the data file which is much more error prone The first line of the data file is skipped and can be used for comments The total number of data points should equal the total number of outputs requested The data values should be given on the second and following lines separated by white spaces or tabs A data value of 1 will be treated as missing data and ignored in likelihood calculations The convention 1 can be changed by changing INPUT_MISSING_VALUE in the header file mc h and recompiling the entire library The integer lt nRuns gt gives the total number of runs to be performed including the runs eventually read in the restart file The next field lt simTypeFlag gt sh
43. ained in the following see Distrib specification page 41 The format of the output file of Monte Carlo simulations is discussed later see Section 6 3 Analyzing simulation output page 50 MCMC specification Markov chain Monte Carlo MCMC can be defined as stochastic simulations following a Markov chain in a given parameter space In MCMC simulations the random choice of a new parameter value is influenced by the current value They can be used to obtain a sample of parameter values from complex distribution functions eventually intractable analytically Such complex distribution functions are typically encountered during Bayesian data analysis under the guise of posterior distributions of a model s parameters The reader wishing to use the MCMC capabilities of GNU MCSim is referred to the published literature for example Bernardo and Smith 1994 Gelman 1992 Gelman et al 1995 Gelman et al 1996 Gilks et al 1996 Smith 1991 Smith and Roberts 1993 see Bibliographic References page 57 MCMC simulation chains which in GNU MCSim start from a sample from the specified prior need to reach equilibrium Checking that equilibrium is obtained is best achieved in our opinion by running multiple independent chains cf Gelman and Rubin 1992 and other relevant statistical literature GNU MCSim does not deal yet with convergence issues The Bayesian analysis of data with GNU MCSim requires you to setup a stru
44. al e Outputs are dependent model variables obtainable at any time as analytical functions of the states inputs or parameters that do not have dynamics They can receive assignments in the Dynamics or CalcOutputs sections The format for declaring each of these variables is the same and consists of the keyword States Inputs or Outputs followed by an equal sign and a list of the variable names enclosed in curly braces as shown here States Qb_fat Benzene in the fat Qb_bm Ho in the bone marrow Qb liv in the liver and others 22 GNU MCSim User s Manual Inputs iQ eau Gavage dose C inh Inhalation concentration Outputs iCb exp Concentration in expired air Cb ven in venous blood After being defined states inputs and outputs can then be given initial values con stants or expressions Inputs can also be assigned input functions described below see Section 5 3 5 Input functions page 25 Some examples of initialization are shown here Qb 0 1 Default initial value for state variable Qb Input variable assigned a periodic exponential input function Q PerExp 1 60 0 1 Magnitude of 1 0 period of 60 time units TO in period is O0 Rate constant is 1 0 If a state input or output variable is not explicitly given an initial value that value will be set to zero by default Initial values are reset to their specified value by the simu lation program at the start of each si
45. al time Initial values of the model state variables parameter values input variables time course and which outputs are to be printed at which times can all be changed in a given Simulation section In simple cases the general layout of the file is therefore see also the sample file in Section B 4 perc lsodes in page 68 Input file text after are comments Global assignments and specifications Simulation 1 Specifications for first simulation Simulation lt Specifications for second simulation gt Unlimited number of simulation specifications End Optional End statement Everything after this line is ignored For Markov chain Monte Carlo simulations see MCMC specification page 37 the general layout of the file must include Level sections Level sections are used to define a hierarchy of statistical dependencies see Section 6 2 5 Setting up statistical models page 46 In that case the general layout of the file is Input file Global assignments and specifications Level 1 Up to 10 levels of hierarchy Simulation 1 Specifications and data for first simulation Simulation lt Specifications and data for second simulation gt Unlimited number of simulation specifications end Level End Optional statement Chapter 6 Running Simulations 35 6 2 1 General input file syntax The general syntax of the file is the same as that of structural model definition files see Sec
46. aling and output computations Here is a template for such a file for further examples see Appendix B Examples page 61 Model description file this is a comment Global variable specifications Initialize 1 Equations for initializing or scaling model parameters Dynamics lt Equations for computing derivatives of the state variables gt CalcOutputs 1 lt Equations for computing output variables gt Initialize Dynamics and CalcOutputs are reserved keywords and if used must ap pear as shown followed by the curly braces which delimit each section see Section 5 3 7 Model initialization page 26 Section 5 3 8 Dynamics section page 26 Section 5 3 9 Output calculations page 27 Please note that at least one of the sections Dynamics or CalcOutputs should be defined and that Dynamics must be used if the model includes differential equations 5 3 1 General syntax The general syntax of the model description file is as follows e Comments begin with a pound sign and continue to the end of the line e Blank lines are allowed and ignored e All commands can span several lines and are terminated by a semi colon Chapter 5 Setting up Structural Models 19 e Four types of variables are used state variables output variables input variables and parameters see Section 5 3 2 Global variable declarations page 21 The name of a variable should be a valid C identifier starting with a letter or
47. all the variables specified The size of the time list is only limited by the available memory at run time The limit of 10 variables names can be increased by changing MAX PRINT VARS in the header file sim h and re installing the whole software The number of Print statements you can used in a given Simulation section is only limited by the available memory at run time The same variable or parameter can appear in more than one PrintStep in a given Simulation section PrintStep specification The value of any model variable can be also output with PrintStep specifications They allow dense printing suitable for smooth plots for example The arguments are the name of only one variable the first output time the last one and a time increment PrintStep lt variable identifier gt lt start time gt lt end time gt lt time step gt The final time has to be superior to the initial time and the time step has to be less than the time span between end and start If the time step is not an exact divider of the time span the last printing step is shorter and the last output time is still the end time specified The number of outputs produced is only limited by the memory available at run time You can use several PrintStep and the same variable or parameter can appear in more than one PrintStep in a given Simulation section 6 2 5 Setting up statistical models With GNU MCSim you must define a statistical model to use the MCMC sp
48. ameters of special computations e g the number of Monte Carlo simulations to run which sampling distributions to use for a given parameter the data likelihood etc These specifications are the following OutputFile specification The OutputFile specification allows you to specify a name for the output file of basic simulations If this specification is not given the name sim out is used if none has been supplied on the command line or during the initial dialog The corresponding syntax is OutputFile lt OutputFilename gt where the character string lt OutputFilename gt enclosed in double quotes should be a valid file name for your operating system Integrate specification The integrator settings can be changed with the Integrate specification Two integration routines are provided Lsodes which originates from the SLAC Fortran library and is originally based on Gear s routine Gear 1971b Gear 1971a Press et al 1989 see Bibliographic References page 57 and Euler Press et al 1989 The syntax for Lsodes is Integrate Lsodes lt rtol gt lt atol gt lt method gt where lt rtol gt is a scalar specifying the relative error tolerance for each integration step The scalar lt atol gt specifies the absolute error tolerance parameter They are used for all state variables The estimated local error for a state variable y is controlled so as to be roughly less in magnitude than rtol x y atol Thu
49. an integer e g the line number followed by values of the various parameters in the order indicated in the SetPoints specification If extra fields are at the end of each line they are skipped The first integer field is needed but not used this allows you to directly use Monte Carlo output files for additional SetPoints simulations The variable lt nRuns gt should be less or equal to the number of lines minus one in the set points file If a zero is given all lines of the file are read Finally a comma separated list of the parameters to be read in the SetPointsFilename is given The format of the output file of set points simulations is discussed below see Section 6 3 Analyzing simulation output page 50 Following the SetPoints specification Distrib statements can be given for param eters not already in the list see Distrib specification page 41 These parameters will be sampled accordingly before to performing each simulation The shape parameters of the distribution specifications can reference other parameters including those of the list OptimalDesign specification The OptimalDesign procedure optimizes the number and location of observation times for experimental conditions you specify in order to minimize the variance of a parameter or an output you designate It requires a structural model see Chapter 5 Setting up Structural Models page 17 a statistical model in the form of a likelihood function s
50. andom TruncNormal_v Uniform UniformRandom Appendix B Examples 61 Appendix B Examples You will find here some examples of model description files and simulation input files B 1 linear model Linear Model with a random component y B time N O SD true Setting SD_true to zero gives the deterministic version Outputs Outputs y Model Parameters A 0 B 1 SD_true 0 SD_esti 0 CalcOutputs y A B t NormalRandom 0 SD_true B 2 1cpt model A sample model description file One Compartment Model First order input and output Inputs Inputs Dose Outputs Outputs JC central AUC 1n C central ln AUC SD C computed SD A computed Model Parameters ka 1 ke 0 5 F 21 V 2 Statistical Parameters SDb_ka 0 SDw_ka SDb_ke SDw_ke SDb_V min_F 3 3 3 3 Il OO 3 62 GNU MCSim User s Manual max F 0 SD C central 0 SD AUC 0 CV_C_cen 0 CV AUC 0 CV_C_cen_true 0 CV_AUC_true 0 3 Calculate Outputs CalcOutputs algebraic equation for C_central C_central ka ke exp ke t exp ka t F ka Dose V ka ke exp ka t ka t F Dose V algebraic equation for AUC AUC ka ke 1 exp ke t ke 1 exp ka t ka F ka Dose V ka ke F Dose 1 1 ka t exp ka t V ke C central
51. ate an executable mcsim my If you have renamed the executable file substitute mcsim my by the name of your executable in the following In Unix the command line syntax to run that executable is simply mcsim a input file output file where the brackets indicate optional arguments If no input and output file names are specified the program will prompt you for them You must provide an input file name That file should describe the simulations to perform and specify which outputs should be printed out see Section 6 2 Syntax of simulation files page 34 If you just hit the return key when prompted for the output name the program will use the name you have specified in the input file if any or a default name see OutputFile specification page 36 If just one file name is given on the command line the program will assume that it specifies the input file For the output filename the program will then use the name you have specified in the input file if any or a default name When the program starts up it announces which model description file was used to create it While the input file is read or while simulations are running some informations will be printed on your computer screen They can help you check that the input file is correctly interpreted and that the program runs as it should GNU MCSim can also post error messages which should be self explanatory Where appropriate they show the line number in the input file where
52. ce of the target outputs or parameters achieved if this point is added Forward mode or removed Backward mode Next the chosen time point at this step is given the one minimizing average variance followed by the variance it leads to in expectation and the corresponding standard deviation The last column Utility is zero unless you uncomment the function Compute utility and modify its code in optdesign c to compute a utility of your own Distrib specification The specification of distributions for simple Monte Carlo simulations is quite straighfor ward MCMC simulations require the definition of a full statistical model and the use of distributions is somewhat more complex in that case but the use of Distrib is basically the same In the context of MonteCarlo or SetPoints simulations see MonteCarlo speci fication page 37 and SetPoints specification page 39 one and only one DistribO specification must be included for each model parameter to randomly sample State in put or output variables cannot be randomly sampled by Distrib in this context A 42 GNU MCSim User s Manual simulation specification file can include any number of Distrib commands at the global level Distrib specifies the name of the parameter to sample and its sampling distribution Its syntax is Distrib parameter identifier lt distribution name gt lt shape parameters gt The parameter identifier gives the name of
53. compiling the program this requires re installation Within a Simulation section several additional specifications can be used e StartTime e Print e PrintStep 46 GNU MCSim User s Manual e Data The Data specification is used only when a statistical model is set up and will be covered in the corresponding section of this manual Section 6 2 5 Setting up statistical models page 46 StartTime specification The origin of time for a simulation if it needs to be defined can be set with the StartTime specification StartTime lt initial time gt If this specification is not given a value of zero is used by default The final time is automatically computed to match the largest output time specified in the Print or PrintStep statements Print specification The value of any model variable or parameter can be requested for output with Print specifications Their arguments are a comma separated list of variable names at least one and up to 10 and a comma separated list of increasing times at which to output their values Print lt identifier1 gt lt identifier2 gt lt timel gt lt time2 gt where lt identifierl gt lt identifier2 gt etc correspond to valid input state or output model variables Model parameters cannot be used but you can assign a parameter value to an output variable in your model definition file and use that output here The same output times are used for
54. ctural model see Chapter 5 Setting up Structural Models page 17 a statistical model see Section 6 2 5 Setting up statistical models page 46 38 GNU MCSim User s Manual prior distributions for the model parameters you want to sample and data likelihoods defining the probability of some observed realizations of the modeled process condi tionally to the model see Distrib specification page 41 Setting up a statistical model requires Level sections and Data specifications Assign ing priors and likelihoods is achieved through the Distrib statements or its equivalents Density O and Likelihood OO Please refer to the corresponding sections of this manual if you are not familiar with them The MCMC statement gives general directives for MCMC simulations and has the following syntax MCMC lt OutputFilename gt lt RestartFilename gt lt DataFilename gt lt nRuns gt lt simTypeFlag gt lt printFrequency gt lt itersToPrint gt lt RandomSeed gt The character strings lt OutputFilename gt lt RestartFilename gt and lt DataFilename gt en closed in double quotes should be valid file names for your operating system If a null string is given instead of the output file name the default name MCMC default out will be used If a restart file name is given the first simulations will be read from that file which must be a text file This allows you to continue a simulated Markov ch
55. e Finally if a parameter is defined several times only the first definition is taken into account a warning is issued but beware of it 5 3 3 Model types This section deals with structural models Statistical models that you setup for model calibration and data analysis are defined in the simulation input files through statistical distribution functions They are dealt with later in this manual see Section 6 2 5 Setting up statistical models page 46 Chapter 5 Setting up Structural Models 23 GNU MCSim can easily deal with purely algebraic structural models You do not need to define state variables or a Dynamics section for such models Simply use input and output variables and parameters and specify the model in the CalcOutputs section You can use the time variable t if that is natural for your model If your model does not use t you will still need to specify output times in Print or PrintStep statements to obtain outputs you can use arbitrary times If you do not use t as independent model variable you will also need do define a Simulation section see Simulation sections page 45 for each combination of values for the independent variables of your model This may be clumsy if many values are to be used In that case you may want to use the variable t to represent something else than time Ordinary differential models with algebraic components can be easily setup with GNU MCSim Use state variables and specify a
56. ecification MCMC simulations will give you a sample from the joint posterior distribution of the param eters that you designate as randomly sampled through Distrib specifications You do Chapter 6 Running Simulations 47 not need to specify explicitly that joint posterior distribution in fact in most case this is impossible The posterior distribution is implicitly defined by a statistical model that is simply a set of conditional relationship between the parameters and some data GNU MCSim handles multilevel hierarchical random effects and mixed effects statis tical models in a Bayesian framework These models need to be defined in the simulation specification file rather than in the structural model definition file Yet due to compilation constraints if you need special parameters for your statistical model e g variances you have to declare them in the structural model file even if they are not used by the structural model itself So how do we go about specifying a statistical model with GNU MCSim Take for example the following simple linear regression model yi Nie o 1 pi a B x x 2 where the observed x y pairs are 1 1 2 3 3 3 4 3 and 5 5 Assume that the pa rameters o and f are given N 0 10000 priors and that 1 6 is given a Gamma 10 10 prior We want the posterior distributions of a B and o The first thing to do is to define a structural or link model to compute y as a f
57. ee Simulation sec tions page 45 In terms of structure Simulation sections behave like Level sections in particular with regard to cloning of random variables see below except that they cannot include further levels There must be one and only one top Level and at most 10 nested sub levels in the hierarchy This limit of 10 can be increased up to 255 by changing MAX LEVELS in the header file sim h and re installing GNU MCSim A Level can specify or change the sampling distribution of any model parameter properly defined in the global section of the structural model description file These distribution specifications apply to all sub levels of the Level where they take place For example MCMC samp out 1 1 1 1 1 4 we are in an MCMC context Level this is the top level Distrib A Uniform O 1 Likelihood Data y Normal Prediction y 1 Level sub level 1 Distrib A Normal A 1 Simulation simulation 1 Simulation simulation 2 End sub level 1 End top end file Level can also make simple assignments to any model parameter see Section 6 2 1 General input file syntax page 35 So for example in an simulation the parameter A could be modified with A 2 0 This overrides any previously assigned values for the specified parameter even if ran domly sampled and applies to the sub levels of the Level where it take place An important concept to grasp here is that of
58. ee Section 6 2 5 Setting up statistical models page 46 and a random set of parameter vectors sampled from a prior distribution using Monte Carlo or MCMC simulations for example and details see Bois et al 1999 see Bibliographic References page 57 The statistical model used should be quite simple and cannot not use Level sections and hence cannot be hierarchical The OptimalDesign command has the following syntax OptimalDesign lt OutputFilename gt lt ParameterSampleFilename gt lt nSamples gt lt RandomSeed gt Style lt parameter identifier gt lt parameter identifier gt The character strings lt OutputFilename gt and lt ParameterSampleFilename gt enclosed in double quotes should be valid file names for your operating system If a null string is given instead of the output file name the default name simopt default out will be used A parameter sample file name must be given that file must be a text file The first line of the file which typically contains column headers is skipped The number of lines in the file must be less than or equal to lt nSamples gt The first column of the file should be integers typically row numbers and the following columns tab or space separated should be values of the various parameters in the order indicated in the list at the end of the OptimalDesign specification If extra fields are at the end of each line they are skipped The first integer fie
59. erbatim copies of this license document but changing it is not allowed 0 PREAMBLE The purpose of this License is to make a manual textbook or other functional and useful document free in the sense of freedom to assure everyone the effective freedom to copy and redistribute it with or without modifying it either commercially or non commercially Secondarily this License preserves for the author and publisher a way to get credit for their work while not being considered responsible for modifications made by others This License is a kind of copyleft which means that derivative works of the document must themselves be free in the same sense It complements the GNU General Public License which is a copyleft license designed for free software We have designed this License in order to use it for manuals for free software because free software needs free documentation a free program should come with manuals providing the same freedoms that the software does But this License is not limited to software manuals it can be used for any textual work regardless of subject matter or whether it is published as a printed book We recommend this License principally for works whose purpose is instruction or reference 1 APPLICABILITY AND DEFINITIONS This License applies to any manual or other work in any medium that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License Such a no
60. have been created to the same end the Matlab family of graphical interactive programs being some of the more general and easy to use Still many available tools are not optimal for performing computer intensive and sophisticated Monte Carlo analyses GNU MCSim was created specifically to this end to perform Monte Carlo analyses in an optimized and easy to maintain environment The software consists in two pieces a model generator and a simulation engine The model generator mod was created to facilitate structural model definition and maintenance while keeping execution time short You code your model using a simplified syntax and mod translates it in C The simulation engine is a set of routines are linked to your model to produce executable code After linking you will be able to run simulations of your structural model under a variety of conditions specify an associated statistical model and perform Monte Carlo simulations 2 1 General procedure Model building and simulation proceeds in four stages 1 You create with any text editor e g emacs a model description file The reference section on mod later in this manual gives you the syntax to use see Chapter 5 Setting up Structural Models page 17 This syntax allows you to describe the model variables parameters equations inputs and outputs in a C like fashion without having you to actually know how to write a C program 2 You instruct the model generator mod to
61. have one corresponding differential equation in the Dynamics section If a differential equation is missing mod issues an error message such as Chapter 5 Setting up Structural Models 27 Error State variable foo has no dynamics and no model c file or executable program will be created The derivative of a state variable is defined using the dt operator as shown here dt state variable constant value or expression The right hand side can be any valid C expression including standard math library calls and the special functions mentioned above see Section 5 3 4 Special functions page 23 Note that no syntactic check is performed on the library function calls Their correctness is your responsibility The dt O operator can also be used in the right hand side of equations in the dynamics section to refer to the value of a derivative at that point in the calculations For example dt Qm in Qmetabolized dt Qm out The integration variable e g time can be accessed if referred to as t as in dt Qm in Qmetabolized t Output variables can also be made a function of t in the Dynamics section Note that while state variables input variables and model parameters can be used on the right hand side of equations they cannot be assigned values in the Dynamics section If you need a parameter to change with time you can declare it as an output variable in the global section Assignments to states inputs or
62. ill specify in the second set of Simulation definitions Data will be simulated for each of the required output There must be one Data statement per output specified the data values are arbitrary An error model must be specified for those data using a Likelihood statement see Distrib specification page 41 The second set of Simulation specifies optimization target parameters or outputs The algorithm will select time points in the first section s Simulation specifications that mini mize the estimation variance of those parameters or outputs When a parameter is targeted no inputs are needed If you optimize for an output variable variance 1 e for the variance of a model prediction the experimental conditions can be very different from those of the experiment whose conditions you optimize The link is afforded solely by the parameters in the first set you are trying to determine the conditions that will optimally identify the parameter values conditioning the predictions or trivially the parameters of the second set The format of the output file of design optimization simulations is quite specific The first column is an iteration number At each iteration one observation point is added Forward mode or removed Backward mode Each step is therefore conditioned by the selection of an observation time point made by the previous step The following columns give for each observation time point you specify the average varian
63. in effect for every sub level or every Simulation section included in the current Level The simulations to perform and the corresponding data values are specified by a Simulation section Only one Simulation section is needed here but several could be specified In this section the value of z is provided The different values of x time in our formulation of the model can be specified via PrintStep see PrintStep specification page 46 since they are equally spaced More generally Print can also be used see Print specification page 46 The data values are given in a Data statement see below The following paragraphs deal with Level sections and Data specifications Level sections Markov chain Monte Carlo simulations require the definition of a statistical model struc tured with levels Think for example of the definition of a prior distribution as a top level in a hierarchy with the data likelihood being at the lowest level The hierarchy levels are defined in GNU MCSim with the help of Level sections At least one Level section must be defined in the simulation input file you cannot use Level in a structural model definition Chapter 6 Running Simulations 49 file Level section starts with the corresponding keyword and is enclosed in curly braces It can include any number of sub levels or Simulations sections Simulations where the data are specified form the lowest level of the hierarchy s
64. ion files and this manual if it was generated is created as usr share doc mcsim If you do not have the necessary access rights and want to install GNU MCSim in a directory such as home me type configure prefix home me This will copy or move mod makemcsim and xmcsim in a bin directory in the home me directory creating it if necessary The library libmcsim so will be moved to the home me 1ib directory etc Chapter 3 Installation 13 3 3 2 Other operating systems Under other operating systems Windows etc or if everything else fails you should be able to both uncompress and untar the archive with widely distributed archiving tools Refer to the documentation of your C compiler to create an executable mod file from the source code files getopt c lex c lexerr c lexfn c mod c modd c modi c modiSBML c modiSBML2 c modo c strutil c provided in the mod directory If you want to process SBML models it is best to install the HbSBML library first You would then compile mod with the HAVE LIBSBML flag defined option DHAVE LIBSBML and link with the library using the 1sbml directive Place then the executable mod on your command path The sim directory contains all the source files sim c getopt c lex c lexerr c lexfn c list c lsodesl c lsodes2 c matutil c matutilo c mh c modelu c optdsign c random c simi c siminit c simmonte c simo c strutil c yourcode c to create a dynamic library or a set of objec
65. ipt or PDF designed for human modification Examples of transparent image formats include PNG XCF and JPG Opaque formats include proprietary formats that can be read and edited only by proprietary word processors SGML or XML for which the DTD and or processing tools are not generally available and the machine generated HTML PostScript or PDF produced by some word processors for output purposes only The Title Page means for a printed book the title page itself plus such following pages as are needed to hold legibly the material this License requires to appear in the title page For works in formats which do not have any title page as such Title Page means the text near the most prominent appearance of the work s title preceding the beginning of the body of the text A section Entitled XYZ means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in Chapter 1 Software and Documentation Licenses 3 another language Here XYZ stands for a specific section name mentioned below such as Acknowledgements Dedications Endorsements or History To Preserve the Title of such a section when you modify the Document means that it remains a section Entitled XYZ according to this definition The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document These Warranty Disclaime
66. is manual 5 2 Using makemcsim to fully process model files makemcsim is a Unix sh shell script that further facilitates preprocessing and compilation You run makemcsim by entering it at the command prompt 18 GNU MCSim User s Manual makemcsim model file where the brackets indicate that the model filename is optional If a model filename is not specified the first file having extension model by alphabetical order is used Makem csim calls mod if the model file has changed since last compilation compiles the model c generated links it to the shared 1ibmcsim so library to create an executable mcsim root model name The extension root model name corresponds to your model filename with out its last extension if it has one i e typically without the model extension The model c file is deleted afterward if you want to inspect it for example if you got error messages from mod run mod on your model definition file Two variants of makemcsim are also available makemcsims which creates a standalone version no dynamic libraries needed and makemcsimd which creates a standalone version with debugging symbols included so that you can use gdb for example to check what the code does 5 3 Syntax of the model description file The model description file is a text ASCII file that consists of several sections including global declarations dynamics specifications with derivative calculations model initializa tion sc
67. istributions can symbolically reference other model parameters even if distributions for these have already been defined For example Distrib A Normal O 1 Distrib B Normal A 2 In the context of MCMC sampling GNU MCSim provides extensions of the above Distrib specification syntax First when Distrib is used to specify the distribution of a model parameter that parameter can also appear as a shape parameter if a distribution has already been specified for the parameter at an upper Level of the file For example Level upper level Distrib A Normal 0 1 Distrib B InvGamma 2 2 Level sub level Distrib A Normal v A B end sub level end upper level In that case the parameter A used for shape specification as the mean of a Normal distribution in the sub level refers to the parent A parameter for which a standard 44 GNU MCSim User s Manual Normal distribution is defined at the upper Level The sampled values of the parent parameters and B will be used as mean and variance for their child parameter A when it will be its turn to be randomly sampled This forms the basis of the specification of multilevel hierarchical models see Section 6 2 5 Setting up statistical models page 46 Next in MCMC simulations you usually assign a probability distribution or a likeli hood to the data you are trying to analyze Typically your model s state and or output variables will attempt to p
68. ke V central The chemical reactions defined in SBML to take Chapter 5 Setting up Structural Models 31 place inside the central or peripheral compartments will be translated into specific terms added to the dt _central and dt periph equations Warning the automatic creation of a model by merging SBML files with a template may shuffle the order of the differential equation declarations Therefore you should not use an already defined dt term in a subsequent differential equation in the template model Chapter 6 Running Simulations 33 6 Running Simulations After having your model processed by mod or makemcsim and obtained an executable mcsim_ file you are ready to run simulations For this you need to write simulation files This chapter explains how to write such files with the proper syntax and how to run the executable program You may want to first give a look at the examples given in the mcsim samples di rectory An sample file perc 1sodes in which works with the perchloroethylene model perc model is also given in an Appendix to this manual see Section B 4 perc lsodes in page 68 6 1 Using the compiled program GNU MCSim provides several types of simulations for the models you create Simulations are specified in a text file of format similar to that of the model description file Assume that your model a model has been preprocessed and compiled by makemcsim see Section 5 2 Using makemcsim page 17 to gener
69. l section of the model definition file and combined in the Dynamics see Section 5 3 8 Dynamics section page 26 and CalcOutputs see Section 5 3 9 Output calculations page 27 sections 5 3 6 In line functions Inline functions can be placed in the various sections of a model file to introduce stan dard C code or whatever in your models Text placed between the parentheses of an Inline function will be passed as is to the C compiler That text can span several lines but its size should not exceed MAX EQN defined in lex h In case it does you can in crease MAX EQN and recompile mod or you can split you text between any number of Inline in a row It is your responsibility to make sure that the code passed can be compiled without errors Example Inline printf hello n 5 3 7 Model initialization The model initialization section begins with the keyword Initialize the keyword Scale is obsolete but is still understood and is enclosed in curly braces The equations given in this section will define a function subroutine that will be called by GNU MCSim after the assignments specified in each Experiment are done see Simulation sections page 45 They are the last initializations performed The model file in mcsim samples perc gives an example of the use of Initialize see Section B 3 perc model page 63 in Appendix All model variables and parameters except inputs can be changed in this section Mod ifications
70. ld is needed but not used this allows you to directly use Monte Carlo output files for OptimalDesign simulations The integer lt nSamples gt indicates the number of lines to read from the lt ParameterSam pleFilename gt file The seed lt RandomSeed gt of the pseudo random number generator can be any positive real number Seeds between 1 0 and 2147483646 0 are used as is others Chapter 6 Running Simulations 41 are rescaled silently within those bounds The directive Style should be either the keyword Forward or the keyword Backward Forward optimization will start from no new data and will add sequentially optimal observation times Backward optimization starts with the full set of observation times you propose and delete the least informative ones sequentially We recommand that you try both options Finally a comma separated list of the parameters to be read in the ParameterSamplFilename should be given The input file must then contain two sets of Simulation definitions You should look at the sample optimal design files provided in mcsim samples The first set specifies all experimental conditions and the set of observation times to optimize for one or several output variables given in Print statements The output times you specify for each output variable define an array of observation time values that the optimization algorithm will rank by order of the estimated variance reduction they permit for variables or parameters you w
71. le at http ftp gnu org gnu mcsim http www gnu org software mcsim and mirror sites of the GNU project Three mailing lists are available for GNU MCSim users General info on GNU MCSim is broadcasted through http lists gnu org archive html info mcsim You can subscribe to the info list by going to http lists gnu org mailman listinfo info mcsim You can request help from us and from other GNU MCSim users by sending email to help mcsim gnu org see http lists gnu org mailman listinfo help mcsim for subscribing Help archives are found at http news gmane org gmane comp gnu mcsim http lists gnu org archive html help mcsim You can report bugs to us by sending email to 12 GNU MCSim User s Manual bug mcsim gnu org http lists gnu org mailman listinfo bug mcsim for subscribing Bugs archives are located at http news gmane org gmane comp gnu mcsim bugs http lists gnu org archive html bug mcsim 3 3 Machine specific installation 3 3 1 Unix and GNU Linux operating systems To install on a Unix or GNU Linux machine download in binary mode the distributed archive file to your machine Place it in a directory where there is no existing mcsim subdirectory that could be erased make sure you check that Decompress the archive with GNU gunzip gunzip lt archive name gt tar gz Untar the decompressed archive with tar tar xf lt archive name gt tar do man tar for further help Move to the
72. m masses and densities etc e system s dynamics differential or algebraic equations defining the model per se e equations to compute the output variables 16 GNU MCSim User s Manual This model definition file as simple syntax easy to master It needs to be turned into a C program file before compilation and linking to the other routines integration file management etc of GNU MCSim You will use mod for that First quit the editor and return to the operating system To start mod under Unix just type mod perc model After a few seconds with no error messages if the model definition is syntactically correct mod announces that the model c file has been created It should operate similarly under other operating systems The next step is to compile and link together the various C files that will constitute the simulation program for your particular model Note that each time you want to change an equation in your model you will have to change the model definition file and repeat the steps above However changing just parameter values or state initial values does not require recompilation since that can be done through simulation specification files e Under Unix the simplest is to use the makemcsim script Just type makemcsim and compilation will be done automatically see Section 5 2 Using makemcsim page 17 An executable mcsim perc is created You can rename it if you wish e Under other operating systems you should use
73. ml 30 GNU MCSim User s Manual End The template structure is similar to that of other GNU MCSim models with two excep tions First the variables and parameters which are supposed to apply to several chemical species defined in SBML are preceeded with an underscore _ Second the compartments allowed in SBML and for which the template is defined are declared using the keyword Compartment followed by an equal sign and a list of the compartment names enclosed in curly braces Here is an example of template file States central _periph Inputs Dose rate Outputs Q total Compartments central peripheral Species dependent parameters _PC 2 _K_urine Species independent parameters V central V periph Initialize K urine K urine 2 Dynamics _Q_rate_c_p 5 central periph PC Central compartment quantity _pk_central Dose rate rate c p K urine central V central dt central pk central Peripheral compartment quantity _pk_periph H rate c p V periph dt periph pk periph CalcOutputs _Q_total central V central _periph V periph End With that template each species say S1 defined in SBML to be outside of the central or peripheral compartments will be cloned to form the state variables SI central and S1_peripheral Those will have associated differential equations using specific parameters S1 PC or unspecific ones li
74. mulation of an Experiment see Simulation sections page 45 All the other variables are parameters Model parameters you want to be able to change in simulation input files should be declared in the global section For example Wind speed m s Local wind speed Parameters are by default assigned a value of zero To assign a different nominal values use the assignment rules given above For example BodyWt 65 0 sqrt 15 0 Weight of the subject in kg All parameters and variables are computed in double precision floating point format Initial values should not be such as to cause computation errors in the model equations this is likely to lead to crashing of the program so for example do not assign a default value of zero to a parameter appearing alone in a denominator Note that the order of global declarations matters within the global section itself 7 e parameters and variables should be defined and initialized before being used in assignments of others but not with respect to other blocks parameter defined at the end of the description file can be used in the Dynamics section which may appear at the beginning of the file Still such an inverse order should be avoided For this reason the format above where global declarations come first is strongly suggested to avoid confusing results Note again that the name IFN in capital letters is reserved by the program and should not be used as parameter or variable nam
75. n Distrib 43 Print specification 46 PrintStep specification 46 Q Qualifier Data 43 Qualifier Prediction 43 R Random number beta 23 Random number binomial 23 Random number binomial beta 23 Random number Cauchy 23 Random number Chi squared 23 Random number exponential 23 Random number gamma 23 Random number general gamma 24 Random number inverse gamma 24 Random number lognormal 24 Random number loguniform 24 Random number normal 24 Random number piecewise 24 Random number Poisson 24 Random number Student 24 Random number truncated inverse gamma 24 Random number truncated lognormal 24 Random number truncated normal 24 Random number uniform 24 Random seed reading its value 23 Random seed setting its value 24 Reserved keywords 59 Running simulations 33 71 S SBML models 22 0523 case epe 28 Scale scaling section 26 Hemi COlON sen ENEE ENN SNE EN
76. n example of a model definition file It is also printed at in Appendix the end of this manual see Section B 3 perc model page 63 You can use it as a template for your own model but you should leave it unchanged for now In that file the pound signs indicate the start of comments Notice that the file defines e state variables for the model for which differentials are defined for example States Q fat Quantity of PERC in the fat mg U wp xs in the well perfused compartment mg H pp nes in the poorly perfused compartment mg Q liv Pear in the liver mg Q_exh ate exhaled mg Q_met Quantity of metabolite formed mg e output variables obtainable at any time as analytical functions of the states inputs and parameters for example Outputs C_liv mg l in the liver C_alv X in the alveolar air C exh in the exhaled air C ven in the venous blood Pct metabolized of the dose metabolized C ech ug ug l in the exhaled air e input variables independent of the others variables and eventually varying with time for example Inputs C inh Concentration inhaled ppm Q ing Quantity ingested mg e model parameters independent of time such as LeanBodyWt 55 lean body weight kg e model initialization and parameters scaling the parameters used in the dynamic equa tions can be made functions of other parameters for example volumes can be computed fro
77. nster G Boersma and H Steenweg Int Arch Occup Environ Health v42 1989 pp303 309 The paper documents measurements of levels of TCE in blood and exhaled air for a group of 6 subjects exposed to different concentrations of PERC in air Inhalation is specified as a dose of magnitude InhMag for the given Exposure time dk dk dk dt dt dt dt dt dt dt dt H dt OF Inhalation is given in ppm Simulation 1 InhMag 72 ppm Period 1e10 Only one dose Exposure 240 4 hour exposure measurements before end of exposure and at 5 30 2hr 18 42 67 91 139 163 Print C exh ug 239 9 245 270 360 1320 2760 4260 5700 8580 10020 Print C ven 239 9 360 1320 2760 4260 5700 8580 10020 END Concept Index Concept Index 3 WEE 19 EE 18 hyphen sign 19 See M Ms et Ee 19 POPS HTN EET 18 FR SOPOT AGO e geen de ton mie mas 19 K OPSLALOL EE 19 gt OPePator e ma Lane in MAG A 19 ES A EEN KE E EEE E E EE 19 Op rator EE 19 EE E Es vb el Men E en p XA Eus 19 DS operto eec he nE hdd PESE REA 19 EE 19 II square brackets notation 19 7 underscore in templates 30 underscore vector notation 21 A Algebraic models 22 Analyzing simulation output 50 EENS RM 19 Assignment ed SNE de es phew nie de dede 19 B Beta distribution
78. o use the Modified Version under the terms of this License in the form shown in the Addendum below Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document s license notice Include an unaltered copy of this License Preserve the section Entitled History Preserve its Title and add to it an item stating at least the title year new authors and publisher of the Modified Version as given on the Title Page If there is no section Entitled History in the Docu ment create one stating the title year authors and publisher of the Document as given on its Title Page then add an item describing the Modified Version as stated in the previous sentence Preserve the network location if any given in the Document for public access to a Transparent copy of the Document and likewise the network locations given in the Document for previous versions it was based on These may be placed in the History section You may omit a network location for a work that was published at least four years before the Document itself or if the original publisher of the version it refers to gives permission For any section Entitled Acknowledgements or Dedications Preserve the Title of the section and preserve in the section all the substance and tone of each of the contributor acknowledgements and or dedications given therein Chapter 1 Software and Documentation Licenses 5 L
79. of specified parameter sets listed in a separate ASCII file see SetPoints specification page 39 You can create these parameter sets yourself on a regular grid for example or use the output of a previous Monte Carlo or MCMC simulation An OptimalDesign procedure optimizes the number and location of observation times for experimental conditions in order to minimize the variance of a parameter or an output you specify given a structural model a statistical model and prior distributions for their parameters see OptimalDesign specification page 40 2 3 Major changes introduced with version 5 4 0 GNU MCSim is now distributed under version 3 of the GNU General Public License The installation scripts have been rewritten using GNU autoconf automake and libtool This should make GNU MCSim easier to install and more portable Systems Biology Markup Language SBML models are processed by libSBML if it is installed Tempered MCMC for hard multimodal posterior densities and stochastic optimiza tions are offered as options of the MCMCx O specification 2 4 Major changes introduced with version 5 5 0 The installation scripts have been regenerated using GNU autoconf version 2 69 which fixes a potential security problem in the installation That should be transparent to the user The mod utility can now generate C model files suitable for use with the R package deSolve Use mod R for that Chapter 3 Installation 11 3
80. of the same parameter placed at the second instance of the second level of the hierarchy is labeled name 2 1 etc The tab delimited file can easily be imported into your favorite spreadsheet graphic or statistical package for further analysis Chapter 6 Running Simulations 51 6 4 Error handling If integration fails for a imulation in DefaultSim simulations no output is generated for that simulation and the user is warned by an error message on the screen In MonteCarlo or SetPoints simulations the corresponding simulation line is not printed but the iteration number is incremented Finally in MCMC simulations the parameter for which the data likelihood was computed is simply not updated which implicitly forbids the uncomputable region of the parameter space In all cases an error message is given on the screen or wherever the screen output has been redirected Chapter 7 Common Pitfalls 53 7 Common Pitfalls The following mistakes are particularly easy to make and sometimes hard to notice or understand at first e Forgetting about type related arithmetics in C 1000 882 gives 1 since it is inter preted as an integer division by the compiler To get a floating point usual division use 1000 882 e Forgetting a semi colon at the end of statements the error is usually detected at the following line s where in fact nothing may be wrong Chapter 8 XMCSim 55 8 XMCSim XMCSim is a menu driven in
81. oned once in order to create another normal variate with the same distribution Each one of those two will be moved to a lower Simulation where they will be conditioned by the data of that simulation only A total of three variables of type A will be sampled and will be printed in the output file coded so that the position in the hierarchy is apparent the parent A 1 a priori uniformly distributed and two dependents A 1 1 and A 1 2 a priori normally distributed around A 1 Data specification Experimental observations of model variables inputs outputs or parameters can be spec ified with the Data command Markov chain Monte Carlo sampling requires that you specify Data O statements see MCMC specification page 37 see Section 6 2 5 Setting up statistical models page 46 The data are then used internally to evaluate the likelihood function for the model The arguments are the name of the variable for which observations exist and a comma separated list of data values Data variable identifier lt valuel gt lt value2 gt This specification can only be used with a matching Print or PrintStep for the same variable see Print specification page 46 see PrintStep specification page 46 You must make sure that there are as many data values in the Data specification as output time requested in the corresponding Print or PrintStep A data value of 1 is treated as missing data and igno
82. ons see Section 5 3 4 Special functions page 23 Here also input functions see Section 5 3 5 Input functions page 25 can only be used on the right hand side of assignments to input variables Vector indices on the right hand side can take the special form of bracketed expressions Bracketed expressions can be composed of integers the 4 basic arithmetic operators P parentheses and the index letter i The running index i points in turn to each component in the range specified on the left hand side imagine that the range given on the left hand side corresponds to a for loop with index i running from the lower bound to the upper bound This is best understood by looking at some code In the previous example the assignments to x 0 and x 1 obviously deserve vectorization This is achieved by the following statements CalcOutputs 1 x 0 1 beta i t Here the index i refers to the values 0 and 1 Here is another example Outputs x 1 10 Chapter 5 Setting up Structural Models 21 CalcOutputs x 1 0 x 2 10 x i 1 1 This is equivalent to Outputs x 1 10 CalcOutputs x 1 0 x 2 x 1 1 x 10 x 9 1 and will assign value 1 to x 2 2 to x 3 etc On the right hand side more com plicated bracketed expressions like 2 i 1 i 3 can be used Another working example of vector use is given in the mcsim samples
83. or choice of default parameter values That does not decrease the value of good comments however 5 4 Reading SBML models and applying a template To read models written in SBML you simply need to create a text file of the same for mat as an MCsim model definition file comments starting with file ending with End e c In that file you specify a list of one or more SBML model files with the keyword SBMLModels followed by an equal sign and a list of SBML model file names of maximum size MAX FILENAMESIZE 80 characters as defined in mod h enclosed in curly braces as shown here SBML List in Use it as mod SBML List in SBMLModels useID default C central xml C periph xml End The first two tokens useID and default at the very beginning of the list are optional but if the appear they must both appear The first indicates that species are recognized by IDs at the moment this the only possibility hardly an option indeed but in the future we would like to be able also to use Names The second one gives the name of the default external compartment in your SBML files Here the default is named default which works for CellDesigner but JDesigner for example uses compartment The list of files Chapter 5 Setting up Structural Models 29 comes after with the filenames being enclosed with double quotes There is no restriction about their extension xml is just an example They just have to
84. ould be between 0 and 4 included e It should be set at zero to start a chain of MCMC simulations In that case parameters are updated by Metropolis steps one at a time e If lt simTypeFlag gt 1 a restart file must also be specified The output file will contain codes for the level sequence simulation numbers printing times data values and the corresponding model predictions computed using the last parameter vector of the restart file This is useful to quickly check the model fit to the data e If lt simTypeFlag gt is equal to 2 a restart file must also be specified and that entire file is used to compute the parameters covariance matrix All parameters are then updated Chapter 6 Running Simulations 39 at once using a multivariate normal kernel as proposal distribution of the Metropolis steps This may result in large improvement in speed However we recommend that this option be used only when convergence is approximately obtained therefore you should run MCMC simulations with lt simTypeFlag gt set to 0 first up to approximate convergence and then restart the chain with the flag at 2 e With lt simTypeFlag gt equal to 3 tempered component by component MCMC is per formed MCMC Geyer and Thompson 1995 see Bibliographic References page 57 In that case a grid of inverse temperatures is used along an annealing scheme By default 5 inverse temperatures are used 0 4 0 512 0 64 0 8 1 but you can define
85. owed to be designated as Invariant The Document may contain zero Invariant Sections If the Document does not identify any Invariant Sections then there are none The Cover Texts are certain short passages of text that are listed as Front Cover Texts or Back Cover Texts in the notice that says that the Document is released under this License A Front Cover Text may be at most 5 words and a Back Cover Text may be at most 25 words A ransparent copy of the Document means a machine readable copy represented in format whose specification is available to the general public that is suitable for revising the document straightforwardly with generic text editors or for images com posed of pixels generic paint programs or for drawings some widely available drawing editor and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters copy made in an otherwise Transparent file format whose markup or absence of markup has been arranged to thwart or discourage subsequent modification by readers is not Transparent An image format is not Transparent if used for any substantial amount of text A copy that is not Transparent is called Opaque Examples of suitable formats for Transparent copies include plain ASCII without markup Texinfo input format LaTEX input format SGML or XML using a publicly available DTD and standard conforming simple HTML PostScr
86. parameter cloning Cloning automat ically creates using templates as many new parameters as you need in your multilevel model One of the characteristic feature of multilevel models is the same parameters ap pear at several levels For example in a random effect model a parameter e g size will be assumed to be randomly distributed in a population of individuals If you have 100 indi viduals in your database your model will have to deal with 100 individual size parameters and an average size To spare you the tedium of defining the same distribution for many parameters GNU MCSim creates an appropriate number of parameters for your model on the basis of its level structure Assume that you have specified a distribution for a pa rameter A at a given level that we label L1 for clarity GNU MCSim will automatically create new parameters clones with the same distribution as A to match the number of immediate sub levels in L1 For example if there are three sub levels included in L1 GNU MCSim creates two clones to form a total of three instances of A the original and its two clones This convention saves a lot writing and effort in the long run In the sample of code given above the parameter A defined at the top level will be simply moved to sub level 1 cloning is not necessary since there is only on sub level directly 50 GNU MCSim User s Manual included in the top level Within sub level 1 the normally distributed A will be cl
87. ple parameter values and run the model for each parameter set so generated The statistical distribution of the model outputs can be studied for uncertainty analysis sensitivity analysis etc Such simulations require the use of two specifications MonteCarlo and Distrib which must appear in the global section of the file before the Simulation sections They are ignored if they appear inside a Simulation section The MonteCarlo specification gives general information required for the runs the output file name the number of runs to perform and a starting seed for the random number generator Its syntax is MonteCarlo lt OutputFilename gt lt nRuns gt lt RandomSeed gt The character string lt OutputFilename gt enclosed in double quotes should be a valid filename for your operating system If a null string is given the default name simmc out will be used The number of runs lt nRuns gt should be an integer and is only limited by either your storage space for the output file or the largest long integer available on your machine The seed lt RandomSeed gt of the pseudo random number generator can be any positive real number Seeds between 1 0 and 2147483646 0 are used as is the others are rescaled within those bounds and a warning is issued Here is an example of use MonteCarlo percsimmc out 50000 9386 630 The parameters sampling distributions are specified by a list of Distrib specifica tions as expl
88. r exact times of occurrence The first argument lt n gt is the number of inputs and input times Next come a list of magnitudes and a list of times Each list is comma separated Currently this function can only be used in the simulation description file and not in the model description file which simply implies that you cannot use it as a default Syntax Spikes lt n gt lt list of magnitudes gt lt list of times gt The arguments of input functions can either be constants or variables For example if Mag and RateConst are defined model parameters then the input variable Q_in can be defined as Q_in PerExp Mag 60 0 RateConst In this way the parameters of input functions can for example be assigned statistical distributions in Monte Carlo simulations see Distrib specification page 41 Variable de pendencies are resolved before each simulation specified by an Experiment see Simulation sections page 45 For each of the periodic functions a single exposure beginning at time initial time can be specified by giving an effectively infinite period e g 101 The first period starts at the initial time of the simulation Magnitudes change exactly at the times given Input variables assigned input functions can be combined to give a lot of flexibility e g an input variable can be declared as the sum of others Separate inputs can also be 26 GNU MCSim User s Manual declared in the globa
89. rate A e StudentT requires three parameters its number of degrees of freedom an integer its mean and its standard deviation e TruncInvGamma truncated inverse gamma distribution needs four strictly positive real parameters the shape the scale the minimum and the maximum e TruncLogNormal truncated lognormal distribution uses four real numbers the geo metric mean and geometric standard deviation strictly superior to 1 the minimum and the maximum in natural space For example Distrib Var TruncLogNormal 1 2 718 0 01 10 samples Var such that In Var is a standardized normal variate of mean In 1 and standard deviation In 2 718 while Var is truncated to fall between 0 01 to 10 e TruncLogNormal v is like the truncated lognormal except that it takes the variance in log space instead of the standard deviation as second parameter You can use it to specify a hierarchical model with a conjugate prior on the variance see Section 6 2 5 Setting up statistical models page 46 e TruncNormal truncated normal distribution takes four real parameters the mean the standard deviation strictly positive the minimum and the maximum e TruncNormal v is like the truncated normal distribution with the variance instead of the standard deviation as second parameter e Uniform with two shape parameters the minimum and the maximum of the sampling range real numbers The shape parameters of the above d
90. red in likelihood calculations The convention 1 can be changed by changing INPUT MISSING VALUE in the header file mc hand recompiling 6 3 Analyzing simulation output The output from Monte Carlo or SetPoints simulations is a tab delimited text file with one row for each run i e parameter set and one column for each parameter and output in the order specified Thus each line of the output file is in the following order lt of run parameters outputs for Exp 1 gt outputs for Exp2 gt The parameters are printed in the order they were sampled or set The first line gives the column headers A variable called name requested for output in an simulation i at a time j is labeled name ij The output of Markov chain Monte Carlo simulations is also a text file with one row for each run It displays column of iteration labels and one column for each parameter sampled The last three columns contain respectively the sum of the logarithms of each pa rameter s density given its parents values LnPrior the logarithm of the data likelihood LnData and the sum of the previous two values LnPosterior The first line gives the column headers On this line parameters names are tagged with a code identifying their position in the hierarchy defined by the Level sections For example the second instance of a parameter called name placed at the fist level of the hierarchy is labeled name 2 the first instance
91. redict some aspect of the observed data distributions mean variance etc GNU MCSim gives you the possibility to specify a distribution for your data using model parameters input state or output model variables or even other data to define the distribution shape This is achieved through the use of the Data and Prediction qualifiers Data can be used at the first position of a Distrib statement or as a distribution shape parameter It uses the following syntax Data lt identifier gt where lt identifier gt corresponds to a valid input state or output model variable for which data are available Model parameters cannot be used but you can assign a simple param eter value to an output variable in your model definition file and use that output here The actual data values need to be given later in the simulation input file through Data specifications which in addition to a variable identifier give a list of numerical data values see Data specification page 50 or in a separate datafile see MCMC specification page 37 Working hand in hand with Data and using the same syntax the Prediction qualifier can be used to designate actual model inputs states and outputs for any shape parameter of a specified distribution therefore Prediction must appear after the distri bution name The actual predicted values matching exactly the corresponding data need to be given later in the simulation input file th
92. rough Print or PrintStep specifications see Print specification page 46 and PrintStep specification page 46 Here are some example of use of Data and Prediction in the extended syntax of a Distrib specification Distrib Data y Normal Prediction y 0 01 Data y 0 1 2 5 3 9 2 Print y 10 20 40 60 100 Distrib Data y Normal Prediction y Prediction sigma Data y 1 01 1 20 0 97 0 80 1 02 PrintStep y 10 50 10 PrintStep sigma 10 50 10 Distrib Data R Binomial Prediction P Data N Data R 0 2 5 5 8 9 10 10 Data N 10 10 9 10 9 9 11 10 Print P 10 20 30 40 50 60 70 80 Chapter 6 Running Simulations 45 these could not appear all as such in an input file they would need to be embedded in Level and Simulation sections Last for more readable input files two keywords Density and Likelihood can be used instead of Distrib They are equivalent to Distrib and have the same syntax SimType specification This specification is now obsolete and should not be used It is left for compatibility with old input files It specifies the type of analysis to perform Syntax SimType keyword The following keywords can be used DefaultSim the list of specified simulations is simulated MonteCarlo MCMC previously Gibbs SetPoints If MonteCarlo MCMC or SetPoints analyses are requested additional specifications are needed
93. rs are considered to be included by reference in this License but only as regards disclaiming warranties any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License 2 VERBATIM COPYING You may copy and distribute the Document in any medium either commercially or noncommercially provided that this License the copyright notices and the license notice saying this License applies to the Document are reproduced in all copies and that you add no other conditions whatsoever to those of this License You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute However you may accept compensation in exchange for copies If you distribute a large enough number of copies you must also follow the conditions in section 3 You may also lend copies under the same conditions stated above and you may publicly display copies 3 COPYING IN QUANTITY If you publish printed copies or copies in media that commonly have printed covers of the Document numbering more than 100 and the Document s license notice requires Cover Texts you must enclose the copies in covers that carry clearly and legibly all these Cover Texts Front Cover Texts on the front cover and Back Cover Texts on the back cover Both covers must also clearly and legibly identify you as the publisher of these copies The front cover must present the full title
94. s be a conditional expression The comparison operators allowed are the equality operator and non equality operators lt gt lt gt lt and gt e Vectors Warning for now the square bracket notation can be only used in the model definition file It is not recognized in simulation specification files for those the underscore _ unrolling syntax can be used to address vector components This limits the usefulness of this feature Vectors declaration To declare a variable as a vector use the one of the two following syntaxes when you first define it lt variable name gt integer lt variable name gt lt integer gt lt integer gt li The variable name is immediately followed by an opening square bracket The array index bounds which define the valid indices can be given as long positive or null integers separated by an hyphen spaces are allowed In this case the second integer must be higher the first They are followed by a closing bracket The hyphen and second integer are optional If only one bound integer is given only the component with corresponding index is declared Both syntaxes can be mixed For example States y 0 9 alpha 0 2 1 beta 0 1 beta 1 2 20 GNU MCSim User s Manual beta 2 4 The previous lines define a state variable y as a vector of length 10 with valid indices ranging between 0 and 9 included
95. s the local error test passes if for each state variable either the absolute error is less than lt atol gt or the relative error is less than lt rtol gt Set rtol to zero for pure absolute error control and set atol to zero for pure relative error control Caution actual global errors may exceed these local tolerances so choose them conservatively The method flag should be 0 zero for non stiff differential systems and 1 for stiff systems You should try both and select the fastest for equal accuracy of output unless insight from your system leads you to choose one of them a priori In our experience a good starting point for atol and lt rtol gt is about 10 9 The syntax for Euler is Integrate Euler lt time step gt 0 0 where lt time step gt is a scalar specifying the constant time increment for each integration step The next two scalars are reserved for future use and should be set to zero Note if the Integrate specification is not used the default integration method is Lsodes with parameters 107 1077 and 1 We recommend using Lsodes since is it highly accurate and efficient Euler can be used for special applications e g in system dynamics where a constant time step and a simple algorithm are needed Chapter 6 Running Simulations 37 MonteCarlo specification Monte Carlo simulations Hammersley and Handscomb 1964 Manteufel 1996 see Bibliographic References page 57 randomly sam
96. se lt magnitude gt period lt initial time gt lt exposure time gt e PerExp specifies a periodic exponential input At time lt initial time gt in the lt period gt the input rises instantaneously to lt magnitude gt and begins to decay exponentially with the constant lt decay constant gt The input is turned off once the magnitude reaches a negligible fraction 10717 of its original value Note that the input does not accumulate across periods it resets at each period start Syntax PerExp lt magnitude gt period lt initial time gt lt decay constant gt e NDoses specifies a number of stepwise inputs of variable magnitude and their starting times The first argument lt n gt is the number of input steps and start times Next come a list of magnitudes and a list of corresponding initial times Each list is comma separated The duration of each input step is computed automatically by difference between the listed times Currently this function can only be used in the simulation description file and not in the model description file which simply implies that you cannot use it as a default Syntax NDoses lt n gt lt list of magnitudes gt lt list of initial times gt Note that the list of times must begin at the starting time of the simulation typically time zero even if the magnitude at that first time is zero e Spikes specifies a number of instantaneous inputs of variable magnitude and thei
97. se a consistent notation style The example file perc model tries to follow such a style see Section B 3 perc model page 63 For example we suggest that 28 GNU MCSim User s Manual e All variable names begin with a capital letter followed by meaningful lower case sub scripts e Where two subscripts are necessary they can be separated by an underscore such as in Qb_fat e Where there is only one subscript an underscore can still be used to increase readability as in Q_fat e Where two words are used in combination to name one item they can be separated visually by capitalizing each word as in BodyWt These conventions are suggestions only The key to have a consistent notation that makes sense to you Consistency is one of the best ways to 1 Increase readability both for others and for yourself If you have to suspend work for a month or two and then come back to it the last thing you want is to have to decipher your own file 2 Decrease the likelihood of mistakes If all of the equations are coded with a consistent logical convention mistakes stand out more readily Last but not least do use comments to annotate your code Also make sure your comments are accurate and update them when you change your code In our experience an enormous number of hours has been wasted in trying to figure out inconsistencies that existed only because of inaccurate comments e g erroneous comments about the reasons f
98. see below 6 2 4 Specifying basic conditions to simulate Any simulation file must define at least one Simulation section Simulation sections include particular specifications which are presented in the following Simulation sections After global specifications if any Simulation sections must be included in the input file Expectedly these sections start with the keyword Simulation and are enclosed in curly braces A Simulation section can make assignments to any state variable input variable or parameter defined in the global section of the model description file Output variables cannot receive assignments in simulation input files State variables and parameters can only take constant values see Section 6 2 1 General input file syntax page 35 For state variables this sets the initial value only So for example in a Simulation section the parameter Speed if properly defined can be set using Speed 83 2 This overrides any previously assigned values even if randomly sampled for the specified parameter Inputs can be redefined with input functions see Section 6 2 2 Input functions revis ited page 35 or constant values Input functions can reference other variables eventually randomly sampled as in Q in PerExp InMag 60 0 RateConst The maximum number of Simulation sections allowed in an input file is 200 This can be changed by changing MAX INSTANCES and MAX EXPERIMENTS in the header file sim h and re
99. self if you find a way to start gdb on an executable via xemacs on the command line please tell me Plot will start an Xgnuplot based interface to gnuplot An Help menu available there to guide you further in the arcanes of gnuplot but we recommend that you also browse gnuplot documentation At some point GNU MCSim may do symbolic computations wash dishes clothes and cars and write poems but for now that s all folks Bibliographic References 57 Bibliographic References Barry T M 1996 Recommendations on the testing and use of pseudo random number generators used in Monte Carlo analysis for risk assessment Risk Analysis 16 93 105 Bernardo J M and Smith A F M 1994 Bayesian Theory Wiley New York Bois F Y Gelman A Jiang J Maszle D Zeise L and Alexeef G 1996 Population toxicokinetics of tetrachloroethylene Archives of Toxicology 70 347 355 Bois F Y Smith T J Gelman A Chang H Y Smith A E 1999 Optimal design for a study of butadiene toxicokinetics in humans Toxicological Sciences 49 213 224 Bois F Y Zeise L and Tozer T N 1990 Precision and sensitivity analysis of pharma cokinetic models for cancer risk assessment tetrachloroethylene in mice rats and humans Toxicology and Applied Pharmacology 102 300 315 Gear C W 1971a Algorithm 407 DIFSUB for solution of ordinary differential equa tions D2 Communications of the ACM 14 185 190 Gear C W 1971b The automatic integra
100. t of straight Monte Carlo simulations and will discussed in a later section see Section 6 3 Analyzing simulation output page 50 SetPoints specification To impose a series of set points 1 e already tabulated values for the parameters the global section can include a SetPoints specification It allows you to perform additional simulations with previously Monte Carlo sampled parameter values eventually filtered You can also generate parameters values in a systematic fashion over a grid for example with another program and use them as input to GNU MCSim Importance sampling Latin hypercube sampling grid sampling can be accommodated in this way This command specifies an output filename the name of a text file containing the chosen parameter values the number of simulations to perform and a list of model parameters to read in It has the following syntax SetPoints lt OutputFilename gt lt SetPointsFilename gt lt nRuns gt lt parameter identifier gt lt parameter identifier gt If a null string is given for the output filename the set points output will be written to the same default output file used for Monte Carlo analyses simmc out 40 GNU MCSim User s Manual The SetPointsFilename is required and must refer to an existing file containing the parameter values to use The first line of the set points file is skipped and can contain column headers for example Each of the other lines should contain
101. ta distributed variate on the interval a b with shape parameters alpha and beta e BinomialBetaRandom E alpha beta return random variate of mathematical ex pectation E drawn from a binomial distribution with probability p p being Beta distributed with parameters alpha and beta e BinomialRandom p N returns a binomially distributed random variate e CauchyRandom s returns a Cauchy distributed random variate with scale s e CDFNormal x the normal cumulative density function e Chi2Random dof returns a Chi squared random variate with dof degrees of freedom e erfc x the complementary error function e ExpRandom beta returns an exponential variate with inverse scale beta e GammaRandom alpha returns a gamma distributed random variate with shape pa rameter alpha and inverse scale equal to 1 e GetSeed returns the current value of the random generator seed 24 GNU MCSim User s Manual GGammaRandom alpha beta returns a gamma distributed random variate with shape parameter alpha and inverse scale beta InvGGammaRandom alpha beta returns an inverse gamma distributed random vari ate with shape parameter alpha and scale parameter beta lnDFNormal x mean sd the natural logarithm of the normal density function InGamma x the natural logarithm of the gamma function LogNormalRandom mean sd returns a lognormally distributed variate with geomet ric mean mean and geometric standard deviation sd i e
102. ted with each integration step It includes specification of differential equations Dynamics Venous blood concentrations at the organ exit Cout_fat Q_fat V_fat PC_fat Cout_wp Q wp V wp PC wp Cout pp Q pp V pp PC pp Cout liv Q liv V liv PC liv Sum of Flow Concentration for all compartments dQ ven Flow fat Cout fat Flow wp Cout wp Flow pp Cout pp Flow liv Cout liv Venous blood concentration C ven dQ ven Flow tot Arterial blood concentration Convert input given in ppm to mg l to match other units C art Flow alv C inh PPM per mg per lr OU ven Flow tot Flow alv PC art Alveolar air concentration C_alv C art PC art Exhaled air concentration 66 GNU MCSim User s Manual C_exh 0 7 C alv 0 3 C inh PPM per mg per 1 Differentials dt Q exh Flow alv dt Q fat Flow fat dt Q wp Flow wp dt Q pp Flow pp C alv Cart Cout fat C art Cout wp C art Cout pp Quantity metabolized in liver dQmet liv Vmax Q liv Km Q liv dt Q liv Flow liv C art Cout liv dQmet liv Metabolite formation dt Qmet dQmet liv End of Dynamics Scale Scale certain model parameters and resolve dependencies between parameters Generally the scaling involves a change of units or conversion from percentage to actual units Scale Volumes scaled to actual
103. terface which automatizes the compilation and running tasks of GNU MCSim It also offers a convenient interface to 2 D and 3 D plotting of the simulation results Note that you need XWindows Tcl Tk and wish installed to run XMCSim xemacs is also recommended Just type xmcsim at the command promt A windows appear with a menu bar Menu items are File which allows you to choose an existing model file or to exit the program Once you have chosen a model file its file name appears as a reminder at the bottom of the window Edit which calls xemacs for you to create a new model file or edit any file of your choice for example an input or output file Note if you do not have xemacs installed you can change the file xmcsim to replace the call to xemacs by a call to your editor Compile has two items Compile model will compile the current model file or prompt you for one and will call mod to generate a model c file from it Compile mcsim will first call mod and will then go on to create an executable mcsim filevia a call to makemcsim create an executable program Run with three items Run which will prompt you for an executable mcsim file an input file and an output file the latter is optional and will then launch the executable Stop will just stop a running executable Debug will produce a standalone executable with a name starting with debugmcsim and will launch xemacs for you you will then need to call gdb or another debugger by your
104. the command make or its equivalent to compile and link together the model c file created by mod and the other C files of the sim directory see Chapter 3 Installation page 11 That should create an application you should give it a name specific to the model you are developing e g ncsim perc Refer to your compiler manual for details on how to use your programming environment Your executable mcsim perc program is now ready to perform simulations To start your GNU MCSim program just type mcsim perc if you gave it that name under Unix After an introductory banner telling in particular which model file the program has been compiled with you are prompted for an input file name type in perc lsodes in see Section B 4 perc lsodes in page 68 to see this file in Appendix then a space and then type in the output file name perc lsodes out After a few seconds or less depending on your machine the program announces that it has finished and that the output file is perc lsodes out You can open the output file with any text editor or word processor you can edit it for input in graphic programs etc You can try the various demonstration models provided in the samples directory and observe the output you obtain You can then start programming you own models and doing simulations The next sections of this manual reference the syntax for model definition and simulation specifications Chapter 5 Setting up Structural Models 17 5 Setting
105. tice grants a world wide royalty free license unlimited in duration to use that work under the conditions stated herein The Document below refers to any such manual or work Any member of the public is a licensee and is addressed as you You accept the license if you copy modify or distribute the work in a way requiring permission under copyright law GNU MCSim User s Manual A Modified Version of the Document means any work containing the Document or a portion of it either copied verbatim or with modifications and or translated into another language Secondary Section is a named appendix or a front matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document s overall subject or to related matters and contains nothing that could fall directly within that overall subject Thus if the Document is in part a textbook of mathematics a Secondary Section may not explain any mathematics The relationship could be a matter of historical connection with the subject or with related matters or of legal commercial philosophical ethical or political position regarding them The Invariant Sections are certain Secondary Sections whose titles are designated as being those of Invariant Sections in the notice that says that the Document is released under this License If a section does not fit the above definition of Secondary then it is not all
106. tion 5 3 1 General syntax page 18 except that e No new variable can be created all variables must have been defined in the model defi nition file Assignments can only modify the value of already defined model variables This implies that parameters needed to set up a statistical model must be declared in the model definition file even if the structural model does not use them e Assignments to state variables or parameters can only use constant values mathemat ical expressions are not allowed e Input variables assignments can use any input function including the NDoses and Spikes functions or constant values e Output variables cannot receive assignments At the program start all model parameters are initialized to the nominal values specified in the model description file Next after the input file is read modifications given in its global section including random sampling are applied then those specified at each Level and finally any modifications specified by the Simulation sections Computations specified in the Initialize section of the model definition file are the last initialization statements executed Structural changes to the model e g addition of a state input output or parameter cannot be done here and must be done in the model description file The simulation specification file is read until its end is reached or until an End command is reached 6 2 2 Input functions revisited Input variables
107. tion of ordinary differential equations Com munications of the ACM 14 176 179 Gelman A 1992 Iterative and non iterative simulation algorithms Computing Science and Statistics 24 433 438 Gelman A Bois F Y and Jiang J 1996 Physiological pharmacokinetic analysis using population modeling and informative prior distributions Journal of the American Statisti cal Association 91 1400 1412 Gelman A Carlin J B Stern H S and Rubin D B 1995 Bayesian Data Analysis Chapman amp Hall London Gelman A and Rubin D B 1992 Inference from iterative simulation using multiple sequences with discussion Statistical Science 7 457 511 Geyer C J and Thompson E A 1995 Annealing Markov chain Monte Carlo with applications to ancestral inference Journal of the American Statistical Association90 909 920 Gilks W R Richardson S and Spiegelhalter D J 1996 Markov Chain Monte Carlo In Practice Chapman amp Hall London Hammersley J M and Handscomb D C 1964 Monte Carlo Methods Chapman and Hall London Manteufel R D 1996 Variance based importance analysis applied to a complex prob abilistic performance assessment Risk Analysis 16 587 598 Park S K and Miller K W 1988 Random number generators good ones are hard to find Communications of the ACM 31 1192 1201 Press W H Flannery B P Teukolsky S A and Vetterling W T 1989 Numerical Recipes 2nd ed Cambridge University Press Cambridge Smith A F
108. ts to link with the model c files generated by mod after processing your mod els The final product should be an executable able to run your model Linking with the GNU Scientific Library gs1 is recommended but not mandatory In that case define the HAVE LIBGSL flag and link with the 1gs1 and lgslcblas in that order You are now ready to use GNU MCSim We recommend that you go through the next section of this manual which walks you through an example of model building and running Chapter 4 Working Through an Example 15 4 Working Through an Example Several models and simulation specification files are provided with the package as examples they are in the samples directory You can try any of them The linear regression model is particularly simple but to be more complete we will try here a nonlinear implicit model specified through differential equations Pharmacokinetics models describe the transport and transformation of chemical com pounds in the body These models often include nonlinear first order differential equations The following example is taken from our own work on the kinetics of tetrachloroethylene a solvent in the human body Bois et al 1996 Bois et al 1990 see Bibliographic References page 57 Go to the mcsim samples perc directory installed either locally or by default in usr share under Unix or GNU Linux Open the file perc model with any text editor e g emacs or vi under Unix This file is a
109. u with an updated version of the Document MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above provided that you release the Modified Version under precisely this License with the Modified Version filling the role of the Document thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it In addition you must do these things in the Modified Version A Use in the Title Page and on the covers if any a title distinct from that of the Document and from those of previous versions which should if there were any be listed in the History section of the Document You may use the same title as a previous version if the original publisher of that version gives permission List on the Title Page as authors one or more persons or entities responsible for authorship of the modifications in the Modified Version together with at least five of the principal authors of the Document all of its principal authors if it has fewer than five unless they release you from this requirement State on the Title page the name of the publisher of the Modified Version as the publisher Preserve all the copyright notices of the Document Add an appropriate copyright notice for your modifications adjacent to the other copyright notices Include immediately after the copyright notices a license notice giving the public permission t
110. unction of x Here is such a model quite similar to the one distributed with GNU MCSim source code see Section B 1 linear model page 61 Outputs y Structural model parameters Alpha 0 Beta 0 x bar 0 Statistical parameter Sigma2 1 CalcOutputs y Alpha Beta t x bar The parameters default values are arbitrary and could be anything reasonable They will be changed or sampled through the input file Note thato is not used in the model equations but still needs to be defined here in order to be part of the statistical model On the other hand u is not defined since we do not really need it Finally x is replaced by the time t for convenience An alternative would be to define an input x and use it instead of t We now need to write an input file specifying the distribution of y e the likeli hood and the prior distributions of the various parameters Technically GNU MCSim uses Metropolis sampling and you do not need to worry about issues of conjugacy or log concavity of your prior or posterior distributions Here is what a simulation file with a statistical model looks like 48 GNU MCSim User s Manual C Simulation input file for a linear regression
111. up Structural Models The model generator mod was created to facilitate structural model definition and maintenance while keeping short execution time through compilation This chapter ex plains how to use mod and how to code your models using a simplified syntax that mod can translate in C creating thereby a model c file After compiling and linking of the newly created model c file together with the other C files of the mcsim sim directory or after linking with a dynamic library libmcsim so an executable simulation program is created specific of your particular model These preprocessing and compilation steps can be performed in Unix with a single shell command makemcsim in which case the model c is created only temporarily and erased after that Several examples of model simulation files are included in the mcsim samples directory Some of them are reproduced in Appendix see Appendix B Examples page 61 5 1 Using mod to preprocess model description files The mod program is a stand alone facility It takes a model description file in the user friendly format described below see Section 5 3 Syntax of mod files page 18 and cre ates a C language file model c which you will compile and link to produce the simulation program Mod allows the user to define equations for the model assign default values to pa rameters or default initial values to model variables and to initialize them using additional algebraic equations
112. volumes BodyWt LeanBodyWt 1 Pct_M_ fat V_fat Pct M fat BodyWt 0 92 density of fat 0 92 g ml V liv Pct LM liv LeanBodyWt V wp Pct LM wp LeanBodyWt V pp 0 9 LeanBodyWt V liv V wp 10 bones Calculate Flow alv from total pulmonary flow Flow alv Flow pul 0 7 Calculate total blood flow from the alveolar ventilation rate and the V P ratio Appendix B Examples 67 Flow tot Flow alv Vent Perf Calculate actual blood flows from total flow and percent flows Flow fat Pct Flow fat Flow tot Flow liv Pct Flow liv Flow tot Flow pp Pct Flow pp Flow tot Flow wp Flow tot Flow fat Flow liv Flow pp Vmax mass time for Michaelis Menten metabolism is scaled by multiplication of bdw 0 7 Vmax sc Vmax exp 0 7 log LeanBodyWt End of model scaling CalcOutputs The following outputs are only calculated just before values are saved They are not calculated with each integration step CalcOutputs 1 Fraction of TCE metabolized per day Pct metabolized InhMag Qmet 1440 Flow alv InhMag mg per 1l per PPM 0 C_exh_ug C exh 1000 milli to micrograms 4 End of output calculation 68 GNU MCSim User s Manual B 4 perc lsodes in The following is a simulation of one of Dr Monster s exposure experiments described in Kinetics of Tetracholoroethylene in Volunteers Influence of Exposure Concentration and Work Load A C Mo
113. your own scale with the InvTemperature specification with the following syntax InvTemperature lt nValues gt value 1 gt lt gt lt value n gt The first number of the specification gives the number of inverse temperatures to use and is followed by a list of them Those should be numbers in the interval J0 1 You usually would want to end with a value of 1 since temperature 1 is the cold end of the temperature scale corresponding to your target distribution e Finally with lt simTypeFlag gt set to 4 GNU MCSim does stochastic optimization an MCMC in which only but all jumps leading posterior density improvement are ac cepted The integer lt printFrequency gt should be set to 1 if you want an output at each iteration to 2 if you want an output at every other iteration etc The parameter lt itersToPrint gt is the number of final iterations for which output is required e g 1000 will request output for the last 1000 iterations to print all iterations just set this parameter to the value of lt nRuns gt Note that if no restart file is used the first iteration is always printed regardless of the value of lt itersToPrint gt Finally the seed lt RandomSeed gt of the pseudo random number generator can be any positive real number Seeds between 1 0 and 2147483646 0 are used as is others are rescaled silently within those bounds Finally the format of the output file of MCMC simulations is quite similar to tha

GNUMCSim: A Monte Carlo Simulation Program

Contents

Download Pdf Manuals

Related Search

Related Contents