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" <biostatmark@gmail.com>
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

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" <biostatmark@gmail.com>
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

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

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

Vignettes

burkina-faso-females

Author(s)

Mark C. Wheldon

Maintainer: "Mark C. Wheldon" <biostatmark@gmail.com>

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.

Metropolis Acceptance Ratio

Description

Internal function of the popReconstruct package.

Author(s)

Mark C. Wheldon

Metropolis Acceptance Ratio

Description

Internal function of the popReconstruct package.

Author(s)

Mark C. Wheldon

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)

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)

Inverse Gamma Density

Description

Internal function of the popReconstruct package.

Author(s)

Mark C. Wheldon

Inverse logit.

Description

Internal function of the popReconstruct package.

Author(s)

Mark C. Wheldon

Logit.

Description

Internal function of the popReconstruct package.

Author(s)

Mark C. Wheldon

Name columns.

Description

Internal function of the popReconstruct package.

Author(s)

Mark C. Wheldon

Inverse Gamma sample.

Description

Internal function of the popReconstruct package.

Author(s)

Mark C. Wheldon

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)

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)

Log likelihood.

Description

Internal function of the popReconstruct package.

Author(s)

Mark C. Wheldon

Log Posterior.

Description

Internal function of the popReconstruct package.

Author(s)

Mark C. Wheldon

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)

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.

See Also

popRecon.ccmp.female, net.number.migrants

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

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)

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

See Also

popRecon.ccmp.female, make.leslie.matrix

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)

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

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.

See Also

make.leslie.matrix, net.number.migrants

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

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

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.

Vignettes

burkina-faso-females

Author(s)

Mark C. Wheldon

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.

Census Years.

Description

Internal function of the popReconstruct package.

Author(s)

Mark C. Wheldon