-
Notifications
You must be signed in to change notification settings - Fork 11
FAQ
What is the difference between a parameter and a variable?
Why does it say my probabilities do not sum to 1?
What is the order of operations at each node?
How do I use a vector parameter?
How do I sample from a Dirichlet distribution?
How do I increase the Java heap size?
How do I cite Amua?
How do I report a bug?
How do I request a new feature?
Is Amua stable?
Parameters are fixed for a given simulation and can be explored in sensitivity analyses or fit via model calibration. Parameters are used to explore 2nd-order or parameter uncertainty.
Variables can change within a simulation - either over time (via variable updates), or across individuals in a Monte Carlo simulation. You could use variables to count the number of events an individual experiences, or to model heterogeneity in a cohort. Variables can thus be used to track events or explore 1st-order or stochastic uncertainty.
Example: Suppose you are developing a Monte Carlo HIV model and want each individual to have their own CD4 count drawn from a distribution. You could use parameters to specify the distribution (e.g. mean and variance) and use a variable called CD4 to assign each person a value sampled from the distribution.
Computers store numbers using finite precision, so there will be times when your probabilities do not sum exactly to 1.0. Amua has a tolerance of 10-8 set internally to deal with this issue, but if you still run into it you should specify one of the probabilities as C (complementary probability) so that Amua will ensure that all probabilities sum to 1.
- Cycle rewards are applied (if Markov State)
- Costs are applied (if applicable)
- Explicit variable updates (if applicable)
- Implicit (dependent) variable updates (if applicable)
- Child probabilities are calculated
A vector/matrix parameter (or variable) is a parameter that returns a matrix (i.e. not just a single number). Many functions and distributions support vector arguments. To reference a value from a vector parameter, the vector index to retrieve is specified using brackets: []. Indices begin at 0. For example, a vector of 10 iid Beta distributions could be defined as a parameter called betas: Beta(rep(2,10), rep(1,10), ~). To retrieve the first sample from the vector parameter you would call betas[0]. (See matrix tables for more information.)
Matrix elements can also be used as arguments. For example, a matrix table called params which contains two column vectors of Beta parameters (a,b) could be defined as:
| a | b |
|---|---|
| 1 | 3 |
| 2 | 4 |
| 3 | 5 |
| 4 | 6 |
(Note: Column headers are not allowed when defining matrix tables, but are included above for illustrative purposes.)
A vector parameter of Beta distributions called betas could then be defined using the columns of this matrix as parameters: Beta(params[:,0], params[:,1], ~). This would return a column vector of samples.
To sample from a Dirichlet distribution you can define a parameter (e.g. called dirichlet) with an expression: Dir([1,5,4],~). The first argument supplies the row vector of alphas [], and the second argument ~ says that you want to sample from the distribution.
To get a value from this parameter (which is a random vector) you reference a particular index of the vector. For example, dirichlet[0] would return the first value, dirichlet[1] would return the second value, etc.
Reminder: Enter C (complementary probability) as the probability for one of the branches to ensure that all sampled probabilities sum to 1.0 (see FAQ above: Why does it say my probabilities do not sum to 1?)
Amua runs on a Java Virtual Machine (JVM) which is allocated some memory when it starts up. You can see how much memory is available by going to Help -> Error Log and scrolling to the bottom where it reports Heap - Max Memory.
You may need to request more memory than the default however. For example, if you are running a Monte Carlo simulation with many individuals the model may become unresponsive if you run out of memory. To request more memory you need to tell the JVM to allocate a larger heap space when Amua starts up. This can be done from the command line, or by creating a shortcut to the Amua jar. The advantage of creating a shortcut is that it can be re-used.
Windows: To create a shortcut, right-click on the Amua jar and select 'Create shortcut'. In the shortcut properties edit the Target to be: java -Xmx[choose memory] -jar [path to Amua.jar]. For example: java -Xmx8g -jar C:\Users\zward\Dropbox\Amua\jars\Amua_0.2.1.jar will open Amua with a max heap size of 8GB. You can increase the heap size up to 4GB on a 32 bit system, or higher if you're on a 64 bit system. Click 'Ok' and then double-click the shortcut to open Amua. Check the system properties in the Error Log to make sure the maximum heap size has been increased.
Academic citation:
Ward ZJ. Amua – An Open-Source Modelling Framework and Probabilistic Programming Language. In: Computational Epidemiology: Methods and Applications for Global Health. Dissertation. Harvard University; 2021. https://github.com/zward/Amua
Or a simpler citation:
Ward ZJ. Amua: An open source modeling framework. 2019. https://github.com/zward/Amua
You can report bugs by submitting an issue.
Some guidelines for submitting a helpful bug report:
- Check the list of issues first to see if the problem has already been submitted
- Include a copy of the error log (Help -> Error Log). Even if the error was not recorded the log has system information that might be useful
- Describe how to reproduce the problem
- If the error log is empty you can usually get more information by running Amua from the command line since the console should capture any error reporting that doesn't get recorded by the error log
You can request new features by submitting an issue.
Here is a general road map of planned future development:
- Stability: Early versions of Amua are focused on fleshing out basic features and fixing bugs
- Calibration methods: Adding other methods for model calibration
- Performance: Future versions will focus on improving performance (e.g. multi-threading and distributed computing options)
- Enhancements: Adding other model types and support for other languages
Amua is still in the early stages of development, but every effort will be made to ensure that new versions of Amua will be backwards compatible with models developed in earlier versions. Models are saved in XML format, so in the worst case scenario, the tags in older models can be updated to be compatible with newer versions.