Appendix: Creating a new Modgen database file
Overview
If you want to make a biography using different actors and/or states, you will need to create a new database using Modgen. The creation of the database file occurs with the execution of a Modgen simulation model and, therefore, requires some knowledge of the Modgen simulation environment. The name, location, and contents of this special file are controlled as follows:
-
the filename, its location within the directory structure, and the number of simulated lifetimes contained within the database file are defined through a Modgen scenario and its Scenario Settings dialog box. Modgen manages model run outputs by using the scenario name followed by a bracketed identifier indicating the type of Modgen output and an extension indicating the type of file. For tracking outputs, the convention used is: scenario_name(trk).mdb.
- the set of actor/states to be displayed by BioBrowser must first be listed in the model variable trackingfacility within the Modgen source code for the specific simulation model. This set including the tracking filter for each actor are required by the model at compile time and can not be dynamically set at run time.
Scenario settings
There are a variety of Modgen scenario settings which determine the nature of each specific simulation. The scenario settings are discussed in complete detail in the Modgen User’s Guide. However, there are three main settings which must be understood in order to create an appropriate database file for the Biographical Browser.
- In the Scenario/Settings/General tab, select "MS Access tracking". This setting tells Modgen that, in addition to the other outputs specified, a tracking database file is requested as output for this model run.
- For case based models, select the number of cases in the Scenario/Settings/General tab. As a general rule, it is important to specify a small number here since all of the simulated cases which meet the tracking filter will be included in the database file. The size of this file can become very large, very quickly depending on the number of cases and states included. In addition, variable tracking will slow the simulation down considerably.
- For time based models, select the time-units in the Scenario/Settings/General tab.
The demonstration file accompanying this release, demo(trk).mdb, contains 20 cases (which for this model corresponds to 20 simulated lifetimes of a person actor whose dominant state is True). It was created from the Statistics Canada model, LifePaths.
Modgen model state tracking
The tracking facility provided by the Modgen language controls the type of actors to be included in the database file along with the list of states which are to be analyzed with BioBrowser.
The track command must be included in one of the .mpp files which contain the Modgen model code which define the simulation model. If the analyst wishes to change the type of actors to be tracked, or change the complement of the states to be output, then the Model must be re-compiled. This is discussed further in the Modgen Developer’s Guide. This guide should also be consulted by readers who are unfamiliar with the concepts outlined in the syntax and examples which follow.
Syntax of the Track Command
track actor_name [filter] { state_or_link , ... , state_or_link } ;
It is important to remember that only one track definition is allowed for each actor in the model. In addition, the filter specifies if and when an actor’s states or links are to be output to the database file.
Example
In this example, the states which describe the person are only output to the database file when he/she is married or remarried (the dominant characteristic is discussed in the Modgen Developer’s Guide). Therefore, if the person was married at age 25, divorced at age 40, and re-married at age 50, then the database file would only contain information on this person from the ages of 25 through 40; and 50 to the age at death. There are nine states which describe the characteristics of the individuals stored in the database file. The last two items of the track definition are not variables but links to other individuals associated with this person. In this case, the database will contain information on the nine variables defined in the track command on the person’s spouse and children if they are present.
track Person
[ dominant || mar_status == MARRIED || mar_status == REMARRIED ]
{
es_state,
ed_level_ep,
sex,
dominant,
employed,
mar_status,
marstat_legal,
fte_earnings,
children_at_home,
lSpouse,
mlChildren
};
Example
In this example the date of birth and sex states for a child actor are output to the database file once the child is established in a family (the tentative characteristic is discussed in the Modgen Developer’s Guide.
track Child [ !tentative ]
{
date_of_birth,
sex,
mlParents
};
Contents of the database file
The MS Access file produced by a Modgen simulation contains a data table called History and the following dictionaries organized hierarchically:
ActorDic - actor dictionary.
ActorStateDic - tracked state dictionary.
ActorLinkDic – tracked linked actor dictionary.
TypeDic - state type dictionary containing a pointer to a specific dictionary below.
The dictionaries for each state type are as follows:
SimpleTypeDic - for simple state types e.g.integer, double, float.
LogicalDic - for logical states.
ClassificationDic and ClassificationValueDic - for classification states and their values.
RangeDic - for range type states.
TypeDic - for linked actors.
Any dictionary with textual identifiers will contain 1 record for each language implemented in the specific Modgen model, as indicated by LanguageDic.
In addition, a file version table called VersionInfo will indicate the version of the tracking file. The BioBrowser uses this version to maintain backward compatibility if the tracking database design is changed.
The History table contains one record for each tracked state at one point in time. A record is added to this table, each time a tracked state changes for each tracked actor. The History table fields used by BioBrowser are: an object identifier, time, a state identifier, and a value for the given state. The ShowData window contains a subset of records from this table. Since the object identifier is common across all records in the ShowData window, its value is shown in the window caption.
- Date modified: