Birth

Birth package.

class miscore.processes.Birth(birth_table=None, year=None, name='birth')[source]

This process generates births for each individual in the simulated population. Can be used with a birth table or a fixed birth date. Example data is provided in the data module. If no birth_table or year is passed, everyone will be born in the year 0.

Parameters:
Raises:

AssertionError – This error is raised when both a birth_table and a year are given.

miscore.processes.birth.calc_adjusted_birth_table(data, sex, country, year, cohort_names=None, sum_to=None)[source]

calc_adjusted_birth_table takes as input the number of people alive in a given year from each birth cohort, and calculates the equivalent cohort sizes at birth by dividing the current size of the cohort by the cohort-specific survival up to given year. It is possible to define different years of evaluation for each cohort given in data by supplying an array for year rather than a single value.

Note that for cohorts that are either very old (i.e. <1930), as well as for recent cohorts (> 1990), the closest available cohort life tables will be used to determine the equivalent cohort sizes at birth.

For example, to calculate equivalent natality figures for the birth cohort distribution of Dutch females in 2021:

>>> import miscore.processes.birth.data.nl_2021 as data
>>> abt = calc_adjusted_birth_table(data.female_cohort_counts, sex="female", country="NL",
...                                 year=2021)
>>> abt[1960]
np.float64(130153.69555061006)
>>> abt[1980]
np.float64(108672.04155275054)

Or, by extension, if we want to evaluate equivalent natality figures for the number alive among one group of cohorts in 2018, but for another in 2021, we need to supply for year a list with the correct reference years, for each cohort separately. Since the cohort years will be repeated among the male and female cohorts, we also need to supply a list of names to properly distinguish them:

>>> female_table_2018 = [(10000, 1960), (11000, 1961), (12000, 1962)]
>>> female_table_2021 = [(9000, 1960), (8000, 1961), (7000, 1962)]
>>> year = [2018, 2018, 2018, 2021, 2021, 2021]
>>> cohort_names = ['group1_1920', 'group1_1921', 'group1_1922',
...          'group2_1920', 'group2_1921', 'group2_1922']
>>> abt = calc_adjusted_birth_table([*female_table_2018, *female_table_2021], sex="female",
...                                 country="NL", year=year, cohort_names=cohort_names)
>>> abt['group1_1921']
np.float64(11762.843564176126)

For further explanation, and more examples, see the documentation.

Parameters:

  • data (Sequence[Tuple[SupportsFloat, SupportsFloat]] | Series) – Data array of PiecewiseLinear.Data type reporting the number (first column) of individuals born in each cohort (second column), alive at the given year.

  • sex (str | Sequence) – Sex of the target population, used to retrieve correct cohort life tables. Can be “male”, “female” or “total”. Either a single sex for each cohort, or a sequence of equal length to data with the sex of each cohort.

  • country (str) – Country of the target population. Can be “US” or “NL”.

  • year (int | Sequence) – Year to which the cohort sizes need to be adjusted, used to retrieve the correct survival figure for each cohort. Either specify a single year, used for all cohorts, or a list of cohort-specific years with length equal to data.

  • cohort_names – List of unique names for each cohort, obligatory when multiple cohorts have the same birth year.

  • sum_to (float | None) – Number that all values in the returned dictionary should sum up to. Can be used to obtain a population of a certain size that consists of several cohorts.

Returns:

A dictionary with p entries, where p is equal to the length of the input array. Indices are given by year, and values give the equivalent cohort size to reproduce the size of the cohort in the supplied year.

miscore.processes.birth.get_birth_table(country, start_year, end_year, sex='total', fractional=False)[source]

The function get_birth_table retrieves a birth table for a specified country, sex and period. The function can be used to generate a population proportional to the historic birth counts of a country.

For example, to retrieve a US birth table to simulate the male population born between 1950 and 1990:

>>> bt = get_birth_table(country="US", start_year=1950, end_year=1989, sex="male")
>>> bt[0:3].tolist()
[[0.0, 1950.0], [0.02419714320448625, 1951.0], [0.049654148400832494, 1952.0]]
>>> bt[-3:].tolist()
[[0.9471128898688392, 1988.0], [0.9731209093450068, 1989.0], [1.0, 1990.0]]
Parameters:

  • country (str) – The country for which a birth table is needed, currently either “US” or “NL”.

  • start_year (int) – The first year for which a birth table is needed.

  • end_year (int) – The final year for which a birth table is needed.

  • sex (str) – The sex for which a birth table is needed, either “male”, “female”, or “total”. Defaults to “total”.

  • fractional (bool) – Determines if the birth table should be reported as fractions instead of cumulatively. Defaults to False.

Returns:

A p x n array of cumulative birth proportions that can be used as an input for the Birth process, where p = (end_year - start_year + 2), such that the cumulative births are 0 at the start of start_year, and 1.0 at the start of (end_year + 1).

Raises:

ValueError – Raised when country, sex, start_year or end_year are invalid.