Population Size and Scaling - openmpp/openmpp.github.io GitHub Wiki
Home > Model Development Topics > Population Size and Scaling
This topic describes ways a model can specify the size of the simulation population, the size of the real-world population represented by the simulation population, and the scaling of table results to the size of the real-world population.
-
Use Modules: The
usestatement and supplied library ofuseframework modules
- Introduction
- Population size and scaling - case-based model
- Population size and scaling - time-based model
The following concepts are used in this topic.
| Term | Explanation |
|---|---|
| run | An execution of a model. A run can consist of one or more independent subs/members/replicates. |
| member/replicate/sub/subsample | Synonyms denoting each of the independent simulations which together constitute a run. |
| case | An independent, isolated entity or small collection of related entities such as a family or clan. |
| case-based model | A model which simulates, in each sub/replicate, a population of independent, non-interacting cases. |
| time-based model | A model which simulates, in each sub/replicate, a population of interacting entities. |
| simulation population | The population of entities in a model simulation. |
| real population | The real-world population represented by a simulation population. |
use module |
A code module supplied with OpenM++ which implements underlying functionality for a model. |
An OpenM++ model specifies population size and scaling in different ways depending on what kind of model it is. For example, a model which creates a synthetic population from multivariate distributions has no intrinsic size whereas a model based on a micro-data file may have its size fixed to the number of observations in that file.
To support different model frameworks OpenM++ includes a library of source code modules. Selected modules from this library are incorporated into a model through use statements to implement the desired model framework. These use statements are usually found in a model code module named ompp_framework.ompp. For more information, please see the Use Modules topic.
Population size and scaling is specified for a case-based model by selecting a pair of modules from the use library,
one which determines population size and one which determines population scaling.
For example, the following code fragment from the ompp_framework.ompp module for a model specifies
that population size is given for the entire run (rather than for each replicate of the run),
and that the results are not scaled to a real population.
use "case_based/case_based_cases_per_run_exogenous.ompp";
use "case_based/case_based_scaling_none.ompp";The following table lists the available choices to specify population size for a case-based model:
use module |
Description |
|---|---|
case_based/case_based_cases_per_member_exogenous.ompp |
The number of cases in a member is given by the input parameter CasesPerMember which is declared in this module. The number of cases in the run is the product of CasesPerMember and the number of replicates specified for the run. |
case_based/case_based_cases_per_run_exogenous.ompp |
The number of cases for the entire run is given by the input parameter SimulationCases which is declared in this module. The cases are evenly divided among the members specified for the run. Any 'extra' cases are assigned to lower-numbered members. |
case_based/case_based_cases_per_member_endogenous.ompp |
The number of cases in a member is given endogenously by the derived parameter CasesPerMember, which is declared in this module. CasesPerMember is set by a PreSimulation function in model code. CasesPerMember might, for example, be set to the number of observations in a micro-data input file. The number of cases in the run is the product of CasesPerMember and the number of replicates specified for the run. NOT YET IMPLEMENTED
|
case_based/case_based_cases_per_run_endogenous.ompp |
The number of cases for the entire run is given endogenously by the derived parameter SimulationCases, which is declared in this module. SimulationCases is set by a PreSimulation function in model code. SimulationCases might, for example, be set to the number of observations in a micro-data input file. Model code would allocate observations in the micro-data file evenly to each of the members of the run, and allocate any 'extra' cases to lower-numbered members. NOT YET IMPLEMENTED
|
The following table shows the available choices to specify population scaling for a case-based model:
use module |
Description |
|---|---|
case_based/case_based_scaling_exogenous.ompp |
The simulated population in each sub/member/replicate is scaled to represent the real-world population given by the input parameter SimulatedPopulation, which is declared in this module. Incorporates weights if model uses weighted tabulation. |
case_based/case_based_scaling_endogenous.ompp |
The simulated population in each sub/member/replicate is scaled to represent a real-world population provided by model code by a call to the global function SetPopulation(). Incorporates weights if model uses weighted tabulation. |
case_based/case_based_scaling_none.ompp |
The simulated population in each sub/member/replicate is scaled to the number of cases in the run. For a run with a single member, this is equivalent to no population scaling. For a run with more than one member, each member is scaled up by the number of members in the run. |
case_based/case_based_scaling_endogenous_or_none.ompp |
Acts like case_based_scaling_endogenous if the parameter DisablePopulationScaling is false, or like case_based_scaling_none if true. |
case_based/case_based_scaling_disable.ompp |
Disables population scaling. Each sub is scaled up by the number of subs, which causes overall (average) run results to become the sums of the original (unscaled) subs. |
Population size and scaling is specified for a time-based model by selecting a module from the use library which determines both population size and scaling. All such modules declare a parameter StartingPopulationSize which gices the size of the starting population. The size of the starting population is the same for all members of a time-based model run.
The following code fragment from the ompp_framework.ompp module for a model specifies that results are not scaled.
use "time_based/time_based_scaling_none.ompp";The following table shows the available choices to specify population size scaling for a time-based model:
use module |
Description |
|---|---|
time_based/time_based_scaling_exogenous.ompp |
The simulated population in each member/replicate is scaled to represent the real-world population given by the input parameter SimulatedPopulation, which is declared in this module. |
time_based/time_based_scaling_endogenous.ompp |
The simulated population in each member/replicate is scaled to represent the real-world population given by the input parameter SimulatedPopulation, which is declared in this module. Or maybe by a call to the function SetPopulation(). NOT FULLY TESTED
|
time_based/time_based_scaling_none.ompp |
The simulated population in each member/replicate is not scaled. |