The function generates trajectories of probabilistic population projection for all countries for which input data is available, or any subset of them.
pop.predict(end.year = 2100, start.year = 1950, present.year = 2020,
wpp.year = 2019, countries = NULL,
output.dir = file.path(getwd(), "bayesPop.output"),
annual = FALSE,
inputs = list(popM=NULL, popF=NULL, mxM=NULL, mxF=NULL, srb=NULL,
pasfr=NULL, patterns=NULL,
migM=NULL, migF=NULL, migMt=NULL, migFt=NULL, mig=NULL,
e0F.file=NULL, e0M.file=NULL, tfr.file=NULL,
e0F.sim.dir=NULL, e0M.sim.dir=NULL, tfr.sim.dir=NULL,
migMtraj = NULL, migFtraj = NULL, migtraj = NULL,
GQpopM = NULL, GQpopF = NULL, average.annual = NULL),
nr.traj = 1000, keep.vital.events = FALSE,
fixed.mx = FALSE, fixed.pasfr = FALSE,
lc.for.hiv = TRUE, lc.for.all = TRUE, mig.is.rate = FALSE,
mig.age.method = c("auto", "un", "rc", "user"), my.locations.file = NULL,
replace.output = FALSE, verbose = TRUE, ...)Object of class bayesPop.prediction with the following elements:
Full path to the base directory output.dir.
Sub-directory relative to base.directory with the projections.
The actual number of trajectories of the projections.
Three-dimensional array of projection quantiles (countries x number of quantiles x projection periods). The second dimension corresponds to the following quantiles: \(0.025,0.05,0.1,0.25,0.5,0.75,0.9,0.95,0.975\).
Three-dimensional array of projection mean and standard deviation (countries x 2 x projection periods). First and second matrix of the second dimension, respectively, is the mean and standard deviation, respectively.
Quantiles of male and female projection, respectively. Same structure as quantiles.
Same as traj.mean.sd corresponding to male and female projection, respectively.
Four-dimensional array of age-specific quantiles of male and female projection, respectively (countries x age groups x number of quantiles x projection periods). The same quantiles are used as in quantiles.
Array of age-specific quantiles of male and female projection, respectively, divided by the total population. The dimensions are the same as in quantilesMage.
Vector of time for which historical data was used in the projections.
Vector of projection time periods starting with the present period.
The wpp year used.
List of input data used for the projection.
Content of the inputs argument passed to the function.
Matrix of countries for which projection exists. It contains two columns: code, name.
Vector of age groups.
If TRUE, this object corresponds to a 1x1 prediction, otherwise 5x5.
This component is added by get.pop.prediction and modified and used by pop.map and write.pop.projection.summary. It is an environment for caching and re-using results of expressions.
Logical determining if cache should be modified.
Logical determining if this object is a result of pop.predict or pop.aggregate.
End year of the projection.
First year of the historical data.
Year for which initial population data is to be used.
Year for which WPP data is used. The functions loads a package called wpp\(x\) where \(x\) is the wpp.year and uses the various datasets as default if the corresponding inputs element is missing (see below).
Array of country codes or country names for which a projection is generated. If it is NULL, all available countries are used. If it is NA and there is an existing projection in output.dir and replace.output=FALSE, then a projection is performed for all countries that are not included in the existing projection. Names of countries are matched to those in the UNlocations dataset (or in the dataset loaded from my.locations.file if used).
Output directory of the projection. If there is an existing projection in output.dir and replace.output=TRUE, everything in the directory will be deleted.
Logical. If TRUE it is assumed that this is 1x1 simulation, i.e. one year age groups and one year time periods. Note that this is still an experimental feature!
A list of file names where input data is stored. It contains the following elements (Unless otherwise noted, these are tab delimited ASCII files; Names of default datasets from the corresponding wpp package which are used if the corresponding element is NULL are shown in brackets):
Initial male/female age-specific population (at time present.year) [popM, popF].
Historical data and (optionally) projections of male/female age-specific death rates [mxM, mxF] (see also argument fixed.mx).
Projection of sex ratio at birth. [sexRatio]
Historical data and (optionally) projections of percentage age-specific fertility rate [percentASFR] (see also argument fixed.pasfr).
Migration type and base year of the migration. In addition, this dataset gives information on country's specifics regarding mortality and fertility age patterns as defined in [vwBaseYear]. patterns and mig.type have the same meaning and can be used interchangeably.
Projection and (optionally) historical data of net migration on the same scale as the initital population. There are three ways of defining this quantity, here in order of priority: 1. via migM and migF which should give male and female age-specific migration [migrationM, migrationF]; 2. via migMt and migFt which should give male and female total net migration; 3. via mig which should give the total net migration. For 2. and 3., the totals are disagregated into age-specific migration by applying a Rogers-Castro schedule. For 3., the totals are equally split between sexes. If all of these input items are missing, the migration schedules are reconstructed from total migration counts derived from migration using the age.specific.migration function.
Comma-delimited CSV file with results of female life expectancy (generated using bayesLife, function convert.e0.trajectories, file “ascii_trajectories.csv”). Required columns are “LocID”, “Year”, “Trajectory”, and “e0”. If this element is not NULL, the argument e0F.sim.dir is ignored. If both e0F.file and e0F.sim.dir are NULL, data from the corresponding wpp package is taken, namely the median projections as one trajectory and the low and high variants (if available) as second and third trajectory.
Comma-delimited CSV file containing results of male life expectancy (generated using bayesLife, function convert.e0.trajectories, file “ascii_trajectories.csv”). Required columns are “LocID”, “Year”, “Trajectory”, and “e0”. If this element is not NULL, the argument e0M.sim.dir is ignored. As in the female case, if both e0M.file and e0M.sim.dir are NULL, data from the corresponding wpp package is taken.
Comma-delimited CSV file with results of total fertility rate (generated using bayesTFR, function convert.tfr.trajectories, file “ascii_trajectories.csv”). Required columns are “LocID”, “Year”, “Trajectory”, and “TF”. If this element is not NULL, the argument tfr.sim.dir is ignored. If both tfr.file and tfr.sim.dir are NULL, data from the corresponding wpp package is taken (median and the low and high variants as three trajectories). Alternatively, this argument can be the keyword “median_” in which case only the wpp median is taken.
Simulation directory with results of female life expectancy (generated using bayesLife). It is only used if e0F.file is NULL.
Simulation directory with results of male life expectancy (generated using bayesLife). Alternatively, it can be the string “joint_”, in which case it is assumed that the male life expectancy was projected jointly from the female life expectancy (see joint.male.predict) and thus contained in the e0F.sim.dir directory. The argument is only used if e0M.file is NULL.
Simulation directory with results of total fertility rate (generated using bayesTFR). It is only used if tfr.file is NULL.
Comma-delimited CSV file with male/female age-specific migration trajectories, or total migration trajectories (migtraj). If present, it replaces deterministic projections given by the mig* items. It has a similar format as e.g. e0M.file with columns “LocID”, “Year”, “Trajectory”, “Age” (except for migtraj) and “Migration”. For a five-year simulation, the “Age” column must have values “0-4”, “5-9”, “10-14”, ..., “95-99”, “100+”. In an annual simulation, age is given by a single number between 0 and 100.
Age-specific population counts (male and female) that should be excluded from application of the cohort component method (CCM). It can be used for defining group quarters. These counts are removed from population before the CCM projection and added back afterwards. It is not used when computing vital events on observed data. The datasets should have columns “country_code”, “age” and “gq”. For a five-year simulation, the “age” column should include values “0-4”, “5-9”, “10-14”, ..., “95-99”, “100+”. However, rows with zeros do not need to be included. In an annual simulation, age is given by a single number between 0 and 100.
Character string with values “TFR”, “e0M”, “e0F”. If this is a 5-year simulation, but the inputs of TFR or/and e0 comes from an annual simulation, including the corresponding string here will cause that the TFR or/and e0 trajectories are converted into 5-year averages.
Number of trajectories to be generated. If this number is smaller than the number of available trajectories of the probabilistic components (TFR, life expectancy and migration), the trajectories are equidistantly thinned.
If all of those components contain less trajectories than nr.traj, the value is adjusted to the maximum of available trajectories of the components. For those that have less trajectories than the adjusted number, the available trajectories are re-sampled, so that all components have the same number of trajectories.
Logical. If TRUE age- and sex-specific vital events of births and deaths as well as other objects are stored in the prediction object, see Details.
Logical. If TRUE, it is assumed the dataset of death rates (mxM and mxF) include data for projection years and they are then used instead of the life expectancy.
Logical. If TRUE, it is assumed the dataset on percent age-specific fertility rate (percentASFR) include data for projection years and they are then used instead of computing it on the fly.
Logical controlling if the modified Lee-Carter method should be used
for projection of mortality rates for countries with HIV epidemics. If FALSE, the function hiv.mortmod from the HIV.LifeTables package is used.
Logical controlling if the modified Lee-Carter method should be used
for projection of mortality rates for all countries. If FALSE, the corresponding method is determined by the columns “AgeMortProjMethod1” and “AgeMortProjMethod2” of the vwBaseYear dataset.
Logical determining if migration data are to be interpreted as net migration rates (TRUE) or counts (FALSE, default). It can also be a vector of two logicals, where the first element refers to observed data and the second element refers to predictions. A value of c(FALSE, TRUE) could for example be used if observed data in inputs$migration are counts, and migration trajectories in inputs$migtraj are rates.
If migration is given as totals, this argument determines a method to disaggregate into age-specific migration.
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. The “auto” method (default) uses “un” if wpp.year is 2022; if not and if it is a 5-year simulation, it uses a residual method, otherwise a Rogers-Castro. For the “un” method, Rogers-Castro is used for observed data. Value “user” can be used
for this argument if user-specific schedules are provided in a binary file, given in the item “mig.alt.age.schedule” of the inputs argument. 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.
Name of a tab-delimited ascii file with a set of all locations for which a projection is generated. Use this argument if you are projecting for a country/region that is not included in the standard UNlocations dataset. It must have the same structure.
Logical. If TRUE, everything in the directory output.dir is deleted prior to the prediction.
Logical controlling the amount of output messages.
Additional arguments passed to the underlying function. These can be parallel and nr.nodes for parallel processing and the number of nodes, respectively, as well as further arguments passed for creating a parallel cluster.
Hana Sevcikova, Thomas Buettner, based on code of Nan Li and helpful comments from Patrick Gerland
The population projection is computed using the cohort component method and is based on an algorithm used by the United Nation Population Division (see also Sevcikova et al (2015) in the References below). For each country, one projection is calculated for each trajectory of male and female life expectancy, TFR and possibly migration. This results in a set of trajectories of population projection which forms its posterior distribution. The trajectories of life expectancy and TFR can be given either in its binary form generated by the packages bayesLife and bayesTFR, respectively (as directories e0M.sim.dir, e0F.sim.dir, tfr.sim.dir of the inputs argument), or they can be given as ASCII tables in csv format, see above. The number of trajectories for male and female life expectancy must match, as does for male and female migration.
The projection is generated sequentially country by country. Results are stored in a sub-directory of output.dir called prediction. There is one binary file per country, called totpop_country\(x\).rda, where \(x\) is the country code. It contains six objects: totp, totpf, totpm (trajectories of total population, age-specific female and age-specific male, respectively), totp.hch, totpf.hch, totpm.hch (the UN half-child variant for total population, age-specific female and age-specific male, respectively). Optionally, if keep.vital.events is TRUE, there is an additional file per country, called vital_events_country\(x\).rda, containing the following objects: btm, btf (trajectories for births by age of mothers for male and female child, respectively), deathsm, deathsf (trajectories for age-specific male and female deaths, respectively), asfert (trajectories of age-specific fertility), mxm, mxf (trajectories of male and female age-specific mortality rates), migm, migf (if used, these are trajectories of male and female age-specific migration), btm.hch, btf.hch, deathsm.hch, deathsf.hch, asfert.hch, mxm.hch, mxf.hch (the UN half-child variant for age- and sex-specific births, deaths, fertility rates and mortality rates). An object of class bayesPop.prediction is stored in the same directory in a file prediction.rda. It is updated every time a country projection is finished.
See pop.trajectories for extracting trajectories.
To access a previously stored prediction object, use get.pop.prediction.
H. Sevcikova, A. E. Raftery (2016). bayesPop: Probabilistic Population Projections. Journal of Statistical Software, 75(5), 1-29. doi:10.18637/jss.v075.i05
A. E. Raftery, N. Li, H. Sevcikova , P. Gerland, G. K. Heilig (2012). Bayesian probabilistic population projections for all countries. Proceedings of the National Academy of Sciences 109:13915-13921.
P. Gerland, A. E. Raftery, H. Sevcikova, N. Li, D. Gu, T. Spoorenberg, L. Alkema, B. K. Fosdick, J. L. Chunn, N. Lalic, G. Bay, T. Buettner, G. K. Heilig, J. Wilmoth (2014). World Population Stabilization Unlikely This Century. Science 346:234-237.
H. Sevcikova, N. Li, V. Kantorova, P. Gerland and A. E. Raftery (2015). Age-Specific Mortality and Fertility Rates for Probabilistic Population Projections. arXiv:1503.05215. https://arxiv.org/abs/1503.05215
pop.trajectories.plot, pop.pyramid, pop.trajectories, get.pop.prediction, age.specific.migration
if (FALSE) {
sim.dir <- tempfile()
# Countries can be given as a combination of numerical codes and names
pred <- pop.predict(countries=c("Netherlands", 218, "Madagascar"), nr.traj=3,
output.dir=sim.dir)
pop.trajectories.plot(pred, "Ecuador", sum.over.ages=TRUE)
unlink(sim.dir, recursive=TRUE)
}Run the code above in your browser using DataLab