Generates synthetic genealogical populations at (small) country scale.
These are all the configuration options supported by ValiPop. Options suffixed with a ‘*’ are required.
Configuration Options
group_name
A name used for a grouping of runs. Must be a valid name for files and directories.
Results of a specific run are written to
<results_save_location>/<group_name>/<timestamp>
timestamp represents the datetime the runs was executed at in the form yyyy-mm-ddThh-mm-ss-sss.
Defaults to default
results_save_location
Path to the root results directory of runs.
Defaults to results/.
summary_results_save_location
Path to the directory where summarisations of runs are written.
A summary is a CSV file where each row is represented as a run. Each row contains information about the run configuration and results.
There is a global summary file shared by all runs at
<summary_results_save_location>/global-results-summary.csv
There is local summary file shared by all runs of the same run purpose at
<summary_results_save_location>/<group_name>/<group_name>-results-summary.csv
Defaults to results/.
input_distributions_path
Path to the input distribution directory.
This is required.
project_location
Path to the project directory.
Defaults to . (current directory).
initialisation_start
The start date of the initialisation phase, where an initial population is generated and simulated until simulation_start. The period between initialisation_start and simulation_start must be at least 150 years to allow enough time for the preliminary population to settle.
At initialisation_start an initial population is first spawned, of which its size is based on initialisation_birth_rate and initialisation_death_rate, and the duration from simulation_start. The population is then simulated regularly until simulation_start.
This is required.
simulation_start
The start date of the main phase, where records of events occurring between simulation_start until simulation_end will be recorded.
This is required.
simulation_end
The end date of the main phase, and end of the simulation in total.
This is required.
simulation_time_step
The time interval used for each simulation step. This is a Java period string of the form P<year>Y<month>M<day>D.
Defaults to P1Y (1 year).
min_birth_spacing
The minimum time interval parents must wait since their last child before having another child. This is a Java period string of the form P<year>Y<month>M<day>D.
Defaults to P147D (147 days).
min_gestation_period
The minimum time interval the child must have been conceived at before their birth. This is a Java period string of the form P<year>Y<month>M<day>D.
Defaults to P147D (147 days).
distribution_granularity
The time intervals for which the given input distributions are divided into between initialisation_start and simulation_end. Input distributions for the same properties over multiple different years are the separated into their respective time_intervals. This is a Java period string of the form P<year>Y<month>M<day>D.
Defaults to P1Y (1 year).
target_initial_population_size
The desired population size at simulation_start. The initialisation phase will aim to generate an initial population of this size from initialisation_start until simulation_start.
This is required.
initialisation_birth_rate
The flat birth rate used for the initial population between initialisation_start and simulation_start. It represents the percentage increase of the population in one time step as a decimal.
Defaults to 0.133.
initialisation_death_rate
The flat death rate used for the initial population between initialisation_start and simulation_start. It represents the percentage decrease of the population in one time step as a decimal.
Defaults to 0.122.
recovery_factor
A multiplier determining how strongly the simulation should compensate for deviations from given one dimensional input distributions
Defaults to 1.
proportional_recovery_factor
A multiplier determining how strongly the simulation should compensate for deviations from given two dimensional input distributions
Defaults to 1.
record_export_format
The output format of the target population records. Can be one of:
NONE : Does not generate.TD : Custom record format created by Tom Dalton.DS : Record format used by Digitising Scotland.EG_SKYE : Subset of the DS format.VIS_PROCESSING: Simplified record format used by Digitising Scotland.Defaults to NONE.
population_export_format
The output format of the target population graphic. Can be one of:
NONE: Does not generate.GRAPHVIZ: a Graphviz .dot file to render a family tree graphGEDCOM: a GEDCOM family tree fileGEOJSON: a Geojoson file showing the birth adresses of each personDefaults to None.
output_table
When true, this creates contingency tables required by the population analysis.
When false, the contingency tables are not created and the population analysis is skipped.
A contingency table is a collection of expected and actual frequencies for events. Contingency tables for birth orders, multiple births, partnership, deaths, and separations are generated.
Defaults to true.
contingency_table_stepback
The stepback used in the contingency table calculation.
Defaults to 1.
contingency_table_precision
The precision used in the contingency table calculation.
Defaults to 1E-66.
deterministic
When true, the program seeds its random generator with the value of seed. This will yield the same result for every run using the same seed.
When false, it will use the system time. This will likely yield different results on every run.
Defaults to false.
seed
The value used to seed random generator. This will be ignored if deterministic = false.
Defaults to 56854687.
binomial_sampling
When true, counts determined by the given input distributions are sampled from binomial distributions.
When false, counts determined by the given input distributions are sampled from normal distributions.
Defaults to true.
over_sized_geography_factor
The multiplier applied when determining the number of house addresses in a given area.
This is used for determining moving addresses and partnering.
Defaults to 1.