Package 'popReconstruct' reference manual

Title:	Reconstruct Human Populations of the Recent Past
Description:	Implements the Bayesian hierarchical model described by Wheldon, Raftery, Clark and Gerland (see: <doi:10.1080/01621459.2012.737729>) for simultaneously estimating age-specific population counts, fertility rates, mortality rates and net international migration flows, at the national level.
Authors:	Mark C. Wheldon
Maintainer:	"Mark C. Wheldon" <[email protected]>
License:	GPL-3
Version:	1.0-6
Built:	2024-12-16 06:54:30 UTC
Source:	CRAN

Reconstruct Human Populations of the Recent Past

Description

popReconstruct is a package for reconstructing populations of the recent past. It simultaneously estimates age-specific population counts, fertility rates, mortality rates and net international migration flows from fragmentary data, and incorporates measurement error. Informative priors are required for vital rates, migration rates, population counts at baseline, and their respective measurement error variances. Inference is based on the joint posterior probability distribution which yields fully probabilistic interval estimates. A sample from this distribution is drawn using a Markov chain Monte Carlo algorithm.

Details

The DESCRIPTION file:

Package:	popReconstruct
Type:	Package
Title:	Reconstruct Human Populations of the Recent Past
Version:	1.0-6
Date:	2019-11-21
Author:	Mark C. Wheldon
Maintainer:	"Mark C. Wheldon" <[email protected]>
Description:	Implements the Bayesian hierarchical model described by Wheldon, Raftery, Clark and Gerland (see: <doi:10.1080/01621459.2012.737729>) for simultaneously estimating age-specific population counts, fertility rates, mortality rates and net international migration flows, at the national level.
License:	GPL-3
Depends:	coda
Suggests:	ggplot2, reshape, gdata
NeedsCompilation:	no
Packaged:	2019-11-22 00:59:39 UTC; markw
Repository:	CRAN
Date/Publication:	2019-11-27 16:50:02 UTC

Index of help topics:

burkina_faso_females    Data for the Vignette burkina-faso-females
life.expectancy.stationary
                        Life Expectancy At Birth in a Stationary
                        Population
make.leslie.matrix      Make Leslie Matrix
net.number.migrants     Calculate Net Number of Migrants
popRecon.ccmp.female    Female Dominant Cohort Component Projection
popRecon.sampler        MCMC Sampler for the popReconstruct Package
popReconstruct-package
                        Reconstruct Human Populations of the Recent
                        Past

Further information is available in the following vignettes:

`burkina-faso-females`	Burkina Faso Females Reconstruction (source, pdf)

See the vignette burkina-faso-females for a detailed illustration.

Vignettes

burkina-faso-females

Author(s)

Mark C. Wheldon

Maintainer: "Mark C. Wheldon" <[email protected]>

References

Wheldon, M. C., Raftery, A. E., Clark, S. J. and Gerland, P. (2013). Reconstructing Past Populations With Uncertainty From Fragmentary Data. Journal of the American Statistical Association, 108:501, 96-110. doi:10.1080/01621459.2012.737729.

Data for the Vignette burkina-faso-females

Description

Contains initial estimates of fertility, mortality, migration and population counts for the reconstruction of the female population of Burkina Faso from 1960–2000. See the vignette burkina-faso-females for an illustration of its use.

Usage

data(burkina_faso_females)data(burkina_faso_females)

Format

The format is: chr "burkina-faso-females.RData"

Details

The dataset contains two lists.

burkina.faso.females has components:

fertility.rates: Matrix of initial estimates of average annual single-year age-specific fertility rates.
survival.proportions: Matrix of initial estimates of age-specific survival proportions.
migration.proportions: Matrix of initial estimates of age-specific average annual net migration as a proportion of the size of the same age-group in the receiving population.
baseline.pop.counts: Single column matrix of age-specific population counts in the baseline year (1960).
census.pop.counts: Matrix of age-specific census counts in years after the baseline year (1975, 1985, 1995, 2005).

burkina.faso.prop.vars has components fert.rate, surv.prop, mig.prop, population.count which contain variances for the Gaussian densities used as proposals in the random walk Metropolis-Hastings algorithm used to sample from the joint posterior.

Vignettes

burkina-faso-females

References

Wheldon, M. C., Raftery, A. E., Clark, S. J. and Gerland, P. (2011) Estimating Demographic Parameters with Uncertainty. Working Paper No. 108, Center for Statistics and the Social Sciences, University of Washington, Seattle. http://www.csss.washington.edu/Papers/wp108.pdf.

Examples

data(burkina_faso_females.RData)
data(burkina_faso_females.RData)

Life Expectancy At Birth in a Stationary Population

Description

Calculates life expectancy at birth from age-specific survival proportions in a stationary population. See the vignette burkina-faso-females for an illustration of its use.

Usage

life.expectancy.stationary(z)
life.expectancy.stationary(z)

Arguments

`z`	Vector of age specific survival proportions for age groups of width five years.

Details

This function calculates the life expectancy at birth in a stationary population subject to the survival proportions supplied.

Value

Life expectancy at birth.

Vignettes

burkina-faso-females

Author(s)

Mark C. Wheldon

Examples


## Can take a few minutes

## Not run: data(burkina_faso_females)
life.expectancy.stationary(burkina.faso.females$survival.proportions[,1])

## End(Not run)

## Can take a few minutes

## Not run: data(burkina_faso_females)
life.expectancy.stationary(burkina.faso.females$survival.proportions[,1])

## End(Not run)

Make Leslie Matrix

Description

Constructs the Leslie Matrix needed for cohort component projection.

Usage

make.leslie.matrix(pop, surv, fert, srb = 1.05, age.int = 5, label.dims = FALSE)
make.leslie.matrix(pop, surv, fert, srb = 1.05, age.int = 5, label.dims = FALSE)

Arguments

`pop`	Population count at baseline.
`surv`	Survivorship probabilities: the probability of reaching the age at the start of the interval. The first row should be nL0/(n*l0). The last row is survival for age.int years in the open interval.
`fert`	Matrix of age specific fertility rates NOT yet mulitplied by age.int.
`srb`	Sex ratio at birth (matrix or scalar).
`age.int`	Width of the age intervals; needed for correct interpretation of survival probabilities and fertility rates.
`label.dims`	Should row and column names be set? Aesthetic.

Details

This function is used in the calculation of the average annual net number of migrants. See the vignette burkina-faso-females for an example of its use.

Value

A Leslie matrix as a matrix object.

Vignettes

burkina-faso-females

Author(s)

Mark C. Wheldon

References

Preston, S. H., Heuveline, P. and Guillot, M. (2001) Demography, chapter 6. Malden, MA: Blackwell.

Examples

example(popRecon.ccmp.female)

(Lk <- make.leslie.matrix(pop = pop.input.mat[,1]
                       ,surv = burkina.faso.females$survival.proportions[,1]
                       ,fert = burkina.faso.females$fertility.rates[,1]
                       ,srb = 1.05
                       ,age.int = 5))
example(popRecon.ccmp.female)

(Lk <- make.leslie.matrix(pop = pop.input.mat[,1]
                       ,surv = burkina.faso.females$survival.proportions[,1]
                       ,fert = burkina.faso.females$fertility.rates[,1]
                       ,srb = 1.05
                       ,age.int = 5))

Calculate Net Number of Migrants

Description

Calculates the net number of migrants from two population vectors and the Leslie matrix describing the amount of change attributable to fertility and mortality.

Usage

net.number.migrants(n1, n2, L)
net.number.migrants(n1, n2, L)

Arguments

`n1`	Population vector at time $t$ .
`n2`	Populatin vectors at time $t+\delta$ .
`L`	The Leslie matrix (see `make.leslie.matrix`).

Details

This function is used in the calculation of the average annual net number of migrants. See the vignette burkina-faso-females for an example of its use.

Value

Vector of net number of migrants in each age group to the population between times $t$ and $t+\delta$ .

Vignettes

burkina-faso-females

Author(s)

Mark C. Wheldon

Examples


## Can take several minutes to run

## Not run: 
example(popRecon.ccmp.female)

example(make.leslie.matrix)

net.number.migrants(n1 = pop.input.mat[,k]
                                ,n2 = pop.input.mat[,k+1]
                                ,L = Lk)

## End(Not run)
## Can take several minutes to run

## Not run: 
example(popRecon.ccmp.female)

example(make.leslie.matrix)

net.number.migrants(n1 = pop.input.mat[,k]
                                ,n2 = pop.input.mat[,k+1]
                                ,L = Lk)

## End(Not run)

Female Dominant Cohort Component Projection

Description

Implements the deterministic female dominant cohort component method of population projection.

Usage

popRecon.ccmp.female(pop, surv, fert, srb = 1.05,
mig, proj.steps, age.int = 5, label.dims = FALSE, base.year = "1960")
popRecon.ccmp.female(pop, surv, fert, srb = 1.05,
mig, proj.steps, age.int = 5, label.dims = FALSE, base.year = "1960")

Arguments

`pop`	Population count at baseline.
`surv`	Survivorship probabilities: the probability of reaching the age at the start of the interval.
`fert`	Matrix of average annual, single-year age-specific fertility rates (see Details).
`srb`	Sex ratio at birth matrix
`mig`	Net number of migrants as a proportion of prev time period's population.
`proj.steps`	Number of time periods to project forward. If missing, set to ncol(fert).
`age.int`	Width of the age intervals; needed for correct interpretation of survival probabilities and fertility rates.
`label.dims`	Should row and column names be set? Aesthetic.
`base.year`	Baseline year for popualtion projections (aesthetic).

Details

The first row of surv should be ${}_nL_0/(nl_0)$ , where ${}_nL_0$ and $l_0$ are the usual life table parameters. The last row is survival for age.int years in the open interval.

The elements of the fert argument should not be multiplied by age.int. In other words, the average annual total fertility rates (TFRs) corresponding to the columns of fert are age.int * colSums(fert).

The elements of mig give the average annual net number of migrants, as proportion of the size of the same age-group in the receiving population. Thus, the total net number of migrants to the population over the period

Value

A matrix of projected population counts, age groups as rows, time periods as columns.

Vignettes

burkina-faso-females

Author(s)

Mark C. Wheldon

References

Preston, S. H., Heuveline, P. and Guillot, M. (2001) Demography, chapter 6. Malden, MA: Blackwell.

Examples


data(burkina_faso_females)

(pop.input.mat <-
    popRecon.ccmp.female(pop=burkina.faso.females$baseline.pop.counts
                      ,surv=burkina.faso.females$survival.proportions
                      ,fert=burkina.faso.females$fertility.rates
                      ,mig=burkina.faso.females$migration.proportions
                      ))
data(burkina_faso_females)

(pop.input.mat <-
    popRecon.ccmp.female(pop=burkina.faso.females$baseline.pop.counts
                      ,surv=burkina.faso.females$survival.proportions
                      ,fert=burkina.faso.females$fertility.rates
                      ,mig=burkina.faso.females$migration.proportions
                      ))

MCMC Sampler for the popReconstruct Package

Description

Draws an MCMC sample from the joint posterior distribution of age-specific fertility rates, survival and migration proportions and baseline population counts.

Usage

popRecon.sampler(n.iter, burn.in = 0, thin.by = 1, al.f = 1, be.f = 0.0109,
al.s = 1, be.s = 0.0109, al.g = 1, be.g = 0.0436, al.n = 1, be.n = 0.0109,
mean.f, mean.s, mean.g, mean.b, start.f = mean.f, start.s = mean.s,
start.g = mean.g, start.b = mean.b, start.sigmasq.f = 5, start.sigmasq.s = 5,
start.sigmasq.g = 5, start.sigmasq.n = 5, pop.data, prop.vars,
ccmp.function = popRecon.ccmp.female, proj.periods = ncol(mean.f),
age.size = 5, verb = FALSE, s.tol = 10^(-10))
popRecon.sampler(n.iter, burn.in = 0, thin.by = 1, al.f = 1, be.f = 0.0109,
al.s = 1, be.s = 0.0109, al.g = 1, be.g = 0.0436, al.n = 1, be.n = 0.0109,
mean.f, mean.s, mean.g, mean.b, start.f = mean.f, start.s = mean.s,
start.g = mean.g, start.b = mean.b, start.sigmasq.f = 5, start.sigmasq.s = 5,
start.sigmasq.g = 5, start.sigmasq.n = 5, pop.data, prop.vars,
ccmp.function = popRecon.ccmp.female, proj.periods = ncol(mean.f),
age.size = 5, verb = FALSE, s.tol = 10^(-10))

Arguments

`n.iter`	Number of iterations to save.
`burn.in`	Number of burn-in iterations; not saved.
`thin.by`	Thinning parameter; save every 'thin'th iteration.
`al.f`	Shape parameter of the distribution of the variance of the age-specific ferility rate initial estimates.
`be.f`	Scale parameter of the distribution of the variance of the age-specific ferility rate initial estimates.
`al.s`	Shape parameter of the distribution of the variance of the age-specific survival proportion initial estimates.
`be.s`	Scale parameter of the distribution of the variance of the age-specific survival proportion initial estimates.
`al.g`	Shape parameter of the distribution of the variance of the age-specific migration proportion initial estimates.
`be.g`	Scale parameter of the distribution of the variance of the age-specific migration proportion initial estimates.
`al.n`	Shape parameter of the distribution of the variance of the age-specific population count initial estimates and census counts.
`be.n`	Scale parameter of the distribution of the variance of the age-specific population count initial estimates and census counts.
`mean.f`	Matrix of initial estimates of age-specific fertility rates with age groups as rows, time periods as columns.
`mean.s`	Matrix of initial estimates of age-specific survival proportions with age groups as rows, time periods as columns.
`mean.g`	Matrix of initial estimates of age-specific migration proportions with age groups as rows, time periods as columns.
`mean.b`	Matrix of initial estimates of age-specific baseline population counts with age groups as rows, time periods as columns.
`start.f`	Matrix of MCMC start values of age-specific fertility rates with age groups as rows, time periods as columns.
`start.s`	Matrix of MCMC start values of age-specific survival proportions with age groups as rows, time periods as columns.
`start.g`	Matrix of MCMC start values of age-specific migration proportions with age groups as rows, time periods as columns.
`start.b`	Matrix of MCMC start values of age-specific baseline population counts with age groups as rows, time periods as columns.
`start.sigmasq.f`	MCMC start value for variance of the age-specific fertility rate initial estimates.
`start.sigmasq.s`	MCMC start value for variance of the age-specific survival proportions initial estimates.
`start.sigmasq.g`	MCMC start value for variance of the age-specific migration proportions initial estimates.
`start.sigmasq.n`	MCMC start value for variance of the age-specific baseline count initial estimates.
`pop.data`	Matrix fo census counts, with age groups as rows, time periods as columns.
`prop.vars`	List of matrices of variances for Gaussian Metropolis random walk proposals. Components are
`ccmp.function`	Function to do cohort component projection.
`proj.periods`	Number of age.size-year periods to over which to do the reconstruction, beginning at the baseline year.
`age.size`	Width of the age groups and time periods in years.
`verb`	Logical; should progress messages be printed.
`s.tol`	A tolerance parameter to stop over-/under-flow when taking logits of survival proportions.

Details

This is the main function of the popReconstruct package. It takes initial estimates of age-specific vital rates, migration proportions and population counts in the baseline year and draws an MCMC sample from the joint posterior distribution defined in Wheldon et al. (2011). See the vignette burkina-faso-females for an extended illustration of its use.

Value

A list with components;

`fert.rate.mcmc`	mcmc object containing MCMC chains for age-specific fertility rates.
`surv.prop.mcmc`	mcmc object containing MCMC chains for age-specific survival proportions.
`mig.prop.mcmc`	mcmc object containing MCMC chains for age-specific migration proportions.
`baseline.count.mcmc`	mcmc object containing MCMC chains for age-specific baseline counts.
`lx.mcmc`	mcmc object containing MCMC chains for age-specific population counts at years subsequent to baseline.
`variances.mcmc`	mcmc object containing MCMC chains for the vital rate variance parameters.
`alg.stats`	“algorithm statistics”; a list with components `acceptance.proportions` giving Metropolis acceptance proportions for each vital rate parameter, `pop.went.negative` giving the number of times Metropolis proposals resulted in negative poplation counts, `run.time` giving the time taken to run the sampler and some other, as yet undocumented, components.
`fixed.params`	A list containing the initial estimates and hyperparmaters of the variance distributions.
`start.vals`	A list containing Metropolis start values for the vital rates, migration proportions, baseline counts and variance parameters.
`alg.params`	“algorithm parameters”; a list returning some of the arguments supplied for this run, saved for later reference. For example, Metropolis proposal variances (`prop.vars`) and the number of iterations (`iters`) are stored here.

Package 'popReconstruct'

Help Index

Reconstruct Human Populations of the Recent Past

Description

Details

Vignettes

Author(s)

References

Data for the Vignette burkina-faso-females

Description

Usage

Format

Details

Vignettes

References

Examples

Life Expectancy At Birth in a Stationary Population

Description

Usage

Arguments

Details

Value

Vignettes

Author(s)

Examples

Make Leslie Matrix

Description

Usage

Arguments

Details

Value

Vignettes

Author(s)

References

See Also

Examples

Calculate Net Number of Migrants

Description

Usage

Arguments

Details

Value

Vignettes

Author(s)

See Also

Examples

Female Dominant Cohort Component Projection

Description

Usage

Arguments

Details

Value

Vignettes

Author(s)

References

See Also

Examples

MCMC Sampler for the popReconstruct Package

Description

Usage

Arguments

Details

Value

Vignettes

Author(s)

References