bayesPop (version 5.2-2)

pop.predict: Probabilistic Population Projection

Description

The function generates trajectories of probabilistic population projection for all countries for which input data is available, or any subset of them.

Usage

pop.predict(end.year = 2100, start.year = 1950, present.year = 2010, 
    wpp.year = 2012, countries = NULL, 
    output.dir = file.path(getwd(), "bayesPop.output"),
    inputs = list(popM=NULL, popF=NULL, mxM=NULL, mxF=NULL, srb=NULL,
        pasfr=NULL, mig.type=NULL, migM=NULL, migF=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), 
    nr.traj = 1000, keep.vital.events = FALSE, fixed.mx = FALSE,
    replace.output = FALSE, verbose = TRUE)

Arguments

end.year

End year of the projection.

start.year

First year of the historical data.

present.year

Year for which initial population data is to be used.

wpp.year

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).

countries

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=FAL

output.dir

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.

inputs

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 e

nr.traj

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 c

keep.vital.events

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.

fixed.mx

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.

replace.output

Logical. If TRUE, everything in the directory output.dir is deleted prior to the prediction.

verbose

Logical controlling the amount of output messages.

Value

• Object of class bayesPop.prediction with the following elements:
• base.directory
  Full path to the base directory output.dir.
• output.directory
  Sub-directory relative to base.directory with the projections.
• nr.traj
  The actual number of trajectories of the projections.
• quantiles
  Three-dimensional array of projection quantiles (countries x number of quantiles x projection periods). The second dimension corresponds to the following quantiles: $0,0.025,0.05,0.1,0.2,0.25,0.3,0.4,0.5,0.6,0.7,0.75,0.8,0.9,0.95,0.975,1$.
• traj.mean.sd
  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.
• quantilesM, quantilesF
  Quantiles of male and female projection, respectively. Same structure as quantiles.
• traj.mean.sdM, traj.mean.sdF
  Same as traj.mean.sd corresponding to male and female projection, respectively.
• quantilesMage, quantilesFage
  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.
• quantilesPropMage, quantilesPropFage
  Array of age-specific quantiles of male and female projection, respectively, divided by the total population. The dimensions are the same as in quantilesMage.
• estim.years
  Vector of time for which historical data was used in the projections.
• proj.years
  Vector of projection time periods starting with the present period.
• wpp.year
  The wpp year used.
• inputs
  List of input data used for the projection.
• function.inputs
  Content of the inputs argument passed to the function.
• countries
  Matrix of countries for which projection exists. It contains two columns: code, name.
• ages
  Vector of age groups.
• cache
  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.
• write.to.cache
  Logical determining if cache should be modified.
• is.aggregation
  Logical determining if this object is a result of pop.predict or pop.aggregate.

Details

The population projection is computed using the Cohort Component method and is based on an algorithm used by the United Nation Population Division. 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.

To access a previously stored prediction object, use get.pop.prediction.

References

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.

See Also

pop.trajectories.plot, pop.pyramid, get.pop.prediction

Examples

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)