M
interpretation: rates that follow apply to males
examples: 
	death 1 M married
	marriage 1 M single
analogous keyword: F
single
interpretation: rates that follow apply to marital status single
examples: 
	birth 1 F single 0
	death 1 M single
	marriage 1 M single
analogous keywords: divorced married widowed [cohabiting]
input_file
interpretation: input files prefix--actual files will be name prefix.opop, prefix.omar
examples: 
	input_file test1
	input_file testruns/test1
explanation: in the first case, the starting population will be in file test1.opop and starting marriage file will be in file test1.omar (both in the current directory). In the second, the files have the same names but are in directory testruns (a subdirectory of the current directory).
analogous keyword: output_file
segments
interpretation: number of segments expected in the simulation. There isn't any limit on the number, but segment information must be provided for each segment.
examples: 
	segments 1
	segments 78
sex_ratio
interpretation: percentage of births that are male. This line assigns a value to prop_males
examples: 
	sex_ratio 0.5112
	sex_ratio 0.3333
default: 0.5112 (reassigned at the start of a new segment)
het_fert
interpretation: assign a value to hetfert, a 0(FALSE)/1(TRUE) flag It's reassigned at the start of the simulation and each segment (as are the analogous keywords which follow). Note that turning the flag on and off is not a good idea.
examples: 
	hetfert 1
	hetfert 0
default: 1
analogous keywords:hhmigration (migrants emigrate with their entire household, default 0) endogamy (marriage within groups, only, default 0)
bint
interpretation: assign a value to bint, a double precision value representing the minimum interval between births. Birth rates are then adjusted to to keep the intended value for the monthly probability of giving birth, however, when the bint is too large it's possible that some births will be lost. The bint is set to 0 at the start of each segment.
examples: 
	bint 9
	bint 24
duration
interpretation: Assign the integer following to the integer variable duration_of_segment, which is the duration of the current segment in months. It is set to 0 during the pre-segment tasks to trigger an error if the duration value isn't set in the segment assignments.
examples: 
	duration 10
	duration 1200
default value: 0 (this triggers an error message)
birthtarget
interpretation: Modify rates to get a number of births close to the value in target in the given segment. When targets are specified a crude calculation of the expected number of births in that segment (based on the rate structure and the parity and age distributions) is used to scale the birth rates by a fixed factor for all individuals in a particular group. The rates themselves are unchanged and can be used in later segments. Note that some feedback is possible while the simulation is running--the target can be read from a file created using the execute command.
examples: 
	birthtarget 2 100
	birthtarget 1 1500

caveat: it's not always possible to to achieve too high a target by increasing birth rates alone--the age/sex structure of the population may not be favorable.
death
interpretation: the rest of the line will represent the group, sex, and marital status of a set of agents in the population. The rate set that follows will apply to them and to all agents whose rate sets default to this set. The next lines will be interpreted as rate blocks for the rate set, until the rate line with upper boundary 1200 is read. Within the simulation the rates may be duration-specific. For
example, divorce rates are based on the "age" (duration) of the union.
examples: 
	death 1 M married
	death 1 F divorced
analogous keywords: marriage divorce
birth
interpretation: the rest of the line will represent the group, sex, marital status, and parity (which starts at 0) of a set of female agents in the population. The rate set that follows will apply to them and to all agents whose rate sets default to this set. The next lines will be interpreted as rate blocks for the rate set, until the rate line with upper boundary 1200 is read. The maximum parity is built into the program--the rate set for very large parity will default to the rate set for the maximum parity.
examples: 
	birth 1 F married 0
	birth 1 F married 14
transit
interpretation: the rest of the line will represent the starting group, sex, marital status, and destination group of a set of female agents in the population. The rate set that follows will apply to them only--there isn't any default by group or sex for migration rates. The next lines will be interpreted as rate blocks for the rate set, until the rate line with upper boundary 1200 is read. There is no need for a complete set of migration rates, allowing this sort of rate to model general status transitions. The maximum number of groups is set in the easy-to-change program variable MAXGROUPS--transitions to a group higher than this value are not permitted.
examples: 
	transit 1 F married 2
	transit 3 M single 2
explanation: The first example gives the migration rates for group 1 married women who are migrating to group 2; while the second applies to group 3 single men who migrate to group 2.
include
interpretation: read the file that follows as though it's contents were spliced into the current file from that point on.
examples: 
	include rates.segment1
	include mortality.seg4
execute
interpretation: interpret the rest of the line as a string to be passed to the UNIX "system command." Control is transferred to the shell and reading doesn't continue until the command is executed and returns. Commands that produce screen output will place their results at this point in the output stream. Commands that generate ratefiles will generate the file before reading the next line (which can be a command to include that file, as above)
example: 
	execute ls
	execute generate_rates 1 5 0 >mortality.seg4
	execute sleep 10
	execute date
	execute echo this section isn't very clear
explanation: ls and date are Unix commands and the output will appear on the screen. sleep 10 will pause for 10 seconds, and the echo command will print out the disclaimer. If the line including generate_rates is a correct command line (and generates rates in the proper form for socsim), the results of the command will be in file mmortality.seg4 and eligible for inclusion by the next line.
run
interpretation: run the next program segment. This command should only be in the "highest" level file, i.e., in the file that is named on the command line. This top-level file is bookmarked at the next reading position (so reading can resume at the end of the segment), the rate file is closed, and the segment processing begins.
example: 
	run

Settings to support inherited component of heterogeneous fertility

It's useful to have a mechanism that allows the daughters of large families to be more likely to have large families themselves. Alphas and betas are used in pairs (.1/1.05, .2/1.10,.4/1.15, etc). The values default to those that are there, effectively, when there is only the heterogeneous fertility setting: alpha = 0, beta = 1.
alpha
interpretation: proportion of an individual daughter's fertility multiplier--when heterogeneous fertility holds sway--that is inherited from her mother. The rest come from a call to a funtion that generates random numbers with a beta distribution. Or as in the code: 
 daughter->fmult = alpha * mother->fmult + (1 - alpha) * fertmult();
example: 
	alpha .1
default value: 0 (reassigned at start of segment)
beta
interpretation: once the child's fertility multiplier (daughter->fmult) is established, it can be modified using the code 
daughter->fmult = 2.5 * exp(beta*log(daughter->fmult/2.5));
example: 
  beta 1.05
default value: 1 (reassigned at start of segment)
factor
interpretation: modify a particular set of rates (a single event, group, sex, marital status index into the rate set) by the given value. In the case of birth rate sets, all parities are modified by the value for the given group and maritial status.
example: 
factor birth 1 single 1.1
factor death 1 M single .9
factor transit1 2 M single .9
default value: 1 (reassigned at start of segment)

Settings to support the Lee-Carter mortality model

Lee-Carter mortality uses several parameters to create on-the-fly rate sets based on the age of the individual at the time of the event competition and the "year" in the simulation the competition occurs. The format for parameters ax and bx is similar to ordinary rate sets, while the kt format is completely different. In particular, the kt can be specified using arbitrary start and stop points (so there must be support for delimiters), or by initial values and a formula (which requires specification keywords). All parameters (including one whole set for some version of the kt values) must be specified before a set is "complete." It's also necessary to inform SOCSIM of the correspondence between simulation month and "year" (e.g., 1990). The formula to use when extrapolating beyond the values provided is computed from the values provided, unless all values are specified by formula from an initial value supplied in a kc_k_val line. A simulation may run until year "2030," but SOCSIM has to have 100 years of event horizon at all times: the "year" parameters must be available for years up to 2129 for use in the last running year of the simulation. Lee-Carter rates are broken up by sex and group, only. The starting year is specified by an parameter to the lc_init keyword. This means that the entire set of Lee-Carter parameters and specification can be kept in one file and read -- via the "include" keyword in the top level command file-- during each segment, with a different start year (corresponding to the point in the simulation) specified in a higher level file (that is, higher with respect to nested reads).
lc_init
interpretation: the mortality model for this population class will be Lee-Carter. This command sets a flag that triggers Lee-Carter completeness checks (and doesn't doesn't complain about the absence of ordinary death rates) and allocates space for the new rate set components. If there is an extra argument, interpret this as the starting year if the kt values are read in. (Otherwise, assume that the values will be generated using a formula). In practice the init command can be at the top level while the rest of the LC specification can be in a separate file. The start year option allows the same file--with hundreds of kt values--to be included, unaltered, for each of several segments. In that case, the init commands should precede the inclusion commands. The command can appear in the included file, too, without ill effect and without the need for a start year ( only the first start year is recognized, and one must be specified before the list of kt values can be processed).
example: 
	lc_init 1 F 1938
	lc_init 1 M 2030
lc_ax
interpretation: the ax values follow: these are specified in the manner of other rates, even though they're parameters
example: 
	lc_ax 1 F single
analogous keyword: lc_bx
lc_k_val
interpretation: Initial value to use when the kt values are computed using the mean, standard deviation, and a starting value, base on the iterative formula: 
 kt_value[i+1] = kt_value[i] + lc->mean + lc->std_dev * normal();
The linear continuation after the last value is read is similar, without the standard deviation term.
example: 
  lc_k_val 1 F -3.5123
lc_k_mean
interpretation: the lc->mean, as above. Mean difference between successive kt values.
example: 
  lc_k_mean 1 F -.31
lc_k_std_dev
interpretation: the lc->std_dev, as above. Standard deviation between successive kt values.
example: 
  lc_k_std_dev 1 F 0
lc_k_start_list
interpretation: Begin reading kt values. These values have a different format which would be incorrect in any other context (while typically correct ones are wrong) so there is a need to inform the error checking mechanisms.
example: 
  lc_k_start_list 1 M
done
interpretation: end of the list of supplied kt values. Additional values will have to come from extrapolation (SOCSIM uses a linear continuation).
example: 
  done