age.specific.migration {bayesPop}

Generate Sex- and Age-specific Migration

Description

Creates sex- and age-specific net migration datasets out of the total net migration using either a residual method or given age schedules.

Usage

age.specific.migration(wpp.year = 2019, years = seq(1955, 2100, by = 5), 
    countries = NULL, smooth = TRUE, rescale = TRUE, ages.to.zero = 18:21,
    write.to.disk = FALSE, directory = getwd(), file.prefix = "migration", 
    depratio = wpp.year == 2015, verbose = TRUE)
    
migration.totals2age(df, ages = NULL, annual = FALSE, time.periods = NULL, 
    schedule = NULL, scale = 1, method = "auto", sex = "M",
    id.col = "country_code", country_code = NULL, mig.is.rate = FALSE, 
    alt.schedule.file = NULL, ...)
    
rcastro.schedule(annual = FALSE)

Arguments

wpp.year

Integer determining which wpp package should be used to get the necessary data from. That package is required to have a dataset on total net migration (called migration). Currently, only packages wpp2015, wpp2017 and wpp2019 contain it (see Details).

years

Array of years that the reconstruction should be made for. This should be a subset of years for which the total net migration is available.

countries

Numerical country codes to do the reconstruction for. By default it is performed on all countries included in the migration dataset where aggregations are excluded.

smooth

Logical controlling if smoothing of the reconstructed curves is required. Due to rounding issues the residual method often yields unrealistic zig-zags on migration curves by age. Smoothing usually improves their look.

rescale

Logical controlling if the resulting migration should be rescaled to match the total migration.

ages.to.zero

Indices of age groups where migration should be set to zero. Default is 85 and older.

write.to.disk

If TRUE results are written to disk.

directory

Directory where to write the results if write.to.disk is TRUE.

file.prefix

If write.to.disk is TRUE results are written into two text files with this prefix, a letter “M” and “F” determining the sex, and concluded by the “.txt” suffix. By default “migrationM.txt” and “migrationF.txt”.

depratio

If it is TRUE it will use an internal dataset on migration dependency ratios to adjust the first three age groups. It can also be a name of a binary file containing such dataset.

verbose

Logical controlling the amount of output messages.

df

data.frame, marix or data.table containing total migration counts or rates. Columns correspond to time, rows correspond to locations. Column “country_code” (or column identified by id.col) contains identifiers of the locations. Names of the time columns should be either single years if annual is TRUE, e.g. “2018”, “2019” etc., or five year time periods if annual is FALSE, e.g. “2010-2015”, “2015-2020” etc.

ages

Labels of age groups into which the total migration is to be disaggregated. If it is missing, default age groups are determined depending on the argument annual.

annual

Logical determining if the age groups are 5-year age groups (FALSE) or 1-year ages (TRUE) on which the choice of the default schedule is dependent, if schedule is missing. It also determines the expected syntax of the names of time columns in df.

time.periods

Character vector determining which columns should be considered in the df dataset. It should be a subset of column names in df. By default, all time columns in df are considered.

schedule

Numeric vector used for distributing total migration across ages. It should have the same length as ages. If not given, the argument method determines how the totals are distributed.

scale

The migration schedule is multiplied by this number. It can be used for example, if total migration needs to be distributed between sexes.

method

Method to use for the distribution of totals into age groups. The “un” method, available only for wpp2022 and only for projected migration, uses the UN migration schedules. The “rc” method uses a simple Rogers-Castro disaggregation via the function rcastro.schedule. The “user” method allows to provide expernal schedules in a file given in the argument alt.schedule.file. The “auto” method tries to apply the “un” method first and for countries or time periods where there is no match, it applies the “rc” method.

sex

“M” or “F” determining the sex of this schedule. It is used for matching to the UN schedules, i.e. if the “auto” or “un” method is used.

id.col

Name of the unique identifier of the locations.

country_code

Code of the country if the data belongs to only country only. It is used for matching to the UN schedules, i.e. if the “auto” or “un” method is used.

mig.is.rate

Logical indicating if the data in df should be interpreted as rates. If FALSE, df represent counts.

alt.schedule.file

If method is “user”, alternative migration age schedules can be provided in this binary file. It has the same structure as the internal package objects mig1.schedule (annual) or mig5.schedule (5-year). If there are different schedules for positive and negative totals, the negative schedules are in mig1.neg.schedule or mig5.neg.schedule objects.

...

Further arguments passed to the underlying functions.

Details

Function age.specific.migration

Unlike in wpp2012, for the three latest releases of the WPP, the wpp2015, wpp2017, and wpp2019, the UN Population Division did not publish the sex- and age-specific net migration counts, only the totals. However, since the sex- and age-schedules are needed for population projections, the age.specific.migration function attempts to reconstruct those missing datasets. It uses the published population projections by age and sex, fertility and mortality projections from the wpp package. It computes the population projection without migration and sets the residual to the published population projection as the net migration. By default such numbers are then scaled so that the sum over sexes and ages corresponds to the total migration count.

If smooth is TRUE a smoothing procedure is performed over ages where necessary. Also, for simplicity, we set migration of old ages to zero (default is 85+). Both is done before the scaling. If it is desired to obtain raw residuals without any additional processing, set smooth=FALSE, rescale=FALSE, ages.to.zero=c().

Function migration.totals2age

This function should be used when working with wpp2022 data. It allows users to disagregate total migration counts or rates (for multiple time periods and multiple locations) into age-specific ones by either the UN schedule used in WPP2022 (method = "un"), a Rogers-Castro (method = "rc"), a user-defined schedule (method = "user") or a combination of the first two (method = "auto"). In the latter case, the UN schedule is used for records that match in terms of country code and time periods. For the remaining records, a Rogers-Castro schedule is used. The latter schedule can be accessed via the function rcastro.schedule where the annual argument specifies if it is for 1-year or 5-year age groups.

Value

Function age.specific.migration returns a list of two data frames (male and female), each having the same structure as migrationM.

Function migration.totals2age returns a data.table with the disaggregated counts.

Function rcastro.schedule returns a vector of proportions for each age group.

Warning

Due to rounding issues and slight differences in the methodology, the age.specific.migration function does not reproduce the unpublished UN datasets exactly. It is only an approximation! Especially, the first age groups might be more off than other ages.

Note

The age.specific.migration function is called automatically from pop.predict if no migration input is given. Similarly, if migration is given as totals, i.e. via the entries mig, migMt, or migFt, the function migration.totals2age is called using either the UN schedules or the default Rogers-Castro schedule. Thus, only users that need sex- and age-specific migration for other purposes, or modify the defaults, will need to call these functions explicitly.

Author(s)

Hana Sevcikova

See Also

pop.predict, migration migrationM

Examples

## Not run: 
asmig <- age.specific.migration()
head(asmig$male)
head(asmig$female)
## End(Not run)

# simple disaggregation for one location
totmig <- c(30, -50, -100)
names(totmig) <- 2018:2020
asmig.simple <- migration.totals2age(totmig, annual = TRUE, method = "rc")
head(asmig.simple)

## Not run: 
# disaggregate WPP 2019 migration for all countries, one sex
data(migration, package = "wpp2019")
# assuming equal sex migration ratio
asmig.all <- migration.totals2age(migration, scale = 0.5, method = "rc") 
# plot result for the US in 2095-2100
mig1sex.us <- subset(asmig.all, country_code == 840)[["2095-2100"]]
plot(ts(mig1sex.us))
# check that the sum is half of the original total
sum(mig1sex.us) == subset(migration, country_code == 840)[["2095-2100"]]/2
## End(Not run)