LIAM 2 User Guide
Contents
1. LIAM 2 User Guide Release 0 4 1 to separate separave Or partner separale Note that it is perfectly valid to chain links as for example in grand_parents_income mother mother income mother father income father mother income father father income Another option to get values in the linked individual is to use the form link_name get expr this syntax is a bit more verbose in the simple case but is much more powerful as it allows to evaluate almost any expression on the linked individual For example if you want to get the average age of both parents of the mother of each individual you can do it so mother get mother age father age 2 5 2 one2many A one2many links an item in an entity to at least one other item in the same eg a person to its children or other entity a household to its members entities household IES e persons type one2many target person field household_id person fields ages aba meone EOE household 1d 3 me JLMalES E household type many2one target household field household_id e persons is the link from the household to its members e household is the link form a person to the household To use information stored in the linked entities you have to use aggregate functions e countlink eg countlink persons gives the numbers of persons in the household e sumlink eg sumlink persons income sums up all in2. e A demonstration model with a synthetic data set of 20 200 persons grouped in 14 700 households 2 2 Getting Started e Copy the contents of the bundle in a directory on your disk let s call it Vocalpath e Run the Notepad Portable exe from the Vocalpath Liam2Suite editor directory e Open a model eg localpath Liam2Suite examples demo01 yml e Press F6 to run the model A console window will open within the editor and display the status of the simulation After the simulation completes the console window becomes interactive e Use this console to explore the results 2 3 Using your own data e Prepare your data as CSV files The first row should contain the name of the fields You need at least two integer columns id and period though they do not necessarily need to be named like that in the csv file e Create an import file as described in the mporting data section You can use Mocal path Liam2Suite examples demo_import yml as an example e Press F5 to convert your CSV files to hdf5 e Use the newly created data file with your model LIAM 2 User Guide Release 0 4 1 4 Chapter 2 Environment CHAPTER THREE MODEL DEFINITION To define the model we have to describe the different entities their fields the way they interact links and how they behave over time processes This is done in one file We use the YAML markup language This format uses the level of indentation to specif
3. Chapter 5 Links CHAPTER SIX IMPORTING DATA 6 1 data files As of now you can only import CSV files one file for each entity Their first row should contain the name of the fields You need at least two integer columns id and period though they do not necessarily need to be named like that in the csv file 6 2 description file To import CSV files you need to create a description file Those description files have the following general format output lt p RAMO and SES compression is optional compression type can be zlib bzip2 or lzo level is a digit from 1 to 9 and is optional defaults to 5 Examples of valid compression strings are zlib lzo 1 bzip2 9 You should experiment to see which compression scheme if any offers the best trade off for your dataset compression lt type gt lt level gt globals periodic path lt path_of_globals_file gt csv if the csv file is transposed each field is on a row instead of a column and the field names are in the first column instead of the first row you can use transpose true You do not need to specify anything if the file is not transposed transposed true entities lt entityl_name gt path lt path_to_entityl_data gt csv if you want to manually select the fields to be used and or specify their types you can do so in the following section If you want to use all the fields present
4. path input globals_transposed csv transposed true entities household path input household csv person path input person csv fields ages ILIRE gender bool workstate arate civilstate int partner dat aj AE oldnames gender male simpler example output simple h5 globals periodic path input globals csv entities household path input household csv 34 Chapter 6 Importing data LIAM 2 User Guide Release 0 4 1 person path input person csv simplest example output simplest h5 entities household person This will try to load all the fields of the household and person entities in household csv and person csv in the same directory than the description file 6 3 importing the data Once you have your data as CSV files and created a description file you can import your data e If you are using the bundled editor simply open the description file and press F5 e If you are using the command line use liam2 import lt path_to_description_file gt 6 3 importing the data 35 LIAM 2 User Guide Release 0 4 1 36 Chapter 6 Importing data CHAPTER SEVEN INDICES AND TABLES LIAM 2 User Guide Release 0 4 1 38 Chapter 7 Indices and tables CHAPTER EIGHT APPENDIX 8 1 Technical choices 8 1 1 Python We use the Python language http www python org for the de
5. for floats 1 for integers and False for booleans Those extra arguments can be given constants but also any expression possibly using links random functions Those expressions are evaluated in the context of the origin individuals For example you could write mother_age age which would set the field mother_age on the new item to the age of their mother example 1 pacti to gyve lacas Logig ege 0 07 filter not gender and age gt 15 and age lt 50 align al_p_birth csv new person filter to_give_birth mother_id id father_id partner id household_id household_id patas _ IT age 0 civilstate 1 Colter 10 education_level 1 workstate 5 gender choice True False 0 51 0 49 The first sub process to_give_birth is a logit regression over women not gender between 15 and 50 which returns a boolean value whether that person should give birth or not The logit itself does not have a deterministic part 0 0 which means that the fertility rank of women that meet the above condition is only determined by a logistic stochastic variable This process is also aligned on the data in al_p_birth csv In the above case a new person is created for each time a woman is scheduled to give birth Secondly a number of links are established the value for the mother_id field of the child is set to the id number of his her mother the child receive
6. observed data is read from the file specified in the input entry Specifying the path is optional If it is omitted it defaults to the directory where the simulation file is located The hdf5 file format can be browsed with vitables http vitables berlios de or another hdf5 browser available on the net 3 3 4 output The simulation result is stored in the file specified in the output entry Only the variables defined at the entity level are stored Temporary local variables are not saved The output file contains values for each period and each field and each item Specifying the path is optional If it is omitted it defaults to the directory where the simulation file is located 3 3 5 start_period Defines the first period integer to be simulated 3 3 6 periods Defines the number of periods integer to be simulated 3 3 7 random_seed Defines the starting point integer of the pseudo random generator This section is optional This can be useful if you want to have several runs of a simulation use the same random numbers 3 3 simulation 9 LIAM 2 User Guide Release 0 4 1 3 3 8 skip_shows If set to True makes all show functions do nothing This can speed up simulations which include many shows usually for debugging 10 Chapter 3 Model Definition CHAPTER FOUR PROCESSES The processes are the core of a model LIAM2 supports two kinds of processes assignments which change the value of a
7. to_give_birth not gender and age gt 15 and age lt 50 e Conditional expressions if condition expression_if_true expression_if_false example agegroup_civilstate if age lt 50 5 e paa las Y D y IE nc lage AONe Note that an if statement has always three arguments If you want to leave a variable unchanged if a condition is not met specify its value in the expression_if_false retire people set workstate 9 when aged 65 or more workstate if age gt 65 9 workstate You can nest if statements The example below retires men gender True over 64 and women whose age equals at least the parameter periodic global WEMRA Women Retirement Age workstate if gender if age gt 65 9 workstate if age gt WEMRA 9 workstate mathematical functions e log expr natural logarithm In e exp expr exponential e abs expr absolute value e round expr n returns the rounded value of expr to specified n number of digits after the decimal point If n is not specified O is used e trunc expr returns the truncated value by dropping the decimal part of expr as an integer e clip x a b returns a if x lt a X ifa lt x lt b b if x gt b min x a max x a the minimum or maximum of x and a aggregate functions grpcount condition count the objects in the entity If filter is given only count the ones satisfying the filter e grpsum
8. 0 scale grpstd errsal Panoinn G 20 4 5 2 Stochastic changes probabilistic simulation choice Monte Carlo or probabilistic simulation is a method for iteratively evaluating a deterministic model using sets of random numbers as inputs In microsimulation the technique is used to simulate changes of state dependent variables Take the simplest example suppose that we have an exogenous probability of an event happening P x 1 or not P x 0 Then draw a random number u from an uniform 0 1 distribution If for individual i ui lt p 1 then xi 1 If not then xi 0 The expected occurrences of x after say 100 runs is then P x 1 100 and the expected value is 1xP 1 0xP 0 P 1 This type of simulation hinges on the confrontation between a random variable and an exogenous probability In the current version of LIAM 2 it is not possible to combine a choice with alignment In LIAM 2 such a probabilistic simulation is called a choice process Suppose i 1 n choice options each with a probability prob_option_i The choice process then has the following form Coode Torrion l clon 2 coo Dir Loma PreobRop tonel romo plo OO MO pS Note that both lists of options and pertaining probabilities are between s Also the variable containing the options can be of any numeric type A simple example of a choice process is the simulation of the gender of newborns 51 males and 49 females as such gender choice
9. 7 candidates from the rest of the sample The leave command works the other way around those who match the condition in that statement are a priori excluded from the event happening The take and leave are absolute conditions which mean that the individuals meeting these conditions will always take or never Jeave experience the event Their soft counterparts can easily be included by manipulating the score of individuals If this score is set to a strong positive or negative number then the individual will a priori have a high of low probability of the event happening These soft take and soft leave s will implement a priority order in the sample of individuals but will not under all circumstances conditionally include or exclude Note that even if the score is 1 an item can be selected by the alignment procedure This happens when there are not enough candidates selected by the score to meet the alignment needs The below application describes the process of being or remaining a wage earner or employee It illustrates a soft leave by setting the a priori score variable wage_earner_score to 1 This makes sure that the a priori selection probability for those not specified in the process is very low but not zero as in the case of leave conditions Next come three sub processes setting a couple of common conditions in the form of local temporary vari ables These three sub processes are followed by six subsequent if conditions
10. and sets it to 1 if the value of the temporary variable ischild is True and to 2 is not e after2 creates a temporary variable after2 and sets it to 1 if the value age lt 18 is True and to 2 if not It is clear that afterl after2 since the age has been changed and ischild has not been updated since 3 2 4 processes Here you define the processes you will need in the model More detail see Processes 3 3 simulation The simulation block includes the location of the datasets input output the number of periods and the start period It sets what processes defined in the entities block are simulated since some can be omitted and the order in which this is done Suppose that we have a model that starts in 2002 and has to simulate for 10 periods Furthermore suppose that we have two object or entities individuals and households The model starts by some initial processes grouped under the header init that precede the actual prospective simulation of the model and that only apply to the observed dataset in 2002 These initial simulations can pertain to the level of the individual or the household Use the init block to calculate variables for the starting period The prospective part of the model starts by a number of sub processes setting the household size and composition Next two processes apply on the level of the individual changing the age and agegroup Finally mortality and fertility are simulated Seeing that this chan
11. commands you can type any expression that is allowed in the simulation file and have the result directly Show is implicit for all operations examples gt gt gt grpavg age 53 MSiS19gl5 gt gt gt groupby age 20 gender expr grpcount inwork 4 7 Interactive console 27 LIAM 2 User Guide Release 0 4 1 gender False True age 20 0 14 18 il Sly 496 2 SiS 258 3 40 102 4 0 0 5 0 0 total 689 874 tortal Be 813 BH 142 SS 4 7 1 breakpoint breakpoint temporarily stops execution of the simulation and launch the interactive console There are two additional commands available in the interactive console when you reach it through a breakpoint step to execute only the next process and resume to resume normal execution general format breakpoint period the period argument is optional and if given will make the breakpoint interrupt the simulation only for that period example marriage in_couple MARRII breakpoint 2002 ED or COHAB 28 Chapter 4 Processes CHAPTER FIVE LINKS Entities can be linked with each other or with other entities for example individuals belong to households and mothers are linked to their children while partners are interlinked as well A typical link has the following form name type lt type gt target lt entity gt field lt na
12. e fixed non assignment actions in interactive console csv remove e fixed error_var argument to cont_regr clip_regr and log_regr 8 2 4 Version 0 2 1 Released on 2011 06 20 Miscellaneous improvements e simplified and cleaned up the demonstration models e improved the error message when a link points to an unknown entity e the evaluator creates fewer internal temporary variables in some cases Fixes e added log and exp to the list of available functions they were already implemented but not usable because of that e fixed log_regr cont_regr and clip_regr which were comparing their result with 0 5 like logit_regr when there is no alignment e fixed new function which created individuals correctly but in some cases returned values which did not correspond to the ids of the newly created individuals due to a bug in numpy 8 2 5 Version 0 2 Released on 2011 06 07 New features added support for retrospective simulation ie simulating periods for which we already have some data at the start of each simulated period if there is any data in the input file for that period it is merged with the result of the last simulated period If there is any conflict the data in the input file has priority added clone function which creates new individuals by copying all fields from their origin individuals except for the fields which are given a value manually added breakpoint function
13. expr filter condition sum the expression e grpavg expr filter condition average e grpstd expr standard deviation e grpmax expr grpmin expr max or min e grpmedian expr median 14 Chapter 4 Processes LIAM 2 User Guide Release 0 4 1 e grpgini expr filter condition gini grpsum sums any expression over all the individuals of the current entity For example grpsum earnings will produce the sum of the earnings of all persons in the sample The expression grpsum nch0_11 will result in the total number of children 0 to 11 in the sample grpcount counts the number of individuals in the current entity optionally satisfying a boolean condition For example grpcount gender will produce the total number of men in the sample Contrary to grpsum the grpcount does not require an argument grpcount will return the total number of individuals in the sample Note that grpsum and grpcount are exactly equivalent if their only argument is a boolean variable eg grp count ISWIDOW grpsum ISWIDOW example macros WIDOW civilstate processes cnt_widows show grpcount WIDOW link functions one2many links e countlink link filter sumlink link expr filter avglink link expr filter e minlink maxlink link expr filter example entities household fields period and id are implicit nb_persons type int initialdata false links persons ty
14. in the csv file you can simply omit this section The field types will be automatically detected fields period and id are implicit lt fieldl_name gt lt fieldl_type gt lt field2_name gt lt field2_type gt if you want to keep your csv files intact but use different 33 LIAM 2 User Guide Release 0 4 1 names in your simulation than in the csv files you can specify name changes her oldnames lt fieldX_newname gt lt fieldX_oldname gt lt fieldY_newname gt lt fieldY oldname gt if you want to invert the value of some boolean fields True gt False and False gt True add them to the invert list below verte iret E boolean tlields to 2nvere lt entity2_name gt Most elements of this description file are optional The only required elements are output and entities If an element is not specified it uses the following default value e if path is omitted it defaults to a file named after the entity in the same directory than the description file ie local_path name_of_the_entity csv e if the fields section is omitted all columns of the csv file will be imported and their type will be detected automatically e if compression is omitted the output will not be compressed Note that if an entity section is entirely empty you need to use the special code p example output normal h5 globals periodic
15. separating the various behavioural equations to the sub sample they pertain to The first three sub conditions pertain to women and describe the probability of being a wage earner from in work and employee previous year 1 from in work but not employee previous year 2 and from not in work previous year 3 The conditions 4 to 6 describe the same transitions but for women wage_earner_process wage_earner_score al lag_public lag workstate 2 or workstate 3 inwork workstate gt 0 and workstate lt 5 lag_inwork lag workstate gt 0 and workstate lt 5 men_inwork gender and age gt 15 and age lt 65 and inwork 4 5 Expressions 19 LIAM 2 User Guide Release 0 4 1 MEN Probability of being employee from in work and employee previous year wage_earner_scor if men_inwork and lag workstate 1 or lag workstate 2 logit_score 0 0346714 age 0 9037688 x collar 1 OW 23600162 gt eivilstate 3 r 2110479 wage_earner_score Probability of becoming employee from in work but not employee previous year wage_earner_scor if men_inwork and lag workstate 1 and lag workstate 2 logit_score 0 1846511 age 0 001445 age x xx 2 0 4045586 collar 1 0 913027 wage_earner_score Probability of becoming employee from not in work previous year wage_earner_scor if men_inwork and lag w
16. those who are not working obviously cannot be working as a wage earner The input files of the alignment process are al_p_wage_earner_m csv and al_p_wage_earner_f csv The alignment process sets the Boolean wage earner and uses as input the scores simulated previously and the information it takes from the alignment files No take or leave conditions are specified in this case Note that the population to align is the population specified in the first condition here age gt 15 and age lt 65 and inwork and not the whole population 20 Chapter 4 Processes LIAM 2 User Guide Release 0 4 1 4 5 4 Lifecycle functions new new creates items initiated from another item of the same entity eg a women gives birth or another entity eg a marriage creates a new houshold generic format new entity_name filter expr xset initial values of a selection of variablesx The first parameter defines the entity in which the item will be created eg person household Then the filter argument specifies which items of the current entity will serve as the origin for the new items for persons that would translate to who is giving birth but the function can of course be used for any kind of entity Any subsequent argument specifies values for fields of the new individuals Any field which is not specified there will receive the missing value corresponding to the type of the field nan
17. tools to inspect the data You can display information during the simulation using show or groupby You can dump data to csv file for further study If you run LIAM 2 in interactive mode you can type in output functions in the console to inspect the data 4 6 1 show show evaluates expressions and prints the result to the console show expr1 expr2 expr3 example 1 show grpcount age gt 18 show grpcount not dead grpavg age filter not dead The first process will print out the number of persons of age 18 and older in the dataset The second one displays the number of living people and their average age example 2 showl Ueountes A EPEOUN TEE Average age grpavg age Age std dev grpstd age gives Count 19944 Average age 42 7496991576 Age std dev 21 9815913417 Note that you can use the special character n to display the rest of the result on the next line example 3 showiUeounts A Ep E OUEN nAverage age grpavg age nAge std dev grpstd age gives Count 19944 Average age 42 7496991576 Age std dev 21 9815913417 4 6 2 csv The csv function writes values to a csv file csv expr1 expr2 expr3 suffix file_suffix fname filename mode w The suffix fname and mode are optional arguments e fname allows defining the exact file names used You can optionally use entity and period to cus tomi
18. variable predictor using an expression and actions which don t but have other effects For each entity for example household and person the block of processes starts with the header pro cesses Each process then starts at a new line with an indentation of four spaces 4 1 Assignments Assignments have the following general format processes variablel_name xpressionl variable2_name xpression2 The variable_name will usually be one of the variables defined in the fields block of the entity but as we will see later it is not always necessary In this case the name of the process equals the name of the endogenous variable Process names have to be unique for each entity See the section about procedures if you need to have several processes which modify the same variable To run the processes they have to be specified in the processes section of the simulation block of the file This explains why the process names have to be unique for each entity example entities person fields ages me processes age age 1 simulation processes person age 4 2 Temporary variables All fields declared in the fields section of the entity are stored in the output file Often you need a variable only to store an intermediate result during the computation of another variable In LIAM2 you can create a temporary variable at any point in the simulation by simply havi
19. which launches the interactive console during a simulation Two more console commands are available in that mode s tep to execute the next process r esume to resume normal execution The breakpoint function takes an optional period argument so that it triggers only for that specific period added tsum function which sums an expression over the whole lifetime of individuals It returns an integer when summing integer or boolean expressions and a float for float expressions 42 Chapter 8 Appendix LIAM 2 User Guide Release 0 4 1 e implemented using the value of a periodic global at a specific period That period can be either a constant eg MINR 2005 or an expression eg MINR period 10 or MINR year_of_birth 20 e added trunc function which takes a float expression and returns an int dropping everything after the decimal point Miscellaneous improvements e made integer division int int return floats eg 1 2 0 5 instead of 0 e processes which do not return any value csv and show do not need to be named anymore when they are inside of a procedure e the array used to run the first period is constructed by merging the individuals present in all previous periods e print timing for sub processes in procedures This is quite verbose but makes debugging performance problems regressions easier e made error messages more understandable in some cases e manua
20. 2011 12 02 39 LIAM 2 User Guide Release 0 4 1 Miscellaneous improvements validate both import and simulation files i e detect bad structure and invalid and missing keywords improved error messages both during import and the simulation by stripping any information that is not useful to the user For some messages we only have a line number and column left this is not ideal but should be better than before The technical details are written to a file error log instead improved incoherent alignment data error message when loading an alignment file by changing the word ing and adding the path of the file with the error reorganised bundle files so that there is no confusion between directories for Notepad and those of liam2 tweaked Notepad configuration added explore command as F7 removed more unnecessary features Fixes disallowed using one2many links like many2one it was never intended this was and produced wrong re sults fixed groupby with a scalar expression it does not make much sense but it is better to return the result than to fail re enabled the code to show the expressions containing errors where possible in addition to the error mes sage This was accidentally removed in a previous version fixed usage to include the explore command 8 2 2 Version 0 4 0 Released on 2011 11 25 New features added grpgini function added grpmedian function implemente
21. 26 Chapter 4 Processes LIAM 2 User Guide Release 0 4 1 T asa Gri 1355 8 36 S57 HAG TSO Ea 27 total 10002 9942 19944 example show groupby inwork gender gives gender False True inwork total kalee e170 5567 11757 meve 3692 4355 gley total 10002 9942 19944 example show groupby inwork gender percent True gives gender False True inwork Total Balse 30 94 28 01 53 95 True 19 21 21 84 Al e05 cotal 50 15 49 85 100 00 example groupby workstate gender expr grpavg age gives the average age by workstate and gender gender False True workstate toral 1 Aare 219 40 53 40 88 2 40 28 44 51 41 88 3 832 To TO 3502 4 72 48 ZEN T238 5 42 35 46 56 43 48 1 AX 157 42 38 42 53 4 7 Interactive console LIAM 2 features an interactive console which allows you to interactively explore the state of the memory either during or after a simulation completed ce s99 1 You can reach it in two ways You can either pass as the last argument when running the executable in which case the interactive console will launch after the whole simulation is over The alternative is to use breakpoints in your simulation to interrupt the simulation at a specific point see below Type help in the console for the list of available commands In addition to those
22. True False 0 51 0 49 The code below illustrates a more complex example of a choice process called collar process Suppose we want to simulate the work status collar 1 blue collar worker white collar worker for all working individuals We however have knowledge one s level of education education_level 2 3 4 The process collar_process has collar as the key endogenous variable and has four sub processes The first sub process defines a local variable filter bw which will be used to separate those that the procedure should apply to These are all those that do not have a value for collar and who are working or who are in education or unemployed which means that they potentially could work 16 Chapter 4 Processes LIAM 2 User Guide Release 0 4 1 The next three collar sub processes simulate whether one is a white or blue collar worker depending on the level of education If one meets the above filter_bw and has the lowest educational attainment level then one has a probability of about 84 men and 69 women of being a blue collar worker If one has education_level equal to 3 the probability of being a blue collar worker is of course lower 64 for men and 31 for women and the probability of becoming a blue collar worker is lowest 8 and 4 respectively for those having the highest educational attainment level collar_process working in education unemployed or other inacti
23. comes from the members in a household e avglink eg avglink persons age gives the average age of the members in a household e minlink maxlink eg minlink persons age gives the age of the youngest member of the household example entities household fields bi clas lelecias date aM RS 8 link from a household to its members persons type one2many target person field household_id processes num_children countlink persons age lt 18 30 Chapter 5 Links LIAM 2 User Guide Release 0 4 1 person fields age int household_id int Es link form a person to his her household household type many2one target household field household_id processes num_kids_in_hh household num_children The num_children process once called will compute the number of persons aged 17 or less in each household and store the result in the num_children field of the household Afterwards that variable can be used like any other variable for example through a many2one link like in the num_kids_in_hh process This process computes for each person the number of children in the household of that person Note that the variable num_kids_in_hh could also have been simulated by just one process on the person level by using num_kids_in_hh household get countlink persons age lt 18 5 2 one2many 31 LIAM 2 User Guide Release 0 4 1 32
24. could write them at that point csv period average income fname avg_income csv When you use the csv function in combination with at least one table expressions see dump and groupby functions below the results are appended below each other csv table_expr1 and here goes another table table_expr2 fname tables csv Will produce a file with a layout like this table 1 value at row 1 col 1 a E COMEN ROWAN MECOM TOIME sd COJLN and here goes another table table 2 value at row 1 col 1 a col row NM Col 1 Paar col N You can also output several rows with a single command by enclosing values between brackets csv rowlvaluel rowlvalueN rowNvaluel rowNvalueN fname several_rows csv example ose thats ist Ta neader with several lines fname person_age_aggregates csv Will produce a file with a layout like this this is a header with several lines 4 6 Output 25 LIAM 2 User Guide Release 0 4 1 4 6 3 dump dump produces a table with the expressions given as argument evaluated over many possibly all individuals of the dataset general format dump exprl expr2 filter filterexpression missing value header True If no expression is given all fields of the current entity will be dumped including temporary variables available at that point
25. d filter argument in grpsum implemented N dimensional alignment alignment can be done on more than two variables dimensions in the same file added keyword arguments to csv fname to allow defining the exact name of the csv file mode to allow appending to a csv file instead of overwriting it reworked csv function to support several arguments like show It also supports non table arguments added skip_shows simulation option to make all show functions do nothing allowed expressions in addition to variable names in alignment files added keyword arguments to dump missing to convert nans into the given value header to determine whether column names should be in the dump or not improved import functionality 40 Chapter 8 Appendix LIAM 2 User Guide Release 0 4 1 compression is now configurable any csv file can be transposed not just globals globals fields can be selected renamed and inverted like in normal entities e added explore command to the main executable to launch the interactive console on a completed simula tion without re simulating it Miscellaneous improvements e expressions do not need to be quoted anymore reverted init to old semantic it happens in start_period 1 so that lag variable_set_in_init works even for the first period purge all local variables after each process to lower memory usage allowed th
26. d process is a procedure which consists of two sub processes If it is executed subprocess_31 will be executed and then subprocess_32 Contrary to normal processes sub processes processes inside procedures names do not need to be unique In the above example it is possible for subprocess_31 and subprocess_32 to have the same name and hence simulate the same variable Procedure names process_name3 does not directly refer to a specific endogenous variable example processes ageing age age 2 in our world people age strangely 12 Chapter 4 Processes LIAM 2 User Guide Release 0 4 1 age age 1 SVAGCOLOUDs trivia ass 10 140 The processes on age and agegroup are grouped in ageing In the simulation block you specify the ageing process if you want to update age and agegroup By using procedures you can actually make building blocks or modules in the model 4 4 1 Temporary variables Temporary variables defined computed within a procedure are local to that procedure they are only valid within that procedure If you want to pass variables between procedures you have to define them in the fields section bad example person fields ages late processes ageing ages age i aisodlels age gt 150 isold is a local variable rejuvenation age age i backfromoldage isold and age lt 150 WRONG In this example isold and backfr
27. dividuals were present in a past period but not in the current period e fixed many2one links returning seemingly random values instead of missing when they were pointing to an individual which was not present anymore usually because the individual was dead e fixed min max functions fields which are not given an explicit value in new are initialised to missing instead of 0 8 2 Change log 43 LIAM 2 User Guide Release 0 4 1 e the result of the new function which returns the id of the newly created individuals is now 1 instead of 0 for parents which are not in the filter e fixed some expressions crashing when used within a lag e fixed the progress bar to display correctly even when there are only very few iterations 8 2 6 Version 0 1 First semi public release released on 2011 02 24 44 Chapter 8 Appendix aggregate functions 14 align 19 alignment 17 avglink 15 breakpoint 28 bundle 2 choice 16 clone 22 countlink 15 csv 24 dump 25 duration 15 expressions 13 groupby 26 hdf5 39 import 31 interactive console 27 lag 15 leave 19 lifecycle functions 20 links 28 logit 17 logit_regr 17 logit_score 18 many2one 29 matching 22 mathematical functions 14 maxlink 15 minlink 15 new 21 normal 16 notepad 2 one2many 30 processes 10 python 39 randint 16 INDEX random 16 remove 22 show 24 simple express
28. e result of new to not be stored in a variable allowed using temporary variables in matching function added a tolerance of 1e 6 to the sum of choice s probabilities to be equal 1 0 added explicit message about alignment over and underflows nicer display for small lt 5ms and large gt 1 hour timings improved error message on missing parenthesis around operands of boolean operators improved error message on duplicate fields improved error message when a variable which is not computed yet is used added more information to the console log number of individuals at the start and end of each period more stats at the end of the simulation excluded unused components in the executable to make it smaller Fixes fixed logit_regr align float fixed grpavg bool filter cond fixed groupby a b c expr grpsum d percent True fixed having several grpavg with a filter argument in the same expression fixed calling the main executable without argument simply display usage fixed dump with some kind of aggregate values in combination with a filter fixed void data source 8 2 3 Version 0 3 0 Released on 2011 06 29 New features e added ability to import csv files directly with the main executable 8 2 Change log 41 LIAM 2 User Guide Release 0 4 1 Miscellaneous improvements e made periodic globals optional e improved a few sections of the documentation Fixes
29. eing or stochastic probability lt 1 such as the chance of dying marrying giving birth or moving within a given time period The aim of such simulations is to give insight about both the overall aggregate change of some characteristics and importantly the way these changes are distributed in the population that is being modelled 1 4 Credits LIAM2 is being developed at the Federal Planning Bureau Belgium with funding and testing by CEPS INSTEAD Luxembourg and IGSS Luxembourg and funding from the European Community It is the spiritual successor of LIAM 1 developed by Cathal O Donoghue LIAM 2 User Guide Release 0 4 1 More formally it is part of the MiDaL project supported by the European Community Programme for Em ployment and Social Solidarity PROGRESS 2007 2013 under the Grant VS 2009 0569 Abstract Project PROGRESS MiDaL deliverable Work Package A 2 Chapter 1 Introduction CHAPTER TWO ENVIRONMENT 2 1 LIAM 2 bundle The bundle includes e The executable e A text editor Notepad pre configured to work with LIAM2 models Notepad is a free and open source text editor that is available at http sourceforge net projects notepad plus We pre configured it so that you can import csv files and run your models directly from within the editor by simply pressing F5 or F6 respectively See below for more information e The documentation in html pdf and chm windows help format
30. elds period and id are implicit Eres Ode dead bool gender bool 1 single 2 married 3 cohabitant 4 divorced 5 widowed civilstate int partner Lee mE earnings float 6 Chapter 3 Model Definition LIAM 2 User Guide Release 0 4 1 This example defines the entity person Each person has an age gender is dead or not has a civil state possibly a partner We use the field civilstate to store the marital status as a switch of values By default all declared fields are supposed to be present in the input file because they are observed or computed elsewhere and their value can be found in the supplied data set The value for all declared fields will also be stored for each period in the output file However in practice there are often some fields which are not present in the input file They will need to be calculated later by the model and you need to tell LIAM2 that the field is missing by using initialdata false in the definition for that field see the agegroup variable in the example below example entities person fields agez int agegroup type int initialdata false Field names must be unique per entity 1 e several entities may have a field with the same name 3 2 2 links Entities can be linked with each other or with other entities for example individuals belong to households and mothers are linked to their children while partners are interlinked as w
31. ell A typical link has the following form name type lt type gt target lt entity gt field lt name of link field gt LIAM 2 uses integer fields to establish links between entities Those integer fields contain the id number of the linked individual LIAM 2 allows two types of links many2one and one2many More detail see Links 3 2 3 macros Macros are a way to make the code easier to read and maintain They are defined on the entity level Macros are re evaluated wherever they appear Use capital letters to define macros example entities person fields age int macros ISCHILD age lt 18 processes test_macros ES cda SAS betorsts 1 1isentla Ly 2 before2 if 1SCALLD 1 2 beforel before2 age age 1 arteria a scale il 2 arenas alse CSCHILD IL 2 afterl after2 simulation 3 2 entities 7 LIAM 2 User Guide Release 0 4 1 processes person test_macros The above example does e ischild creates a temporary variable ischild and sets it to True if the age of the person is under 18 and to False if not e beforel creates a temporary variable before and sets it to if the value of the temporary variable ischild is True and to 2 if not e before2 creates a temporary variable before2 and sets it to 1 if the value age lt 18 is True and to 2 if not e age the age is changed e afterl creates a temporary variable after
32. ever it is convenient to use multiple logits with the same alignment process In this case using a logit_score instead of logit_regr will result in the logit returning intermediate scores that for all conditions together are the inputs of the alignment process A typical behavioural equation with alignment has the following syntax name_process initialise the score to 1 score _ variable 1 first condition gCora verilcioleos le eoinclieaoim l logit_score logit_expr_1 score variable second condition SESCObCmyaGdalolle ala Comeukeakomuay logit_score logit_expr_2 score _variable i pos oher Cordun Erons do alignment based on the scores calculated above name_endogenous_variable Lt cond te Ton if gender align score_variable take conditions leave conditions fname filename_m csv align score_variable take conditions leave conditions 18 Chapter 4 Processes LIAM 2 User Guide Release 0 4 1 fname filename_f csv False The equation needs to simulate the variable name_endogenous_variable It starts however by creating a score that reflects the event risk p i In a first sub process a variable name_score is set equal to 1 because this makes it highly unlikely that the event will happen to those not included in the conditions for which the logit is applied Next subject to conditions condition_1 and condition_2 this score is simula
33. ges the numbers of individuals in households the process establishing the household size and composition is again used example simulation ali lalic g household household composition person agegroup processes household household_composition person age agegroup dead_procedure birth household household_composition input path liam2 file base h5 8 Chapter 3 Model Definition LIAM 2 User Guide Release 0 4 1 Output path liam2 file simulation h5 start_period 2002 periods 10 random_seed 5235 optional 3 3 1 processes This block defines which processes are executed and in what order They will be executed for each period starting from start_period for periods times Since processes are defined on a specific entities they change the values of items of that entity you have to specify the entity before each list of process Note that you can execute the same process more than once during a simulation and that you can alternate between entities in the simulation of a period In the example you see that after dead_procedure and birth the household_composition procedure is re executed 3 3 2 init Every process specified here is only executed in the last period before start period start_period 1 You can use it to calculate initialise variables derived from observed data This section is optional it can be entirely omitted 3 3 3 input The initial
34. h Also in that case the partner identification code is erased All other procedures describing the heritage process should be included here Finally the remove command is called to removes the dead from the simulation dataset 4 5 5 Matching functions matching aka Marriage market matches individuals from set 1 with individuals from set 2 For each individual in set 1 following a particular order given by the expression in the orderby argument the function computes the score of all unmatched individuals in set 2 and take the best scoring one You have to specify the boolean filters which provide the two sets to match setl filter and set2filter the criterion to decide in which order the individuals of the first set are matched and the expression that will be used to assign a score to each individual of the second set given a particular individual in set 1 In the score expression the fields of the set 1 individual can be used normally and the fields of its possible partners can be used by prefixing them by other 22 Chapter 4 Processes LIAM 2 User Guide Release 0 4 1 generic setup matching setlfilter boolean_expr set2filter boolean_expr orderby difficult_match score coefl x fieldl coef2 other field2 The generic setup of the marriage market is simple one needs to have selected those individuals who are to be coupled to_couple true Furthermore one needs to have a va
35. h simulation on the contrary a clone with no fields mentioned will result in a new item that is an exact copy of the origin except for its id number which is always set automatically example make_twins clone filter new_born and is_twin gender choice True False 0 51 0 49 remove remove removes items from an entity dataset With this command you can remove obsolete items eg dead persons empty households thereby ensuring they are not simulated anymore This will also save some memory and in some cases improve simulation speed The procedure below simulates whether an individual survives or not and what happens in the latter case dead_procedure decide who dies dead if gender logit_regr 0 0 align al_p_dead_m csv logit_regr 0 0 align al_p_dead_f csv change the civilstate of the suriving partner cCivilstate if partner dead 5 civilstate break the link to the dead partner partner_id if partner dead 1 partner_id remove the dead remove dead The first sub procedure dead simulates whether an individual is scheduled for death using again only a logistic stochastic variable and the age gender specific alignment process Next some links are updated for the surviving partner The sub procedure civilstate puts the variable of that name equal to 5 which means that one is a widow er for those individuals whose partner has been scheduled for deat
36. ions 13 sumlink 15 take 19 tavg 15 temporal functions 15 tsum 15 uniform 16 value_for_period 15 yaml 39 45
37. lbox which is not tied to a particular model By making it available for free our hope is to greatly reduce the development costs in terms of both time and money of microsimulation models The toolbox is made as generic as possible so that it can be used to develop almost any microsimulation model as long as it use cross sectional ageing ie all individuals are simulated at the same time for one period then for the next period etc You can find the latest version of LIAM2 and this documentation at http liam2 plan be 1 2 About this guide This guide will help you develop dynamic microsimulation models using LIAM 2 Please note that it describes version 0 4 of LIAM 2 but both the software package and this manual are very much work in progress and are therefore subject to change including in the syntax described in this manual for defining models 1 3 Microsimulation Microsimulation is as defined by the International Microsimulation Association a modelling technique that operates at the level of individual units such as persons households vehicles or firms Each unit has a set of associated attributes e g each person in the model has an associated age sex marital and employment status At each time step a set of rules intended to represent individual preferences and tendencies are applied to these units leading to simulated changes in state and possibly behaviour These rules may be deterministic probability 1 such as ag
38. ll df Federal Planning Bureau Economic analyses and forecasts LIAM 2 User Guide Release 0 4 1 G Bryon G Dekkers G de Menten December 02 2011 1 Introduction 11 gt Abut LIAM oscar ee Y 12 Aboutthis guide c e e404 idee vs 1 3 Microsimulation 14 Credits 2 ee ba ek eee SR 2 Environment 2 1 LIAM 2 bundle oo oc oe 2 2 Getting Started 2 3 Using your own data 3 Model Definition Sello SlObAaIS 0 ea Sue sok a 3 3 2 EMS 3 eee Sisk 244484 444 3 3 simulation gt s eos saca e me e 4 Processes 4 1 Assignments 5 64255 0 45 8 AS ACHOS ye 2 ote eG Re a oS 4 4 Procedures 5 4644 Sed we ee AS EXpressions concisa Faw o s es 46 Output 2 66 shi e eee o 4 7 Interactive console 42 Temporary variables 5 Links Sil MANYZOMS cms caras HZ ONEMAN eii 6 Importing data Gl data Mes oso aa e 6 2 description file se lt 084654844585 6 3 importing the data 7 Indices and tables 8 Appendix 8 1 Technical choices aooaa aa 8 2 Changelog s eers e eii a a Index CONTENTS j a j E E CHAPTER ONE INTRODUCTION LIAM 2 is a tool to develop different kinds of microsimulation models 1 1 About LIAM2 The goal of the project is to let modellers concentrate on what is strictly specific to their model without having to worry about the technical details This is achieved by providing a generic microsimulation too
39. lly flush the console output every time we write to it not only within the interactive console as some environments namely when using the notepad bundle do not flush the buffer themselves e disable compression of the output simulation file as it hurts performance quite a bit the simulation time can be increased by more than 60 Previously it was using the same compression settings as the input file e allowed align to work on a constant eg align 0 0 fname al_p_dead_m csv e made the tavg function work with boolean and float expressions in addition to integer expressions e allowed links to be used in expression given in the new function to initialise the fields of the new individ uals e using __parent__ in the new function is no longer necessary e made the init section optional it was never intended to be mandatory e added progress bar for copying table optimised some parts for speed making the whole simulation roughly as fast as 0 1 even though more work is done Fixes e fixed tavg function the result was wrong because the number of values used in the division was one less than it should it yielded random values when some individuals were present in a past period but not in the current period e fixed duration function it crashed when a past period contained no individuals it yielded random values when some in
40. me of link field gt LIAM 2 uses integer fields to establish the link between entities Those integer fields contain the id number of the linked individual LIAM 2 allows two types of links many2one and one2many 5 1 many2one A many2one link the item of the entity to one other item in the same eg a person to its mother or another entity eg a person to its household This allows the modeller to use information stored in the linked entities SIME aE LOS S person talla ages ala SPIN OM Came ko cites MON Sa ci Estima Leg Laia petoer tes Slate Es mother type many2one target person field mother_id father type many2one target person field father_id partner type many2one target person field partner_id processes age age 1 mother_age mother ag parents_income mother income father income To access a field of a linked individual possibly of the same entity you use link_name field_name For example the mother_age process uses the mother link to assign the age of the mother to the mother_age field If an individuals link does not point to anything eg a person has no known mother trying to use the link would yield the missing value eg for orphans mother age is 1 and parents_income is nan As another example the process below sets a variable to_separate to True if the variable separate is True for either the individual or his her partner 29
41. ng an assignment to an undeclared variable Their value will be discarded at the end of the period 11 LIAM 2 User Guide Release 0 4 1 example person fields period and id are implicit egies int agegroup int processes age age 1 agediv10 trunc age 10 agegroup agediv10 x 10 agegroup2 agedivl0 x 5 In this example agediv10 and agegroup2 are temporary variables In this particular case we could have bypassed the temporary variable but when a long expression occurs several times it is often cleaner and more efficient to express it and compute it only once by using a temporary variable 4 3 Actions Since actions don t return any value they do not need a variable to store that result and they only ever need the condensed form processes process_name action expression example processes remove_deads remove dead 4 4 Procedures A process can consist of sub processes in that case we call it a procedure Processes within a procedure are executed in the order they are declared Sub processes each start on a new line again with an indentation of four spaces and a So the general setup is processes variable_ name expression process_name2 action_expression process_name3 subprocess_31 expression subprocess_32 expression In this example there are three processes of which the first two do not have sub processes The thir
42. omoldage are local variables They can only be used in the procedure where they are defined Because we are trying to use the local variable sold in another procedure in this example LIAM 2 will refuse to run complaining that isold is not defined 4 4 2 Actions Actions inside procedures don t even need a process name example processes death_procedure dead age gt 150 remove dead 4 5 Expressions 4 5 1 Deterministic changes Let us start with a simple increment the following process increases the value of a variable by one each simulation period age age 1 The name of the process is age and what it does is increasing the variable age of each individual by one each period simple expressions e Arithmetic operators exponent modulo 4 5 Expressions 13 LIAM 2 User Guide Release 0 4 1 Note that an integer divided by an integer returns a float For example 1 2 will evaluate to 0 5 instead of 0 as in many programming languages If you are only interested in the integer part of that result for example if you know the result has no decimal part you can use the trunc function agegroup5 5 trunc age 5 e Comparison operators lt lt gt gt e Boolean operators and or not Note that you have to use parentheses when you mix boolean operators with other operators inwork workstate gt 0 and workstate lt 5
43. ork partner_id coupled to_couple and partner_id 1 newhousehold new household filter coupled and FEMALE start_period period region_id choice 0 1 2 3 Ocil O22 Des O64 household_id if coupled if MALE partner newhousehold newhousehold household_id The code above shows an application First of all individuals eligible for marriage are all those between 18 and 90 who are not a part of a couple the actual decision who is eligible is left to the alignment process Next for every women eligible to coupling the variable difficult_match is the difference between her age and the average age of men eligible for coupling In a third step for each eligible woman in turn following the order set by difficult_match all eligited men are assigned a score and the man with the best score is matched with that woman This score depends on his age his difference in age with the woman and the the work status of the potential partners In a next step a new household is created for women who have just become a part of a couple Their household number as well as their new partners is then updated to reflect their new household 4 5 Expressions 23 LIAM 2 User Guide Release 0 4 1 4 6 Output LIAM 2 produces simulation output in three ways First of all by default the simulated datasets are stored in hdf5 format These can be accessed at the end of the run You can use several
44. orkstate gt 4 loguiiemsiconre UNOS Su 2 wage e236 collar LO US ONE wage_earner_score WOMEN women_inwork not gender and age gt 15 and age lt 65 and inwork Probability of being employee from in work and employee previous year wage_earner_scor if women_inwork and lag workstate 1 or lag workstate 2 logit_score 1 179012 x age 0 0305389 x age xx2 0 0002454 x age xx3 OS SS lt Collar I a 7 91385 wage_earner_score Probability of becoming employee from in work but not employee previous year wage_earner_scor if women_inwork and lag workstate 1 and lag workstate 2 logit_score 0 8362935 age 0 0189809 age x2 0 O0VISZ 2 ace 3 0 7602 2 Collec 1 0 6092356 lt civalstare 3 a So IDS wage_earner_score Probability of becoming employee from not in work previous year wage_earner_scor if women_inwork and lag workstate gt 4 logit_score 0 6177936 age 0 0170716 age x2 0 0001582 agex 3 9 388913 wage_earner_score wage_earner if age gt 15 and age lt 65 and inwork if gender align wage_earner_score fname al_p_wage_earner_m csv align wage_earner_score fname al_p_wage_earner_f csv False The last sub procedure describes the alignment process Alignment is applied to individuals between the age of 15 and 65 who are in work The reason for this is that
45. otherwise each expression will be evaluated on the objects which satisfy the filter and produce a table The filter argument allows to evaluate the expressions only on the individuals which satisfy the filter Defaults to None evaluate on all individuals The missing argument can be used to transform nan values to another value Defaults to None no transforma tion The header argument determine whether column names should be in the dump or not Defaults to True example show dump age partner age gender filter id lt 10 gives akel age partner ag gender 0 21 il False 1 86 val False 2 16 True 3 L9 i False 4 al 2 False 5 89 92 True 6 59 61 True 7 65 29 False 8 38 35 True 9 48 52 True 4 6 4 groupby groupby aka pivot table group all individuals by their value for the given expressions and optionally compute an expression for each group If no expression is given it will compute the number of individuals in that group A filter can be specified to limit the individuals taken into account general format groupby expr1 expr2 expr3 expr expression filter filterexpression percent True example show groupby age 10 gender gives gender False True age 10 total 0 818 803 12i il 800 800 1600 2 1199 1197 2396 8 MOS SOS SLING 4 1697 1696 S895 5 1496 1491 2987 6 1191 Sia 2313
46. pe one2many target person field household_id processes household_composition nb_persons countlink persons nb_students countlink persons workstate 1 nch0_11 countlink persons age lt 12 nch12_15 countlink persons age gt 11 and age lt 16 temporal functions e lag value at previous period e value_for_period value at specific period e duration number of consecutive period the expression was True e tavg average of an expression since the individual was created tsum sum of an expression since the individual was created If an item did not exist at that period the returned value is 1 for a int field nan for a float or False for a boolean You can overide this behaviour when you specify the missing parameter example 4 5 Expressions 15 LIAM 2 User Guide Release 0 4 1 lag age missing 0 the age each person had last year 0 if newborn grpavg lag age average age that the current population had last year lag grpavg age average age of the population of last year value_for_period inwork and not male 2002 duration inwork and earnings gt 2000 duration educationlevel 4 tavg income random functions uniform random numbers with a uniform distribution e normal random numbers with a normal distribution e randint random integers between bounds example a random variable with the stdev derived from errsal normal loc 0
47. riable difficult_match which can be used to rank individuals according how easy they are to match Finally we need a function score matching potential partners In the first step and for those persons that are selected to be coupled potential partners are matched in the order set by difficult_match and each woman is matched with the potential partner with the highest matching score Once this is done both individuals become actual partners and the partner identification numbers are set so that the partner number of each person equals the identification number of the partner example marriage in_couple MARRIED or COHAB to_couple if age gt 18 and age lt 90 and not in couple if MALE logit_regr 0 0 align al_p_mmkt_m csv legaet See 10 07 eea ell joy ae ES False avg_age_males_to_couple grpavg age filter to_couple and MAL difficult_match if to_couple and FEMALE abs age avg_age_males_to_couple nan work workstate gt 0 and workstate lt 5 IPIALES RIO OC OUp iS matching setlfilter FEMALE set2filter MAL orderby difficult_match E leal score 0 4893 x other age 0 0131 other age x x 2 0 0001 x other age x 3 0 0467 x other age age 07018954 other tage age x 2 0 0003 x x other age age x 3 OVOS other work end not work 1 32386 not obher work and work 0 6549 x other work and w
48. s the household number of his her mother the child s father is set to the partner of the mother Finally some variables of the child are set to specific initial values the most important of these is its gender which is the result of a simple choice process new is not limited to items of the same entity the below procedure get a life makes sure that all those who are single when they are 24 year old leave their parents household for their own household The region of this household is created through a simple choice process example 2 get_a_life household_id if age 24 and civilstate 2 and civilstate 3 new household start_period period echlom id sclicuics 10 y 2 Sir Mel 0 2 Oo 0541 4 5 Expressions 21 LIAM 2 User Guide Release 0 4 1 household_id clone clone is very similar to new but is intended for cases where most or all variables describing the new individual should be copied from his its parent origin instead of being set to missing With clone you cannot specify what kind of entity you want to create as 1t is always the same as the origin item However similarly to new clone also allows fields to be specified manually by any expression evaluated on the parent origin Put differently a new with no fields mentioned will result in a new item of which the initial values of the fields are all set to missing and have to be filled throug
49. sv align wage_earner_score fname al_p_wage_earner_f csv False 4 5 Expressions 17 LIAM 2 User Guide Release 0 4 1 logit_regr Suppose that we have a logit regression that relates the probability of some event to explanatory variables X p i logit 1 BX EPSi This probability consists of a deterministic element as before completed by a stochastic element EPSi a log normally distributed random variable The condition for the event occurring is p i gt 0 5 Instead suppose that we want the proportional occurrences of the event to be equal to an overall proportion X In that case the variable p i sets the rank of individual i according to the risk that the relevant event will happen Then only the first X N individuals in the ranking will experience the event This process is known as alignment In case of one logit with one alignment process or a logit without alignment logit_regr will result in the logit returning a Boolean whether the event is simulated In this case the setup becomes single_align logit_regr lt logit arguments gt filter lt filter arguments gt align name csv example pan tAk to gaye loans logie zege One Orr filter FEMALE and age gt 15 and age lt 50 alicia culo orte CSV The above generic setup describes the situation where one logit pertains to one alignment process logit_score In many cases how
50. ted on the basis of estimated logits The specification logit_score results in the logit not returning a Boolean but instead a score Note that by specifying the endogenous variable name_score without any transformations under the ELSE con dition makes sure that the score variable is not manipulated by a sub process it does not pertain to align After this step the score is known and this is the input for the alignment process Suppose as is mostly the case that alignment data exists for men and women separately Then the alignment process starts by a if to gender Next comes the align command itself This takes the form align score_variable filter conditions take conditions leave conditions fname name csv The file name csv contains the alignment data A standard setup is that the file starts with the prefix al_ followed by the name of the endogenous variable and a suffix _m or _f depending on gender The optional take and leave commands forces inclusion or exclusion of objects with specified characteristics in the selection of the event The individuals with variables specified in the take command will a priori be selected for the event Suppose that the alignment specifies that 10 individuals should experience a certain event and that there are 3 individuals who meet the conditions specified in the take Then these 3 individuals will be selected a priori and the alignment process will select the remaining
51. ve lleer bws workstate gt 0 and workstate lt 7 DE workstate 10 and collar 0 collar if filter_bw and education_level 2 if gender caos l 21 Ws83505 AS Cones Ml Zi 10 686 0 3 collar collar if filter_bw and education _ level 3 if gender Gmonkes il 21 0 6427 i 0 6421 Choices i 21 WaSl278 L O sil278 o collar collar if filter_bw and education_level 4 if gender Chores lil 21 M O822 1 08221 Chaeace iL 21 0 0366 L 0396 collar 4 5 3 Stochastic changes II behavioural equations Logit logit_regr expr filter None align filename logit_regr expr filter None align percentage e Alignment align expr take take_filter leave leave_filter fname filename csv e Continuous expr normal 0 1 mult error_var cont_regr expr filter None mult 0 0 er ror_var None e Clipped continuous always positive clip_regr expr filter None mult 0 0 error_var None e Log continuous exponential of continuous log_regr expr filter None mult 0 0 error_var None example divorce logit_regr 0 6713593 household nch12_15 MOROS A ZEUS O Ups 0 1429621 agediff filter FEMALE and civilstate 2 align al_p_divorce csv wage_earner if age gt 15 and age lt 65 and inwork if MALE align wage_earner_score fname al_p_wage_earner_m c
52. velopment of LIAM 2 Python runs on Windows Linux Unix Mac OS X and has been ported to the Java and NET virtual machines Python is free to use even for commercial products because of its OSI approved open source license 8 1 2 HDF5 We store the used data in an hdf5 format http www hdfgroup org HDES is a data model library and file format for storing and managing data It supports an unlimited variety of data types and is designed for flexible and efficient I O and for high volume and complex data HDF5 is portable and is extensible allowing applications to evolve in their use of HDF5 The HDF5 Technology suite includes tools and applications for managing manipulating viewing and analyzing data in the HDFS format HDF is open source and the software is distributed at no cost Potential users can evaluate HDF without any financial investment Projects that adopt HDF are assured that the technology they rely on to manage their data is not dependent upon a proprietary format and binary only software that a company may dramatically increase the price of or decide to stop supporting altogether This allows us to handle important data sets 8 1 3 YAML The definition of the data and the model is done in the YAML language http www yaml org YAML YAML Ain t Markup Language What It Is YAML is a human friendly data serialization standard for all programming languages 8 2 Change log 8 2 1 Version 0 4 1 Released on
53. y objects and sub objects In a LIAM 2 model file all text following a is considered to be comments and is therefore ignored A LIAM 2 model has the following structure globals entities simulation 3 1 globals The globals are variables aka parameters that do not relate to any particular entity defined in the model They can be used in expressions across all entities Periodic globals can have a different value for each period For example the retirement age for women in Belgium has been gradually increasing from 61 in 1997 via 63 from 2003 onward up to 65 in 2009 A global variable WEMRA has therefore been included globals periodic WEMRA float Periodic globals can be used in any process They can be used in two ways like a normal variable they will evaluate to their value for the period being simulated for example workstate if age gt WEMRA 9 workstate This changes the workstate of the individual to retired 9 if the age is higher than the required retirement age in that year Another way to use them is to specify explicitly for which period you want them to be evaluated This is done by using GLOBALNAME period_expr periodexpr can be any expression yielding a valid period value Here are a few artificial examples workstate if age gt WEMRA 2010 9 workstate workstate if age gt WEMRA period 1 9 workstate workstate if age gt WEMRA
54. year_of_birth 60 9 workstate LIAM 2 User Guide Release 0 4 1 3 2 entities Each entity has a unique identifier and a set of attributes fields You can use different entities in one model You can define the interaction between members of the same entity eg between partners or among different entities eg a person and its household using links The processes section describe how the entities behave The order in which they are declared is not important In the simulation block you define if and when they have to be executed this allows to simulate processes of different entities in the order you want LIAM 2 declares the entities as follows entities entity namel fields fields definition TS links definition macros macros definition processes processes definition entity name2 As we use YAML as the description language indentation and the use of are important 3 2 1 fields The fields hold the information of each member in the entity That information is global in a run of the model Every process defined in that entity can use and change the value LIAM 2 handles three types of fields e bool boolean True or False e int integer e float real number There are two implicit fields that do not have to be defined e id the unique identifier of the item e period the current period in the run of the program example entities person fi
55. ze the name e suffix allows to set the name of csv file more easily If suffix is used the filename will be en tity _ period _ suffix csv 24 Chapter 4 Processes LIAM 2 User Guide Release 0 4 1 The default file name if neither fname nor suffix is used is entity _ period csv example csv grpavg income suffix income will create one file for each simulated period Assuming start_period is 2002 and periods is 2 it will create two files person_2002_income csv and person_2003_income csv with the average income of the population for period 2002 and 2003 respectively e mode allows appending mode a to a csv file instead of overwriting it mode w by default This allows you for example to store the value of some expression for all periods in the same file instead of one file per period by default example csv period grpavg income fname avg_income csv mode a Note that unless you erase overwrite the file one way or another between two runs of a simulation you will append the data of the current simulation to that of the previous one One way to do that automatically is to have a procedure in the init section without mode a to overwrite the file If you want that file to start empty you can do so this way csv fname avg_income csv If you want some headers in your file you
Download Pdf Manuals
Related Search