Demographic analysis in R

Description

demogR is a collection of functions to construct and analyze age-structured population models. For a list of functions, type: help(package="demogR").

Details

Author(s)

James Holland Jones
Department of Anthropological Sciences
Stanford University

Contributor: Jim Oeppen, Southern Denmark University, Odense, Denmark

Maintainer: Hana Sevcikova <hanas@uw.edu>

References

Caswell, H. 2001. Matrix population models: Construction, analysis, and interpretation. 2nd ed. Sunderland, MA: Sinauer.

Coale, A.J. 1972. The growth and structure of human populations: A mathematical investigation. Princeton: Princeton University Press.

Jone, J.H. (2007). demogR: A Package for the Construction and Analysis of Age-structured Demographic Models in R. Journal of Statistical Software, 22(10), 1-28.

Keyfitz, N. 1977. Introduction to the mathematics of populations. 2nd ed. Menlo Park: Addison-Wesley.

Keyfitz, N., and H. Caswell. 2005. Applied mathematical demography. 3rd ed. New York: Springer.

Leslie, P.H. 1945. On the use of matrices in certain population mathematics. Biometrics 33:213-245.

Preston, S.H., P. Heuveline, and F. Guillot. 2001. Demography: Measuring and modeling population processes. Oxford: Blackwell.

Tuljapurkar, S. 1990. Population dynamics in variable environments. Vol. 85, Lecture notes in biomathematics. Berlin: Springer-Veralg.

Caclulate net reproduction number from a demographic projection matrix

Description

Calculate the net reproduction number (R_0) from an age or stage-classified demographic projection matrix.

Usage

calc.ro(A, N.out = FALSE)

Arguments

Details

Calculates the net reproduction number (R_0) from an age or stage-classified demographic projection matrix by first decomposing the k x k projection matrix A into two component matrices, T and F. T collects the transitions between life-cycle stages while F collects the fertility transitions. For an age-classified Leslie matrix, T will contain only the sub-diagonal of A and F will contain only the first row of A. The fundamental matrix is given by N = (I-T)^{-1}, where I is a k x k identity matrix. R_0 is the leading eigenvalue of the matrix FN.

Value

If the (default) option N.out=FALSE is used, the net reproduction number is returned as a single value. If N.out=TRUE, the returned value is a list of two items:

...

Author(s)

James Holland Jones

References

Caswell, H. 2001. Matrix population models: construction, analysis, and interpretation, Second edition. Sinauer, Sunderland, Massachusetts, USA.

See Also

see leslie.matrix

Examples

## Create a Leslie matrix
Px <- c(0.77, 0.95, 0.98, 0.97)
Fx <- c(0,0,1,1.2,1)
L <- odiag(Px,-1)
L[1,] <- Fx
## Calculate R_0
calc.ro(L)
## look at the fundamental matrix
calc.ro(L, N.out=TRUE)

Coale-Demeny Model Life Tables

Description

Coale-Demeny regional model life tables

Usage

cdmltw(sex = "F")
cdmlte(sex = "F")
cdmlts(sex = "F")
cdmltn(sex = "F")

Arguments

Details

Provides region-specific model life tables for 25 different levels of mortality, indexed by life expectancy at age 10 (with 1 being the lowest and 25 being the highest life expectancy at age 10).

The regions are West (cdmltw), East (cdmlte), South (cdmlts), and North (cdmltn).

Value

A list containing two 21 element vectors, one 25 element vector and eight 25 x 21 matrices: 25 mortality levels by 21 age classes. The eight matrices contain the standard columns of a life table for each mortality level:

Author(s)

Kenneth Wachter, Department of Demography, University of California, Berkeley.

Modified by James Holland Jones, Department of Anthropological Sciences, Stanford University

Corrected by Jim Oeppen, Southern Denmark University, Odense, Denmark

References

Coale, A., P. Demeny, and B. Vaughn. 1983. Regional model life tables and stable populations. 2nd ed. New York: Academic Press.

See Also

life.table

Examples

## Generate West model life table family for females
Wf <- cdmltw()

## Plot survivorship for the 25 levels
plot(Wf$age,Wf$lx[1,], type="l", xlab="Age", ylab="Survivorship")
for(i in 2:25) lines(Wf$age, Wf$lx[i,])

coale

Description

Utility used by life.table to graduate the person-years lived by those dying in the interval by the method of Coale and Demeny.

Usage

coale(b1, b4, nMx)

Arguments

Details

Utility function called by life.table.

Value

The first two values (age classes 0-1 and 1-5) of the nax column of a period life table.

References

Coale, A., P. Demeny, and B. Vaughn. 1983. Regional model life tables and stable populations. 2nd ed. New York: Academic Press.

See Also

life.table

Examples

data(goodman)
vlt1 <- with(goodman, life.table(x=age, nKx=ven.nKx, nDx=ven.nDx, type="cd"))

cohort

Description

Dummy function called in life.table.

Usage

cohort(width12)

Arguments

Details

This is essentially a place-holder function used when passing the option type="cohort" to life.table.

Value

A two element vector representing the first two values of the nax column of the life table.

See Also

life.table

Examples

data(thar)
thar.lt <- with(thar, life.table(x=age, nDx=deaths, nKx=count, 
    type="cohort", iwidth=1, width12=c(1,1)))
thar.lt

eigen.analysis

Description

Calculates the asymptotic growth rate and related quantities from a demographic projection matrix.

Usage

eigen.analysis(A)

Arguments

Details

Calculates the asymptotic growth rate (lambda) of a population described by demographic projection matrix A. The asymptotic growth rate of the population is given by the dominant eigenvalue of the projection matrix. By the Perron-Frobenius Theorem, this eigenvalue is guaranteed to be real, positive and strictly greater than all the other eigenvalues if the matrix A is non-negative, irreducible, and primitive (for details see Caswell (2001)).

Also calculates the damping ratio (rho), eigenvalue sensitivities, eigenvalue elasticities, the stable age distribution (for the communicating parts of the life cycle), and scaled reproductive values.

The damping ratio is the ratio of the dominant eigenvalue and the absolute value of the second eigenvalue. rho is a measure of the rate of convergence to the stable age-distribution. A population characterized by damping ratio rho will converge asymptotically to the stable age distribution exponentially with rate at least as fast as log(rho). Clearly, a population already at or very near the stable age distribution will converge faster, but rho provides an upper bound.

The eigenvalue sensitivities are the partial derivatives of lambda with respect to a perturbation in matrix element a_{ij}. The sensitivities measure the selection gradient on the life-cycle (Lande 1982). The eigenvalue elasticities are scaled to be proportional sensitivities of lambda to a perturbation in a_{ij}. Elasticities have a number of desirable properties including, their sum across all life-cycle transitions is unity and the sum of the elasticities of all incoming arcs to a life-cycle stage must equal the sum of all outgoing arcs (van Groenendael et al 1994).

The stable age distribution is normalized to represent the proportion in each of the communicating age classes. If the population is characterized by post-reproductive survival (and hence age classes that do not communicate with the rest of the life cycle graph), then other methods should be used to calculate to stable distribution. For example, from classic stable population theory, we know that the stable age distribution of the population c(x) is given by the relationship:

c(x) = b l(x) exp(-r*x)

where b is the gross birth rate, l(x) is survivorship to age x and r is the rate of increase of the population (=log(lambda)). See Coale (1972) or Preston et al. (2001) for details.

The age-specific reproductive values are normalized so that the reproductive value of the first age class is unity. Problems associated with post-reproductive survival are irrelevant for reproductive value since the reproductive value of post-reproductive individuals is, by definition, zero.

Value

A list with six components:

References

Caswell, H. 2001. Matrix population models: Construction, analysis, and interpretation. 2nd ed. Sunderland, MA: Sinauer.

Coale, A.J. 1972. The growth and structure of human populations: A mathematical investigation. Princeton: Princeton University Press.

Lande, R. A. 1982. A quantitative genetic theory of life history evolution. Ecology 63:607-615.

van Groenendael, J., H. De Kroon, S. Kalisz, and S. Tuljapurkar. 1994. Loop analysis: Evaluating life history pathways in population projection matrices. Ecology 75 (8):2410-2415.

See Also

leslie.matrix, secder

Examples

data(goodman)
ven <- with(goodman, life.table(x=age, nKx=ven.nKx, nDx=ven.nDx))
ven.mx <- with(goodman, ven.bx/ven.nKx)
A <- leslie.matrix(lx=ven$nLx,mx=ven.mx)

usa <- with(goodman, life.table(x=age, nKx=usa.nKx, nDx=usa.nDx))
usa.mx <- with(goodman, usa.bx/usa.nKx)
B <- leslie.matrix(lx=usa$nLx,mx=usa.mx)

eav <- eigen.analysis(A)
eau <- eigen.analysis(B)

## compare rates of increase

eav$lambda1
eau$lambda1

## compare stable age distributions for Venezuela and the USA
op <- par(no.readonly = TRUE)
age <- seq(0,50,by=5)
par(mfrow=c(1,2))
barplot(eav$stable.age, names.arg=age, 
	     horiz=TRUE, 
	     col="grey", 
	     ylab="Age")
barplot(eau$stable.age, names.arg=age[-11], 
	     horiz=TRUE, 
	     col="blue", 
	     ylab="Age", 
	     xlim=c(0,0.2))

par(op)

## Compare reproductive values for Venezuela and the USA

plot(age, eav$repro.value, type="l", xlab="Age", ylab="Reproductive Value")
lines(age[-11], eau$repro.value, lty=2)
legend("topright", c("Venezuela (1965)", "USA (1967)"), lty=c(1,2))

elassens

Description

Calculates the partial derivatives of the eigenvalue elasticities of a demographic projection matrix.

Usage

elassens(A, k, l)

Arguments

Details

See Caswell (2001) section 9.7.1.

Value

A matrix of class "leslie.matrix".

References

Caswell, H. 2001. Matrix population models: Construction, analysis, and interpretation. 2nd ed. Sunderland, MA: Sinauer.

See Also

secder, leslie.matrix, eigen.analysis

Examples

data(goodman)
mlt <- with(goodman, life.table(x=age, nDx=mad.nDx, nKx=mad.nKx))
mx <- goodman$mad.bx/goodman$mad.nKx

##  make the Leslie matrix
mad <- leslie.matrix(lx=mlt$lx, mx=mx)

## now calculate the sensitivities of the elasticitities with respect
##to infant survival

es21 <- elassens(mad,2,1)

fullsecder

Description

Calculates the second derivatives of the dominant eigenvalue of a square matrix, A, with respect to all non-zero elements of A.

Usage

fullsecder(A)

Arguments

Details

Produces a matrix the columns of which are re-shaped matrices of second derivatives of the dominant eigenvalue of the projection matrix A with respect to each non-zero element in A.

See Caswell (1996, 2001) for details on second derivatives of the dominant eigenvalue.

Value

A square matrix. If A is a Leslie matrix of rank k, then the maximum rank of the resulting matrix is 2k-1 (since there are at most k non-zero fertilities and k-1 survival probabilities in a k x k Leslie matrix).

References

Caswell, H. 1996. Second derivatives of population growth rate: Calculation and applications. Ecology 77 (3):870-879.

Caswell, H. 2001. Matrix population models: Construction, analysis, and interpretation. 2nd ed. Sunderland, MA: Sinauer.

See Also

secder, elassens, eigen.analysis, stoch.sens

Examples

## eigenvalue second derivatives of the US projection matrix from 1967
data(goodman)
ult <- with(goodman, life.table(x=age, nKx=usa.nKx, nDx=usa.nDx))
mx <- goodman$usa.bx/goodman$usa.nKx
usa <- leslie.matrix(lx=ult$nLx,mx=mx)

fs <- fullsecder(usa)

## plot the survival cross-second derivatives of lambda with respect
## to infant survival

plot( seq(0,40,by=5), fs["21",10:18], type="l", 
	 xlab="Age (j)", 
	 ylab=expression(paste(partialdiff^2 , lambda, "/", 
	 partialdiff, P[1] , partialdiff, P[j])))
abline(h=0,lty=3)

gen.time

Description

Calculates the generation time for an age or stage-classified demographic projection matrix.

Usage

gen.time(A, peryear = 5)

Arguments

Details

Calculates the generation time (T) for an age or stage-classified demographic projection matrix using the identity

R_0 = \exp(r*T)

where R_0 is the net reproduction number and r is the intrinsic rate of increase (=log(lambda)).

Generation time is the amount of time that it takes a typical female to produce R_0 offspring or, equivalently, the amount of time it takes a population growing with instantaneous rate r to increase by a factor of R_0.

Value

The generation time implied by the demographic projection matrix.

Note

Calls function calc.ro, which calculates R_0 from the fundamental matrix of the Markov transition matrix (Caswell 2001).

References

Keyfitz, N., and H. Caswell. 2005. Applied mathematical demography. 3rd ed. New York: Springer.

Caswell, H. 2001. Matrix population models: Construction, analysis, and interpretation. 2nd ed. Sunderland, MA: Sinauer.

Preston, S.H., P. Heuveline, and F. Guillot. 2001. Demography: Measuring and modeling population processes. Oxford: Blackwell.

See Also

calc.ro, eigen.analysis

Examples

## compare generation times from two populations with very different
## R_0 values
data(goodman)
ven <- with(goodman, life.table(x=age, nKx=ven.nKx, nDx=ven.nDx))
ven.mx <- with(goodman, ven.bx/ven.nKx)
A <- leslie.matrix(lx=ven$nLx,mx=ven.mx)

usa <- with(goodman, life.table(x=age, nKx=usa.nKx, nDx=usa.nDx))
usa.mx <- with(goodman, usa.bx/usa.nKx)
B <- leslie.matrix(lx=usa$nLx,mx=usa.mx)

gen.time(A)
gen.time(B)

Demographic data from Venezuela, Madagascar and the United States in the late 1960s

Description

Aggregate vital registration data for female from Venezuela (1965), Madagascar (1966), and the United States (1967) used in Goodman, Keyfitz, and Pullam (1974).

Usage

data(goodman)

Format

A data frame with 19 observations on the following 10 variables.

age

age classes

ven.nKx

mid-year population structure for Venezuela

ven.nDx

enumerated deaths for Venezuela

ven.bx

enumerated births for Venezuela

mad.nKx

mid-year population structure for Madagascar

mad.nDx

enumerated deaths for Madagascar

mad.bx

enumerated births for Madagascar

usa.nKx

mid-year population structure for the United States

usa.nDx

enumerated deaths for the United States

usa.bx

enumerated births for the United States

Details

Vital event data tabulated by Keyfitz and Flieger (1990) and used by Goodman et al. (1974) to illustrate their kinship frequency calculations. The three female populations represent tremendous diversity in age-specific demographic schedules. Venezuela (1965) is characterized by low mortality and high fertility; Madagascar (1966) is characterized by very high mortality and fertility, while the United States (1967) is characterized by low mortality and low fertility.

Source

Keyfitz and Flieger (1990), Goodman et al. (1974)

References

Keyfitz, N., and W. Flieger. 1990. World population growth and aging: Demographic trends in the late twentieth century. Chicago: University of Chicago Press.

Goodman, L. A., N. Keyfitz, and T. W. Pullum. 1974. Family formation and the frequency of various kinship relationships. Theoretical Population Biology 5:1-27.

Examples

data(goodman)
## Plot age-specific mortality rates for the three populations
with(goodman, plot(age, usa.nDx/usa.nKx, type="l", log="y", xlab="Age", ylab="nMx"))
with(goodman, lines(age, mad.nDx/mad.nKx, lty=2))
with(goodman, lines(age, ven.nDx/ven.nKx, lty=3))
legend("bottomright", c("USA","Madagascar","Venezuela"), lty=c(1,2,3))

keyfitz

Description

Utility used by life.table to graduate the person-years lived by those dying in the interval by the method of Keyfitz and Flieger (1990).

Usage

keyfitz(b0, nMx)

Arguments

Details

Utility function called by life.table.

Value

The first two values (age classes 0-1 and 1-5) of the nax column of a period life table.

References

Keyfitz, N., and W. Flieger. 1990. World population growth and aging: Demographic trends in the late twentieth century. Chicago: University of Chicago Press.

See Also

life.table

Examples

data(goodman)
## default type="kf"
vlt <- with(goodman, life.table(x=age, nKx=ven.nKx, nDx=ven.nDx))

lams

Description

Calculates the logarithm of the stochastic growth rate using Tuljapurkar's second order approximation for independent and identically distributed environments.

Usage

lams(aseq, n = 5)

Arguments

Details

Uses Tuljapurkar's second order approximation for independent and identically distributed (i.i.d.) environments.

Value

The long-run growth rate for the population with projection matrices given by aseq.

References

Tuljapurkar, S. 1990. Population dynamics in variable environments. Edited by S. A. Levin. Vol. 85, Lecture notes in biomathematics. Berlin: Springer-Veralg.

Caswell, H. 2001. Matrix population models: Construction, analysis, and interpretation. 2nd ed. Sunderland, MA: Sinauer.

See Also

stoch.sens, eigen.analysis

Examples

## simulate two matrices: good year/bad year
## beta distributed survival, gamma fertility

px1 <- rbeta(5,9,1)
px2 <- rbeta(5,7,3)
mx1 <- c(0,rgamma(5,10,10))
mx2 <- c(0,rgamma(5,7,10))
## good year matrix
A1 <- odiag(px1,-1)
A1[1,] <- mx1

## bad year matrix
A2 <- odiag(px2,-1)
A2[1,] <- mx2
aseq <- cbind(matrix(A1,nr=36,nc=1), matrix(A2,nr=36,nc=1))
lams(aseq)

Leslie Matrix

Description

Generates a Leslie matrix for demographic projection from vectors of age-specific cumulative survival and fertility.

Usage

leslie.matrix(lx, mx, 
		    L = TRUE, 
		    peryear = 5, 
		    one.sex = TRUE, 
		    SRB = 1.05, 
		    infant.class = TRUE) 

Arguments

Details

Constructs a k x k age-classified demographic projection matrix with age-specific survival probabilities along the sub-diagonal and age-specific fertilities along the first row of the matrix.

lx and mx are assumed to be of the same length. The resulting matrix is truncated to insure that there are no post-reproductive classes. This is important for ensuring irreducibility of the resulting matrix.

If mx is longer than lx, mx is trucated to be the same length as lx. If lx is longer than mx, a warning is issed and lx is truncated to be the same length as mx.

Fertility is assumed to be birth-flow (Caswell 2001). That is, breeding is assumed to be continuous and the individual elements of the first row of the Leslie matrix are averaged over successive age-classes. Fertility rates are typically given in annualized form. If this is the case and the age-classes are wider than one year, then peryear can be used to appropriately scale up the annual values.

The default behavior is to use person-years lived in the interval as the survival measure. If infant.class=TRUE, lx is taken to have a value for the infant age class (i.e., a shorter class width than the other elements of lx. What is done when there is an infant class depends on what the values in lx represent. If L=TRUE, then the first two values of lx are combined to form the total person-years for the first age-class in the Leslie matrix. Human demographic data from abridged life tables typically come with age classes x = 0, 1, 5, 10, ... Thus, combining the person-years for the first two age classes gives an initial age class of the correct width. If infant.class=TRUE and L=FALSE, the second element of lx is deleted. Creating a Leslie matrix from other forms of non-standard early age-classes can be accomplished by pre-processing lx and using the option infant.class=FALSE.

The human sex ratio at birth (male births/female births) is remarkably close to SRB=1.05 across a wide range of populations and this is the default value for SRB.

The resulting matrix has class "leslie.matrix". This class is not used extensively but will be in future development.

Value

A k x k age-classified demographic projection matrix with class "leslie.matrix".

References

Keyfitz, N. 1977. Introduction to the mathematics of populations. 2nd ed. Menlo Park: Addison-Wesley.

Preston, S.H., P. Heuveline, and F. Guillot. 2001. Demography: Measuring and modeling population processes. Oxford: Blackwell.

Caswell, H. 2001. Matrix population models: Construction, analysis, and interpretation. 2nd ed. Sunderland, MA: Sinauer.

See Also

odiag, leslie.row1

Examples

## Construct lx and mx values
data(goodman)
mlt <- with(goodman, life.table(x=age, nDx=mad.nDx, nKx=mad.nKx))
mx <- goodman$mad.bx/goodman$mad.nKx

## Now make the Leslie matrix
mad <- leslie.matrix(lx=mlt$nLx, mx=mx)

## Might as well do something with it too!
eigen.analysis(mad)

leslie.row1

Description

A utility for calculating the first row of a Leslie matrix from vectors of interval survival probabilities and age-specific fertility rates.

Usage

leslie.row1(mx, px, L = NULL, SRB = 1.05, peryear = 5, one.sex = TRUE)

Arguments

Details

Calculates the first-row entries for a Leslie matrix. This utility is particularly useful for constructing simulated Leslie matrices.

Value

A vector of length k, where k is the rank of the projection matrix A.

See Also

leslie.matrix

Examples

## simulate survival values from a beta(9,1) distribution

px <- rbeta(10,9,1)

## simulate fertility values from a gamma(2,10) distribution with age
##   at first reproduction = 10

mx <- c(0,0,0,rgamma(8,2,10))
A <- odiag(px,-1)
Fx <- leslie.row1(mx,px)
A[1,] <- Fx

life.table

Description

Construct either a period or cohort life table from enumerated deaths and mid-interval population estimates.

Usage

life.table(x, nDx, nKx, 
	      b0 = c(0.07, 1.7), 
	      b1 = c(0.053, 2.8), 
	      b4 = c(1.522, 1.518), 
	      type = "kf", 
	      nxx = 0, 
	      iwidth = 5, 
	      width12 = c(1, 4))

Arguments

Details

Constructs a period or cohort life tables from enumerated deaths and mid-interval population sizes (period) or enumerated deaths and person-years at risk (cohort). x, nDx, and nKx must all the be same length.

There are currently three options for life table construction. The first two are for the construction of period life tables. They differ only in the way that person-years lived by those dying in the first two intervals are handled. For type="kf", the default, the first two values of nax estimated using Keyfitz and Fleiger's (1990) regression method. For type="cd", Coale and Demeny's method (1983) is used. The Coale-Demeny method uses different coefficients depending on the level of early mortality. As a result, this method may work better for high-mortality populations.

The third type of life table is a cohort life table, for which the conversion from mortality rates to probabilities of death is unnecessary, so the nax column of the life table is of limited interest.

Value

A dataframe with nine columns:

References

Keyfitz, N. 1977. Introduction to the mathematics of populations. 2nd ed. Menlo Park: Addison-Wesley.

Coale, A., P. Demeny, and B. Vaughn. 1983. Regional model life tables and stable populations. 2nd ed. New York: Academic Press.

Keyfitz, N., and W. Flieger. 1990. World population growth and aging: Demographic trends in the late twentieth century. Chicago: University of Chicago Press.

Preston, S.H., P. Heuveline, and F. Guillot. 2001. Demography: Measuring and modeling population processes. Oxford: Blackwell.

See Also

cdmltw

Examples

data(goodman)
## default type="kf"
vlt <- with(goodman, life.table(x=age, nKx=ven.nKx, nDx=ven.nDx))

## compare nax values for cd vs kf life tables
vlt1 <- with(goodman, life.table(x=age, nKx=ven.nKx, nDx=ven.nDx, type="cd"))
vlt$nax[1:2]
vlt1$nax[1:2]

## now construct a cohort life table for Himalayan thar,
##  (Hemitargus jemlahicus) 
data(thar)
thar.lt <- with(thar, life.table(x=age, nDx=deaths, nKx=count, 
    type="cohort", iwidth=1, width12=c(1,1)))
thar.lt

loop.elas

Description

Calculate and plot loop elasticities for a demographic projection matrix .

Usage

loop.elas(A, 
	       draw.plot = TRUE, 
	       peryear = 5, 
	       xlab = "Loop Elasticity", 
	       ylab = "Age", 
	       xlim = c(0, (maxe + 0.02)), 
	       ...)

Arguments

Details

Calculates and plots the life-cycle decomposition of van Groenendael et al (1994).

Value

A vector of length k (the rank of the projection matrix A) giving the loop elasticities for each of the loops in the life-cycle graph.

References

Van Groenendael, J., H. De Kroon, S. Kalisz, and S. Tuljapurkar. 1994. Loop analysis: Evaluating life history pathways in population projection matrices. Ecology 75 (8):2410-2415.

See Also

eigen.analysis, leslie.matrix

Examples

data(goodman)
ven <- with(goodman, life.table(x=age, nKx=ven.nKx, nDx=ven.nDx))
ven.mx <- with(goodman, ven.bx/ven.nKx)
A <- leslie.matrix(lx=ven$nLx,mx=ven.mx)

usa <- with(goodman, life.table(x=age, nKx=usa.nKx, nDx=usa.nDx))
usa.mx <- with(goodman, usa.bx/usa.nKx)
B <- leslie.matrix(lx=usa$nLx,mx=usa.mx)

eav <- eigen.analysis(A)
eau <- eigen.analysis(B)

## Compare the loop elasticities of Venezuela (1965) and the USA (1967)
le.usa <- loop.elas(A)
le.usa <- loop.elas(B)

m2v

Description

Utility that takes a matrix n x m and stacks its columns to form a column vector of length mn.

Usage

m2v(A)

Arguments

Value

For an m x n input matrix, returns a m*n x 1 matrix (i.e., a column vector).

Note

Meant to capture the MATLAB functionality of the colon operator, A(:)

See Also

odiag

Examples

A <- matrix(rnorm(9), nr=3, nc=3)
m2v(A)

odiag

Description

Utility function that creates a square matrix with a vector on the off-diagonal or extracts the specified off-diagonal vector.

Usage

odiag(A, at = 0)

Arguments

Details

If the first argument is a vector of length k, the result will be a square matrix of rank k+at with the provided vector along the 'at' diagonal. Positive values for 'at' place the vector above the diagonal, negative values below the diagonal, and at=0 (the default) places the vector on the diagonal.

Value

A vector if argument A is a matrix and a matrix if A is a vector.

Note

odiag is meant to capture some of the functionality of the MATLAB function diag().

See Also

diag

Examples

## Construct a matrix from a vector
## random survival probabilities with mean 0.9 and variance 0.0082

y <- rbeta(4,9,1)
A <- odiag(y,-1)

## add fertilities
F <- c(0,rep(1,4))
A[1,] <- F

## Extract a vector from a matrix
A <- matrix(rnorm(25), nr=5, nc=5)
odiag(A,2)

plot.leslie.matrix

Description

Plots Leslie matrices and other objects of class "leslie.matrix".

Usage

## S3 method for class 'leslie.matrix'
plot(x, y=NULL,
                  ...,
                  main="", sub="",
                  ann=TRUE,
                  xlim=NULL, ylim=NULL,
                  axes=TRUE,
                  col=c("black","grey"),
                  lwd=2,
                  xlab="Age", ylab="Sensitivity",
                  peryear=5 )

Arguments

Details

Plots the subdiagonal and the first row of an object of class leslie.matrix on common axes. Probably most useful for plotting either eigenvalue sensitivities or elasticities of a projection matrix.

Value

NULL

See Also

eigen.analysis, loop.elas

Examples

data(goodman)
ven <- with(goodman, life.table(x=age, nKx=ven.nKx, nDx=ven.nDx))
ven.mx <- with(goodman, ven.bx/ven.nKx)
A <- leslie.matrix(lx=ven$nLx,mx=ven.mx)
ea.ven <- eigen.analysis(A)

usa <- with(goodman, life.table(x=age, nKx=usa.nKx, nDx=usa.nDx))
usa.mx <- with(goodman, usa.bx/usa.nKx)
B <- leslie.matrix(lx=usa$nLx,mx=usa.mx)
ea.usa <- eigen.analysis(B)

## Compare sensitivities for Venezuela and the USA

plot(ea.ven$sens, main="Venezuela")
plot(ea.usa$sens, main="USA")

project.leslie

Description

Projects an population vector tmax intervals by pre-multiplication with a Leslie matrix.

Usage

project.leslie(A, no, tmax, pop.sum = FALSE)

Arguments

Details

Takes an initial population vector, no, and pre-multiplies by the demographic projection matrix, A, tmax times. This projection will be tmax*n years into the future, where n is the width of the age-classes in the Leslie matrix, A.

Value

If pop.sum=FALSE (the default), the value will be a k x tmax+1 matrix. The first column of the matrix is no and each subsequent column represents the population structure at time step 1, 2, ..., tmax.

If pop.sum=TRUE, the value will be a vector of length tmax+1, where each element of the vector is the total population at time t=0, 1, ..., tmax.

See Also

leslie.matrix, eigen.analysis

Examples

data(goodman)
ult <- with(goodman, life.table(x=age, nKx=usa.nKx, nDx=usa.nDx))
mx <- goodman$usa.bx/goodman$usa.nKx
usa <- leslie.matrix(lx=ult$nLx,mx=mx)

## initial population is the age structure in 1967
## this includes the number of 0-1 year-olds and the number of 1-4
## year-olds, which need to be combined into a single 5-year wide
## element 

no <- goodman$usa.nKx[3:11]
no <- c(sum(goodman$usa.nKx[1:2]),no)/1e6

N <- project.leslie(usa,no,tmax=20)
plot( seq(1967,2067,by=5), apply(N,2,sum), 
         type="l", 
	 xlab="Years", 
	 ylab="Projected Population (millions)")
title("Projected Total Population Size (Ages 0-45) of the United States")

##   Note that this is a lousy projection since it assumes constant
##   demographic rates and a closed population and only accounts for
##   ages 0-45

secder

Description

Calculates the second derivatives of the dominant eigenvalue of the demographic projection matrix for all non-zero transitions with respect to one specified transition.

Usage

secder(A, k, l)

Arguments

Details

See Caswell (1996, 2001) for details on second derivatives of the dominant eigenvalue.

Value

A square matrix of the same rank as A where each element s_{ij} is the second derivative of the dominant eigenvalue of A, \partial^2 \lambda/\partial a_{ij} \partial a_{kl}.

Note

The eigenvalue second derivatives are essential for calculating both perturbation analyses of the eigenvalue elasticities and stochastic sensitivities. secder is used in functions to calculate both these quantities.

References

Caswell, H. 1996. Second derivatives of population growth rate: Calculation and applications. Ecology 77 (3):870-879.

Caswell, H. 2001. Matrix population models: Construction, analysis, and interpretation. 2nd ed. Sunderland, MA: Sinauer.

See Also

fullsecder, elassens, eigen.analysis, stoch.sens

Examples

## eigenvalue second derivatives of the US projection matrix from 1967
## with respect to infant survival
data(goodman)
ult <- with(goodman, life.table(x=age, nKx=usa.nKx, nDx=usa.nDx))
mx <- goodman$usa.bx/goodman$usa.nKx
usa <- leslie.matrix(lx=ult$nLx,mx=mx)

sd21 <- secder(usa,2,1)

stoch.sens

Description

Calculates the sensitivity of the stochastic growth rate to perturbations in the mean demographic projection matrix.

Usage

stoch.sens(env, amat, k)

Arguments

Details

See Caswell (2001, section 14.4) for details.

Value

A list with two elements:

Note

This is essentially a translation of Caswell's (2001, section 14.4.1.1) MATLAB code.

References

Caswell, H. 2001. Matrix population models: Construction, analysis, and interpretation. 2nd ed. Sunderland, MA: Sinauer.

Haridas, C. V., and S. Tuljapurkar. 2005. Elasticities in variable environments: Properties and implications. American Naturalist 166 (4):481-495.

Tuljapurkar, S. 1990. Population dynamics in variable environments. Vol. 85, Lecture notes in biomathematics. Berlin: Springer-Veralg.

Tuljapurkar, S., and C. V. Haridas. 2006. Temporal autocorrelation and stochastic population growth. Ecology Letters 9 (3):324-334.

See Also

lams, eigen.analysis

Examples

## Simulate an i.i.d. sequence of 3 environmental states

env <- floor(runif(100,0,3))+1
px1 <- rbeta(4,9.5,0.5)
px2 <- rbeta(4,7.5,2.5)
px3 <- rbeta(4,5,5)
mx <- c(0,rgamma(4,5,10))

A1 <- odiag(px1,-1)
A2 <- odiag(px2,-1)
A3 <- odiag(px3,-1)
A1[1,] <- leslie.row1(mx,px1)
A2[1,] <- leslie.row1(mx,px2)
A3[1,] <- leslie.row1(mx,px3)
amat <- cbind(matrix(A1,nr=25), matrix(A2,nr=25), matrix(A3,nr=25))
stoch.sens(env,amat,k=5)

thar

Description

Caughley's (1966) survival data on Himalayan thar (Hemitargus jemlahicus).

Usage

data(thar)

Format

A data frame with 13 observations on the following 3 variables.

age

age class

count

the number of individuals at the start of the age class

deaths

observed deaths in the age class

Details

Caughley (1966) smoothed the counts within age classes and this data set used those reported smoothed counts.

Source

Caughley, G. 1966. Mortality patterns in mammals. Ecology 47:906-918.

Examples

data(thar)
thar.lt <- with(thar, 
    life.table(x=age, 
        nDx=deaths, 
        nKx=count, 
        type="cohort", 
        iwidth=1, 
        width12=c(1,1)))
thar.lt