pop.trajectories: Accessing Trajectories

Description

Obtain projection trajectories of population and vital events/rates. get.pop allows to access trajectories using a basic component of an expression. get.trajectory.indices creates a link to the probabilistic components of the projection by providing indices to the trajectories of TFR, e0 and migration.

Usage

pop.trajectories(pop.pred, country, sex=c('both', 'male', 'female'), age='all', ...)
get.pop(object, pop.pred, aggregation = NULL, observed = FALSE, ...)
get.trajectory.indices(pop.pred, country, what=c("TFR", "e0M", "e0F", "migM", "migF"))

Arguments

pop.pred

Object of class bayesPop.prediction.

country

Name or numerical code of a country.

sex

One of both (default), male or female. By default the male and female projections are summed up.

age

Either a character string all (default) or an integer vector of age indices. Value 1 corresponds to age 0-4, value 2 corresponds to age 5-9 etc. Last age goup $130+$ corresponds to index 27. Results is summed over the given age categories

object

Character string giving a basic component of an expression (see pop.expressions).

aggregation

If the basic component is to be evaluated on an aggregated prediction object, this argument gives the name of the aggregation (corresponds argument name in pop.aggregate). By default, the

observed

Logical. Determines if the evaluation uses observed data (TRUE) or predictions (FALSE).

what

A character string that defines to which component should the indices link to. Allowable options are TFR, e0M (male life expectancy), e0F (female life expectancy), migM (male migration),

...

Additional argument passed to the underlying functions. In case of get.pop, this is only used for a Population component and observed=FALSE. It can be either nr.traj giving the number of trajectories

Value

Function pop.trajectories returns a two-dimensional array (time x trajectory). Function get.pop returns an array of four dimensions (country x age x time x trajectory). See pop.expressions for more details. Function get.trajectory.indices returns a 1-d array of indices. If the given component is deterministic, it returns NULL.

Details

Function pop.trajectories returns an array of population trajectories for given sex and age. Function get.pop evaluates a basic component of an expression and results in a four-dimensional array. Internally, this function is used for evaluation after an expression is decomposed into basic components. It can be useful for example for debugging purposes, to obtain results from parts of an expression. In addition, while pop.trajectories works only for population counts, get.pop can be used for obtaining trajectories of vital events and rates. Note that if object contains the wildcard XXX, the function only works on observed data, i.e. observed must be TRUE. Function get.trajectory.indices returns an array of indices that link back to the given probabilistic component. It is of the same length as number of trajectories in the prediction object. For example, an array of c(10, 15, 20) (for a prediction with three trajectories) obtained with what="TFR" means that the 1st, 2nd and 3rd population trajectory, respectively, were generated with the 10th, 15th and 20th TFR trajectory, respectively. If the input TFR and e0 were generated using bayesTFR and bayesLife, functions get.tfr.trajectories and get.e0.trajectories can be used to extract the corresponding TFR and e0 trajectories.

Examples

Run this code

sim.dir <- file.path(find.package("bayesPop"), "ex-data", "Pop")
pred <- get.pop.prediction(sim.dir, write.to.cache=FALSE)

# observed female of Netherlands by age; 1x21x13x1 array
popFNL <- get.pop("PNL_F{}", pred, observed=TRUE)

# observed migration for all countries in the prediction object,
# here 2 countries; 2x1x13x1 array
migAll <- get.pop("GXXX", pred, observed=TRUE)

# projection population for Ecuador with 3 trajectories; 
# 1x1x19x3 array
popEcu <- get.pop("P218", pred, observed=FALSE)

# the above is equivalent to 
popEcu2 <- pop.trajectories(pred, "Ecuador")

# Expression "PNL_F{} / PNL_M{}" evaluated on projections
# is internally replaced by
FtoM <- get.pop("PNL_F{}", pred) / get.pop("PNL_M{}", pred)

# the example simulation was generated with 3 TFR trajectories ...
get.trajectory.indices(pred, "Netherlands", what="TFR")
# ... and 1 e0 trajectory 
get.trajectory.indices(pred, "Netherlands", what="e0M")