In dymium-org/dymiumModules: A utility package for `dymium` module management
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
eval = TRUE
)
library(dymiumCore)
# knitr::opts_knit$set(root.dir = normalizePath(rprojroot::find_rstudio_root_file()))
demography module documentation
The demography module provides event functions for simulating the dynamics of evolving urban population and their households at an individual-based level. These events are responsible for household formation (marriage, cohabitation,
leaving parental home), household dissolutions (separation, divorce, break up), household expansion (birth).
Note that, there are hard-coded rules that can be modified, such as the age range in which females can bare a child. See constants.R.
Release notes
version 1.1.0
- Replaced
assign_reference() with World$get().
version 1.0.0
- Bumped up to version 1.0.0 to use the standard versionning (major.minor.patch)
- Fixed a wrong variable in a logging statement of the separation event.
version 0.1.3
This version is only compatible with dymiumCore version 0.1.4.
- Fixed various bugs in the module.
- Refactored demographic event functions.
- Fixed breaking changes from dymiumCore version 0.1.4 such as the removal of
household_formation functions and new Entity$add().
version 0.1.2
- Fixed the type of newborn's default age from numeric to integer.
version 0.1.1
- Updated outdated event
modules options. Event scipts should only export run and REQUIRED_MODELS.
version 0.1.0
- First release!
Requirements
R packages
R packages: dymiumCore, data.table, modules, here, checkmate, R6.
Events
Aging
Description
Increase age of all Individual agents by 1, which is equivalent to one year.
If there are any attributes that should be updated depending on the age of agent
then it can be implemented inside this event. For example, currently there are
three rules that are active. These rules update marital status, education,
and labour force status of the agent once it has reached some certain age thresholds.
All agents aged 16 and above can be in a relationship (a marriage or a cohabitation)
hence once they turn 16 their marital status will be changed from "not applicable"
to "never married" which allows them to be considered when the marriage event and
the cohabitation event are being simulated.
Usage
event_demography_age <- modules::use(here::here("modules/demography/age.R"))
event_demography_age
Params
- object: a World object.
- model: NULL, this event doesn't require this argument.
- target: NULL, this event doesn't require this argument.
- time_steps: an integer vector that contains the time steps in which this event
should be run.
Example
create_toy_world()
event_demography_age <- modules::use(here::here("modules/demography/age.R"))
# summary of 'age' attribute before ageing
summary(world$entities$Individual$get_attr(x = "age"))
world %>%
event_demography_age$run(.)
# summary of 'age' attribute after ageing
summary(world$entities$Individual$get_attr(x = "age"))
Birth
Description
The birth event adds newborns to the population by simulating the chance for fertile individual agents to give birth.
Newborns inherit some attributes from their mothers such as household id and dwelling id. Their mother id and father id fields will be set at the time of their birth and a new unique id will be assigned to them. If your Individual agents have more attributes than the basic ones in toy_individuals then you should modify the birth event script to set the default values for those extra attributes. See create_newborns() inside the event script.
Usage
event_demography_birth <- modules::use(here::here("modules/demography/birth.R"))
event_demography_birth
Params
- object: a [World] object.
- model: a named list.
- fertility: a binary model to determine whether an eligible female would to have a child or not.
- birth_multiplicity: chance of giving birth to more than one baby. Note that, the current code is only allow for twins but you may modify this to accommodate cases of triplets and more.
- birth_sex_ratio: the chance of giving birth to a female baby vs a male baby.
model <- list(fertility = list(yes = 0.05, no = 0.95),
birth_multiplicity = list("single" = 0.97, "twins" = 0.03),
birth_sex_ratio = list(male = 0.51, female = 0.49))
- target: default as
NULL or it can be a named list which determines the number of individual agents to under go the fertility event. For example, if a list list(yes = 100) it will garantee that there are 100 individual agents that will give birth.
- time_steps: an integer vector that contains the time steps in which this event
should be run.
Example
create_toy_world()
event_demography_birth <- modules::use(here::here("modules/demography/birth.R"))
# Total number of individuals before a run of the birth event
world$entities$Individual$n()
world %>%
event_demography_birth$run(., model = model)
# Total number of individuals after a run of the birth event
world$entities$Individual$n()
Death
Usage
event_demography_death <- modules::use(here::here("modules/demography/death.R"))
event_demography_death
Params
- world: a
World object.
- model: a named list.
- death: a binary model.
model <- list(death = list(yes = 0.1, no = 0.9))
- target: default as
NULL or a named list.
- time_steps: an integer vector that contains the time steps in which this event
should be run.
Description
Removes dying individual agents from the individual database and also updates any affected attributes (such as marital status, household size) the agents that are related to the dying agents.
The marital status of those individual agents whom their partner has died will be
labelled as "widowed". To retrive the data of all agents that have been removed you
through the death event use the get_removed_data() method.
Example
create_toy_world()
event_demography_death <- modules::use(here::here("modules/demography/death.R"))
# Total number of individuals before a run of the death event
world$entities$Individual$n()
# Distribution of marital status before a run of the death event
table(world$entities$Individual$get_attr("marital_status"))
world %>%
event_demography_death$run(., model = model)
# Total number of individuals after a run of the death event
world$entities$Individual$n()
# Distribution of marital status after a run of the death event
table(world$entities$Individual$get_attr("marital_status"))
Marriage
Description
This event forms marriage relationships between cohabiting couples and any two opposite-sex individuals that are not in a relationship. After the marriage is formed, the newly wedded couple then decide whether to form a new household or to merge their households into one. When forming a new household, regardless of their household formation decision, any related individuals (i.e. dependent children) to both individuals will also follow to the new household.
As you can see there are four models that shall be supplied to determine the likelihood in each stage of the marriage event. The first stage is to marry cohabiting couples based on the likelihood produces by the marriage_cohab_male model. The second stage is to marry eligible, single individual agents. The probabilities for the individual agents to enter the marital market come from the Monte Carlo simulation result performed using the marriage_no_cohab_male and marriage_no_cohab_female models on the individual agents' attributes. Then all participating individual agents are paired based on a given rule. The rule can be as simple as all agents prefer to match with an agent that has the minimum age difference to theirs. See StochasticMarriageMarket and OptimalMarriageMarket for the matching strategies available in modules/demography/marriage.R. Note that, if there are more agents of one gender than other in the marital market then the number of maximum matches will be equal to the number of individual agents with the lesser number. Those who are not matched will remain single after the event has ended. The current implementation doesn't include marriages between same-sex couples. After the matching step, all newly formed couples will decide whether they will form a new household (both agents leave their current households) or for the wife and her related individuals to join her husband's household. The current implementation applies a very simple rule which is likely to be wrong and should be replaced if there is a better assumption or model. The current rule is that for all newly wedded couples if their male partner aged more than the number given in husbandAgeRuleToCreateNewHousehold they will create a new household.
TLDR;
- Simulate marriages for comhabiting couples and single individuals.
- Aged 16 and above to be able to marry.
- Doesn't consider marriages between same-sex couples.
- The matching strategy for pairing individuals can be configured, either optimal or stochastic.
Usage
event_demography_marriage <- modules::use(here::here("modules/demography/marriage.R"))
event_demography_marriage
Params
- object: a [World] object.
- model: a named list.
- marriage_cohab_male: a binary model that determines whether a cohabitating couple will get married. This is based on attributes of the male partner.
- marriage_no_cohab_male: a binary model that determines the chance for eligible males to enter the marital market.
- marriage_no_cohab_female: a binary model that determines the chance for eligible females to enter the marital market.
model <- list(
marriage_cohab_male = list(yes = 0.1, no = 0.9),
marriage_no_cohab_male = list(yes = 0.1, no = 0.9),
marriage_no_cohab_female = list(yes = 0.1, no = 0.9)
)
- target: a named list
- time_steps: an integer vector that contains the time steps in which this event
should be run.
Example
create_toy_world()
event_demography_marriage <- modules::use(here::here("modules/demography/marriage.R"))
# Distribution of marital status before a run of the marriage event
table(world$entities$Individual$get_attr("marital_status"))
world %>%
event_demography_marriage$run(., model = model)
# Distribution of marital status before a run of the marriage event
table(world$entities$Individual$get_attr("marital_status"))
Separation
Description
Separation is the stage before a couple is officially divorced. In the Australian context, all married couples that would like to get divorced must register their separtion one year prior to becoming legally divorced. Hence, this event simulates that process.
Separation is the first step before couples can be officially divorced. This module assume that no couples will recoupled once they have decided to separate.
Usage
event_demography_separation <- modules::use(here::here("modules/demography/separation.R"))
event_demography_separation
Params
- object: a World object.
- model: a named list.
model <-
list(
separate_male = list(yes = 0.1, no = 0.9),
separate_child_custody = list(male = 0.2, female = 0.8),
separate_hhtype = list(lone = 0.5, group = 0.5),
separate_hf_random_join = list("1" = 0.4, "2" = 0.3, "3" = 0.2, "4" = 0.1)
)
- target: NULL
- time_steps: an integer vector that contains the time steps in which this event
should be run.
Example
create_toy_world()
event_demography_separation <- modules::use(here::here("modules/demography/separation.R"))
# Distribution of marital status before a run of the marriage event
table(world$entities$Individual$get_attr("marital_status"))
world %>%
event_demography_separation$run(., model = model)
# Distribution of marital status before a run of the marriage event
table(world$entities$Individual$get_attr("marital_status"))
Divorce
Description
When divorce is triggered for a separted individual, his/her ex-partner will also under go divorce if the marital status of his/her ex-partner is still 'separated'.
Usage
event_demography_divorce <- modules::use(here::here("modules/demography/divorce.R"))
event_demography_divorce
Params
- object: a World object.
- model: a named list.
model <- list(
divorce_male = list(yes = 0.5, no = 0.9),
divorce_female = list(yes = 0.5, no = 0.9)
)
- target: NULL
- time_steps: an integer vector that contains the time steps in which this event
should be run.
Example
create_toy_world()
event_demography_divorce <- modules::use(here::here("modules/demography/divorce.R"))
# Distribution of marital status before a run of the marriage event
table(world$entities$Individual$get_attr("marital_status"))
world %>%
event_demography_divorce$run(., model = model)
# Distribution of marital status before a run of the marriage event
table(world$entities$Individual$get_attr("marital_status"))
Cohabitation
Description
Form cohabitation relationships. Everything is the same with marriage in term of the steps.
Usage
event_demography_cohabit <- modules::use(here::here("modules/demography/cohabit.R"))
event_demography_cohabit
Params
- object: a [World] object.
- model: a named list.
model <- list(
cohabitation_male = list(yes = 0.1, no = 0.9),
cohabitation_female = list(yes = 0.1, no = 0.9)
)
- target: a named list.
- time_steps: an integer vector that contains the time steps in which this event
should be run.
Example
create_toy_world()
event_demography_cohabit <- modules::use(here::here("modules/demography/cohabit.R"))
# people with partner before the cohabitation event
table(!is.na(world$entities$Individual$get_attr("partner_id")))
world %>%
event_demography_cohabit$run(., model = model)
# people with partner after running the cohabitation event
table(!is.na(world$entities$Individual$get_attr("partner_id")))
Breakup
Description
Breakup ends cohabitation relationships.
Usage
event_demography_breakup <- modules::use(here::here("modules/demography/breakup.R"))
event_demography_breakup
Params
- object: a [World] object.
- model: a named list.
model <-
list(
breakup = list(yes = 0.1, no = 0.9),
breakup_child_custody = list(male = 0.2, female = 0.8),
breakup_hhtype = list(lone = 0.5, group = 0.5),
breakup_hf_random_join = list("1" = 0.4, "2" = 0.3, "3" = 0.2, "4" = 0.1)
)
- target: a named list.
- time_steps: an integer vector that contains the time steps in which this event
should be run.
Example
create_toy_world()
event_demography_breakup <- modules::use(here::here("modules/demography/breakup.R"))
# Total number of individuals with partner before
table(is.na(world$entities$Individual$get_attr("partner_id")))
world %>%
event_demography_breakup$run(., model = model)
# Total number of individuals with partner after
table(is.na(world$entities$Individual$get_attr("partner_id")))
Leave parental home
Description
This simulates young adults leaving their parental home.
This should not include the proportion of people whom leave home to get married or to live with their partner as it has been accounted for in the marriage event and the cohabitation event.
Usage
event_demography_leavehome <- modules::use(here::here("modules/demography/leavehome.R"))
event_demography_leavehome
Params
- object: a [World] object.
- model: a named list.
- leavehome_male: a binary decision for male individuals whether to leave home or not.
- leavehome_female: a binary decision for female individuals whether to leave home or not.
- leavehome_hhtype: a binary choice whether to join a group household or to form a single household.
- leavehome_hf_random_join: a discrete distribution of the household size. For example, if this is
list(1 = 0.5, 2 = 0.3, 3 = 0.1, 4 = 0.1) there is a 50% chance that an individual leaving their parental home will find a single household to join and a 30% chance to join a two-person household and so on.
model <- list(leavehome_male = list(yes = 0.3, no = 0.7),
leavehome_female = list(yes = 0.2, no = 0.8),
leavehome_hhtype = list(lone = 0.2, group = 0.8),
leavehome_hf_random_join = list("1" = 0.5, "2" = 0.3, "3" = 0.1, "4" = 0.1))
- target:
NULL or a named list.
- time_steps: an integer vector that contains the time steps in which this event
should be run.
Example
create_toy_world()
event_demography_leavehome <- modules::use(here::here("modules/demography/leavehome.R"))
# Total number of households before
world$entities$Household$n()
world %>%
event_demography_leavehome$run(., model = model)
# Total number of households after
world$entities$Household$n()
Migration
Description
Add a migrant population to the main population.
The migrant population will be assigned new unique ids once it is added. Note that all migrants should have all the same attribute columns (as well as their types) as the main population it is being added to.
Usage
event_demography_migration <- modules::use(here::here("modules/demography/migration.R"))
event_demography_migration
Params
- object: a [World] object.
- model: a named list.
- migrant_individuals: a data.table that contains migrant individual agents' attribute data.
- migrant_households: a data.table that contains migrant household agents' attribute data.
model <- list(
migrant_individuals = dymiumCore::toy_individuals,
migrant_households = dymiumCore::toy_households
)
- target: an integer which indicates how many households should be added.
target = 100
- time_steps: an integer vector that contains the time steps in which this event
should be run.
Note
Example
create_toy_world()
event_demography_migration <- modules::use(here::here("modules/demography/migration.R"))
# Total number of households and individuals before
world$entities$Household$n()
world$entities$Individual$n()
world %>%
event_demography_migration$run(., model = model, target = target)
# Total number of households and individuals after
world$entities$Household$n()
world$entities$Individual$n()
Known issues
dymium-org/dymiumModules documentation built on May 23, 2020, 10:30 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
knitr::opts_chunk$set( collapse = TRUE, comment = "#>", eval = TRUE ) library(dymiumCore) # knitr::opts_knit$set(root.dir = normalizePath(rprojroot::find_rstudio_root_file()))
demography module documentation
The demography module provides event functions for simulating the dynamics of evolving urban population and their households at an individual-based level. These events are responsible for household formation (marriage, cohabitation, leaving parental home), household dissolutions (separation, divorce, break up), household expansion (birth).
Note that, there are hard-coded rules that can be modified, such as the age range in which females can bare a child. See constants.R.
Release notes
version 1.1.0
- Replaced
assign_reference()withWorld$get().
version 1.0.0
- Bumped up to version 1.0.0 to use the standard versionning (major.minor.patch)
- Fixed a wrong variable in a logging statement of the separation event.
version 0.1.3
This version is only compatible with dymiumCore version 0.1.4.
- Fixed various bugs in the module.
- Refactored demographic event functions.
- Fixed breaking changes from dymiumCore version 0.1.4 such as the removal of
household_formationfunctions and newEntity$add().
version 0.1.2
- Fixed the type of newborn's default age from numeric to integer.
version 0.1.1
- Updated outdated event
modulesoptions. Event scipts should only exportrunandREQUIRED_MODELS.
version 0.1.0
- First release!
Requirements
R packages
R packages: dymiumCore, data.table, modules, here, checkmate, R6.
Events
Aging
Description
Increase age of all Individual agents by 1, which is equivalent to one year.
If there are any attributes that should be updated depending on the age of agent then it can be implemented inside this event. For example, currently there are three rules that are active. These rules update marital status, education, and labour force status of the agent once it has reached some certain age thresholds. All agents aged 16 and above can be in a relationship (a marriage or a cohabitation) hence once they turn 16 their marital status will be changed from "not applicable" to "never married" which allows them to be considered when the marriage event and the cohabitation event are being simulated.
Usage
event_demography_age <- modules::use(here::here("modules/demography/age.R"))
event_demography_age
Params
- object: a World object.
- model: NULL, this event doesn't require this argument.
- target: NULL, this event doesn't require this argument.
- time_steps: an integer vector that contains the time steps in which this event should be run.
Example
create_toy_world() event_demography_age <- modules::use(here::here("modules/demography/age.R")) # summary of 'age' attribute before ageing summary(world$entities$Individual$get_attr(x = "age")) world %>% event_demography_age$run(.) # summary of 'age' attribute after ageing summary(world$entities$Individual$get_attr(x = "age"))
Birth
Description
The birth event adds newborns to the population by simulating the chance for fertile individual agents to give birth.
Newborns inherit some attributes from their mothers such as household id and dwelling id. Their mother id and father id fields will be set at the time of their birth and a new unique id will be assigned to them. If your Individual agents have more attributes than the basic ones in toy_individuals then you should modify the birth event script to set the default values for those extra attributes. See create_newborns() inside the event script.
Usage
event_demography_birth <- modules::use(here::here("modules/demography/birth.R"))
event_demography_birth
Params
- object: a [World] object.
- model: a named list.
- fertility: a binary model to determine whether an eligible female would to have a child or not.
- birth_multiplicity: chance of giving birth to more than one baby. Note that, the current code is only allow for twins but you may modify this to accommodate cases of triplets and more.
- birth_sex_ratio: the chance of giving birth to a female baby vs a male baby.
model <- list(fertility = list(yes = 0.05, no = 0.95), birth_multiplicity = list("single" = 0.97, "twins" = 0.03), birth_sex_ratio = list(male = 0.51, female = 0.49))
- target: default as
NULLor it can be a named list which determines the number of individual agents to under go the fertility event. For example, if a listlist(yes = 100)it will garantee that there are 100 individual agents that will give birth. - time_steps: an integer vector that contains the time steps in which this event should be run.
Example
create_toy_world() event_demography_birth <- modules::use(here::here("modules/demography/birth.R")) # Total number of individuals before a run of the birth event world$entities$Individual$n() world %>% event_demography_birth$run(., model = model) # Total number of individuals after a run of the birth event world$entities$Individual$n()
Death
Usage
event_demography_death <- modules::use(here::here("modules/demography/death.R"))
event_demography_death
Params
- world: a
Worldobject. - model: a named list.
- death: a binary model.
model <- list(death = list(yes = 0.1, no = 0.9))
- target: default as
NULLor a named list. - time_steps: an integer vector that contains the time steps in which this event should be run.
Description
Removes dying individual agents from the individual database and also updates any affected attributes (such as marital status, household size) the agents that are related to the dying agents.
The marital status of those individual agents whom their partner has died will be
labelled as "widowed". To retrive the data of all agents that have been removed you
through the death event use the get_removed_data() method.
Example
create_toy_world() event_demography_death <- modules::use(here::here("modules/demography/death.R")) # Total number of individuals before a run of the death event world$entities$Individual$n() # Distribution of marital status before a run of the death event table(world$entities$Individual$get_attr("marital_status")) world %>% event_demography_death$run(., model = model) # Total number of individuals after a run of the death event world$entities$Individual$n() # Distribution of marital status after a run of the death event table(world$entities$Individual$get_attr("marital_status"))
Marriage
Description
This event forms marriage relationships between cohabiting couples and any two opposite-sex individuals that are not in a relationship. After the marriage is formed, the newly wedded couple then decide whether to form a new household or to merge their households into one. When forming a new household, regardless of their household formation decision, any related individuals (i.e. dependent children) to both individuals will also follow to the new household.
As you can see there are four models that shall be supplied to determine the likelihood in each stage of the marriage event. The first stage is to marry cohabiting couples based on the likelihood produces by the marriage_cohab_male model. The second stage is to marry eligible, single individual agents. The probabilities for the individual agents to enter the marital market come from the Monte Carlo simulation result performed using the marriage_no_cohab_male and marriage_no_cohab_female models on the individual agents' attributes. Then all participating individual agents are paired based on a given rule. The rule can be as simple as all agents prefer to match with an agent that has the minimum age difference to theirs. See StochasticMarriageMarket and OptimalMarriageMarket for the matching strategies available in modules/demography/marriage.R. Note that, if there are more agents of one gender than other in the marital market then the number of maximum matches will be equal to the number of individual agents with the lesser number. Those who are not matched will remain single after the event has ended. The current implementation doesn't include marriages between same-sex couples. After the matching step, all newly formed couples will decide whether they will form a new household (both agents leave their current households) or for the wife and her related individuals to join her husband's household. The current implementation applies a very simple rule which is likely to be wrong and should be replaced if there is a better assumption or model. The current rule is that for all newly wedded couples if their male partner aged more than the number given in husbandAgeRuleToCreateNewHousehold they will create a new household.
TLDR;
- Simulate marriages for comhabiting couples and single individuals.
- Aged 16 and above to be able to marry.
- Doesn't consider marriages between same-sex couples.
- The matching strategy for pairing individuals can be configured, either optimal or stochastic.
Usage
event_demography_marriage <- modules::use(here::here("modules/demography/marriage.R"))
event_demography_marriage
Params
- object: a [World] object.
- model: a named list.
- marriage_cohab_male: a binary model that determines whether a cohabitating couple will get married. This is based on attributes of the male partner.
- marriage_no_cohab_male: a binary model that determines the chance for eligible males to enter the marital market.
- marriage_no_cohab_female: a binary model that determines the chance for eligible females to enter the marital market.
model <- list( marriage_cohab_male = list(yes = 0.1, no = 0.9), marriage_no_cohab_male = list(yes = 0.1, no = 0.9), marriage_no_cohab_female = list(yes = 0.1, no = 0.9) )
- target: a named list
- time_steps: an integer vector that contains the time steps in which this event should be run.
Example
create_toy_world() event_demography_marriage <- modules::use(here::here("modules/demography/marriage.R")) # Distribution of marital status before a run of the marriage event table(world$entities$Individual$get_attr("marital_status")) world %>% event_demography_marriage$run(., model = model) # Distribution of marital status before a run of the marriage event table(world$entities$Individual$get_attr("marital_status"))
Separation
Description
Separation is the stage before a couple is officially divorced. In the Australian context, all married couples that would like to get divorced must register their separtion one year prior to becoming legally divorced. Hence, this event simulates that process.
Separation is the first step before couples can be officially divorced. This module assume that no couples will recoupled once they have decided to separate.
Usage
event_demography_separation <- modules::use(here::here("modules/demography/separation.R"))
event_demography_separation
Params
- object: a World object.
- model: a named list.
model <- list( separate_male = list(yes = 0.1, no = 0.9), separate_child_custody = list(male = 0.2, female = 0.8), separate_hhtype = list(lone = 0.5, group = 0.5), separate_hf_random_join = list("1" = 0.4, "2" = 0.3, "3" = 0.2, "4" = 0.1) )
- target: NULL
- time_steps: an integer vector that contains the time steps in which this event should be run.
Example
create_toy_world() event_demography_separation <- modules::use(here::here("modules/demography/separation.R")) # Distribution of marital status before a run of the marriage event table(world$entities$Individual$get_attr("marital_status")) world %>% event_demography_separation$run(., model = model) # Distribution of marital status before a run of the marriage event table(world$entities$Individual$get_attr("marital_status"))
Divorce
Description
When divorce is triggered for a separted individual, his/her ex-partner will also under go divorce if the marital status of his/her ex-partner is still 'separated'.
Usage
event_demography_divorce <- modules::use(here::here("modules/demography/divorce.R"))
event_demography_divorce
Params
- object: a World object.
- model: a named list.
model <- list( divorce_male = list(yes = 0.5, no = 0.9), divorce_female = list(yes = 0.5, no = 0.9) )
- target: NULL
- time_steps: an integer vector that contains the time steps in which this event should be run.
Example
create_toy_world() event_demography_divorce <- modules::use(here::here("modules/demography/divorce.R")) # Distribution of marital status before a run of the marriage event table(world$entities$Individual$get_attr("marital_status")) world %>% event_demography_divorce$run(., model = model) # Distribution of marital status before a run of the marriage event table(world$entities$Individual$get_attr("marital_status"))
Cohabitation
Description
Form cohabitation relationships. Everything is the same with marriage in term of the steps.
Usage
event_demography_cohabit <- modules::use(here::here("modules/demography/cohabit.R"))
event_demography_cohabit
Params
- object: a [World] object.
- model: a named list.
model <- list( cohabitation_male = list(yes = 0.1, no = 0.9), cohabitation_female = list(yes = 0.1, no = 0.9) )
- target: a named list.
- time_steps: an integer vector that contains the time steps in which this event should be run.
Example
create_toy_world() event_demography_cohabit <- modules::use(here::here("modules/demography/cohabit.R")) # people with partner before the cohabitation event table(!is.na(world$entities$Individual$get_attr("partner_id"))) world %>% event_demography_cohabit$run(., model = model) # people with partner after running the cohabitation event table(!is.na(world$entities$Individual$get_attr("partner_id")))
Breakup
Description
Breakup ends cohabitation relationships.
Usage
event_demography_breakup <- modules::use(here::here("modules/demography/breakup.R"))
event_demography_breakup
Params
- object: a [World] object.
- model: a named list.
model <- list( breakup = list(yes = 0.1, no = 0.9), breakup_child_custody = list(male = 0.2, female = 0.8), breakup_hhtype = list(lone = 0.5, group = 0.5), breakup_hf_random_join = list("1" = 0.4, "2" = 0.3, "3" = 0.2, "4" = 0.1) )
- target: a named list.
- time_steps: an integer vector that contains the time steps in which this event should be run.
Example
create_toy_world() event_demography_breakup <- modules::use(here::here("modules/demography/breakup.R")) # Total number of individuals with partner before table(is.na(world$entities$Individual$get_attr("partner_id"))) world %>% event_demography_breakup$run(., model = model) # Total number of individuals with partner after table(is.na(world$entities$Individual$get_attr("partner_id")))
Leave parental home
Description
This simulates young adults leaving their parental home.
This should not include the proportion of people whom leave home to get married or to live with their partner as it has been accounted for in the marriage event and the cohabitation event.
Usage
event_demography_leavehome <- modules::use(here::here("modules/demography/leavehome.R"))
event_demography_leavehome
Params
- object: a [World] object.
- model: a named list.
- leavehome_male: a binary decision for male individuals whether to leave home or not.
- leavehome_female: a binary decision for female individuals whether to leave home or not.
- leavehome_hhtype: a binary choice whether to join a group household or to form a single household.
- leavehome_hf_random_join: a discrete distribution of the household size. For example, if this is
list(1 = 0.5, 2 = 0.3, 3 = 0.1, 4 = 0.1)there is a 50% chance that an individual leaving their parental home will find a single household to join and a 30% chance to join a two-person household and so on.
model <- list(leavehome_male = list(yes = 0.3, no = 0.7), leavehome_female = list(yes = 0.2, no = 0.8), leavehome_hhtype = list(lone = 0.2, group = 0.8), leavehome_hf_random_join = list("1" = 0.5, "2" = 0.3, "3" = 0.1, "4" = 0.1))
- target:
NULLor a named list. - time_steps: an integer vector that contains the time steps in which this event should be run.
Example
create_toy_world() event_demography_leavehome <- modules::use(here::here("modules/demography/leavehome.R")) # Total number of households before world$entities$Household$n() world %>% event_demography_leavehome$run(., model = model) # Total number of households after world$entities$Household$n()
Migration
Description
Add a migrant population to the main population.
The migrant population will be assigned new unique ids once it is added. Note that all migrants should have all the same attribute columns (as well as their types) as the main population it is being added to.
Usage
event_demography_migration <- modules::use(here::here("modules/demography/migration.R"))
event_demography_migration
Params
- object: a [World] object.
- model: a named list.
- migrant_individuals: a data.table that contains migrant individual agents' attribute data.
- migrant_households: a data.table that contains migrant household agents' attribute data.
model <- list( migrant_individuals = dymiumCore::toy_individuals, migrant_households = dymiumCore::toy_households )
- target: an integer which indicates how many households should be added.
target = 100
- time_steps: an integer vector that contains the time steps in which this event should be run.
Note
Example
create_toy_world() event_demography_migration <- modules::use(here::here("modules/demography/migration.R")) # Total number of households and individuals before world$entities$Household$n() world$entities$Individual$n() world %>% event_demography_migration$run(., model = model, target = target) # Total number of households and individuals after world$entities$Household$n() world$entities$Individual$n()
Known issues
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.