Step 1: Creating a Population ============================= The microWELT model development starts from a very generic basic template for typical continuous-time interacting population models. The model creates a starting population from a weighted file of observations. While not having much functionality at this point, the model provides a starting point 'hiding' some of the more tricky coding. Newcomers to Modgen are not required to fully understand all the code at this point: the following steps of model development introduce the basic concepts from a modelers perspective and provide step-by-step instructions for model building using Modgen. Model Description ----------------- .. include:: Step01/code/model_info.mpp :start-after: NOTE(model, EN) :end-before: */ File input ---------- The micro-data population **input file** is a csv-file which currently contains the following variables: - Household ID - Weight - Time of birth - Sex - Role in family The variables, including their order, have to correspond with the variables in the starting population file. The list can simply be expanded as required. Parameters ---------- The model currently has 7 **parameters** organized into 2 groups: Starting population and Microdata output. .. figure:: Figures/Step01_Parameters.png *Figure: Model Parameters* The starting population parameters are: - The file name - The file size - The simulated sample size (which can be bigger or smaller than the file) - The real population size (to which all output is automatically scaled) The starting population is generated from a weighted file of observations. Depending on weights and the desired simulation size, a population of actors is created from the observations, whereby individual observations might or might not be picked or picked various times. Parameters for micro-data output are: - A check-box to switch output on/off - A file-name for the output file - Parameters for the timing of the first and the last output and output intervals Users can select when output should be written, which can be a single point in time or repeated panel waves with regular intervals. Model Output ------------ At this point, the model creates 3 output table as well as a micro-data output file. File output is generated in csv format including a header row containing variable names. Tables are part of the graphical user interface and there are various options to copy/paste or export tables. Code organization and a classification of files ----------------------------------------------- Modgen code is organized in .mpp files which can be classified into 4 groups. **Simulation engine:** these files contain general model settings and the the code to run a simulation. Most of the code was automatically generated by the Modgen model wizard for time-based models. The code is mostly pure C++ and developers typically are not required to modify -- or understand -- it. The model is designed to run for various countries. All country and version specific code (like start year) are kept in a separate file _CountryContext.mpp. - model_core.mp - model_info.mpp - modgen_timebased - _CountryContext.mpp **Actor core files:** Each Actor introduced in the model typically has a core file which contains general characteristics and functions of the actor. Our model at this point has four actor types, Observations (one for each record of the starting population file), Persons (the actual simulated entities representing the population), a Clock, and an actor Globals (for storing information easily accessible for all actors). Accordingly, there are four core files: - ObservationCore.mpp - PersonCore.mpp - ClockCore.mpp - GlobalsCore.mpp **Regular modules:** These are the modules developers typically spend most of their time on. Usually there is one such module by modeled behavior (like fertility, mortality, labor force participation) and policy system. At the moment, our model contains just one such module: - CalendarYearChange.mpp **Output modules:** Modgen models produce three types of output: tables, micro-data, and a database of tracked actors used for a visualization tool called BioBrowser. The template provides two output files: - Tables.mpp: contains all table output - MicroDataOutput.mpp: handles micro-data output Besides the model code, modes come with one or mode parameter files, as well as micro-data input and output files. **Parameter .dat files:** values are stored in one or more .dat files, which are readable text-files. Parameters are typically changed within the graphical user interface of the model. - Default(PersonCore).dat: contains all model parameters. The file-name consists of a scenario name (Default) and the parameter file name. A user creating and saving a new scenario would generate a new file, e.g. NewScenario(PersonCore). **Microdata csv input and output**: Micro-data in/output is organized in csv (comma separated values) files, which are readable text files. File-names can be chosen by the model user, e.g. - startpop_YYYY_COUNTRY.csv - micro_output_YYYY_COUNTRY.csv Model Documentation ------------------- Modgen models are self-documenting: Users can access a help file from the menu of the user interface. Labels and notes for modules (as well as any symbols used in the program) are used for the automatically generated model help file for users, thus good documentation is not only best practice for model development, but also creates a detailed documentation for the user. - A **label**: a one line description - A **note**: a more detailed description Example: :: //LABEL (CalendarYearChange, EN) Calendar Year Change /* NOTE (CalendarYearChange, EN) This module handles calendar year changes. Before a year ends, the Person function YearEnd() is called by the Calendar clock actor. This is a point in time in which models typically update accounts and perform other end of year routines. Immediately after the year end, the YearStart() routine is called. This is when the calendar_year state is changed. */ Placed above or in the same line of a newly introduced symbol, labels can also be written as :: //EN The text of the label Labels are introduced by a language code (EN for English in our case) Modgen also support multilingual applications, in which these labels are translated into (an)other language(s). Besides their purpose of code documentation, these labels are used in the user interface, e.g. for column headings in tables or for the labeling of parameters. .. figure:: Figures/Step01_Help.png *Figure: Help System* Code Discussion --------------- Model Information: model_info.mpp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This file is used for model documentation and contains a model description. The file is for documentation only and does not contain any model code. The Simulation Engine: model_core.mpp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: Step01/code/model_core.mpp :start-after: NOTE(model_core, EN) :end-before: */ .. include:: Step01/code/model_core.mpp :start-after: */ :code: Modgen Simulation Framework: modgen_time_based.mpp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: Step01/code/modgen_time_based.mpp :start-after: NOTE(modgen_time_based, EN) :end-before: */ The Country/Version-Specific Settings: _CountryContext ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: Step01/code/_CountryContext.mpp :start-after: NOTE(_CountryContext, EN) :end-before: */ .. include:: Step01/code/_CountryContext.mpp :start-after: */ :code: Core file of the Observation Actor: ObservationCore.mpp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: Step01/code/ObservationCore.mpp :start-after: NOTE(ObservationCore, EN) :end-before: */ .. include:: Step01/code/ObservationCore.mpp :start-after: */ :code: Core file of the Person Actor: PersonCore.mpp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: Step01/code/PersonCore.mpp :start-after: NOTE(PersonCore, EN) :end-before: */ As for any actor, its core file is a good place to declare states and corresponding types which do not belong to specific behaviors but are used by various modules (e.g. sex). Also, the Start() and Finish() functions of each actor are declared in its core file. .. include:: Step01/code/PersonCore.mpp :start-after: */ :code: Core file of the Clock Actor: ClockCore.mpp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: Step01/code/ClockCore.mpp :start-after: NOTE(ClockCore, EN) :end-before: */ .. include:: Step01/code/ClockCore.mpp :start-after: */ :code: Core file of the Globals Actor: GlobalsCore.mpp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: Step01/code/GlobalsCore.mpp :start-after: NOTE(GlobalsCore, EN) :end-before: */ .. include:: Step01/code/GlobalsCore.mpp :start-after: */ :code: Actions at Year End: CalendarYearChange.mpp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: Step01/code/CalendarYearChange.mpp :start-after: NOTE(CalendarYearChange, EN) :end-before: */ .. include:: Step01/code/CalendarYearChange.mpp :start-after: */ :code: Micro Data Output: MicroDataOutput.mpp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: Step01/code/MicroDataOutput.mpp :start-after: NOTE(MicroDataOutput, EN) :end-before: */ .. include:: Step01/code/MicroDataOutput.mpp :start-after: */ :code: Micro Data Output: TablesPopulation.mpp ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. include:: Step01/code/Tables.mpp :start-after: NOTE(Tables, EN) :end-before: */ .. include:: Step01/code/Tables.mpp :start-after: */ :code: