get.pop: Accessing Trajectories

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/get_outputs.R

Description

Obtain projection trajectories of population and vital events/rates. get.pop allows to access trajectories using a basic component of an expression. get.pop.ex and get.pop.exba returns results of an expression defined “by time” and “by age”, respectively. get.trajectory.indices creates a link to the probabilistic components of the projection by providing indices to the trajectories of TFR, e0 and migration. extract.trajectories.eq returns trajectories (of population or expression) and their indices that are closest to given values or a quantile. Similarly, functions extract.trajectories.ge and extract.trajectories.le return trajectories and their indices that are greater equal and less equal, respectively, to the given values or a quantile.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
pop.trajectories(pop.pred, country, sex = c("both", "male", "female"), 
    age = "all", ...)

get.pop(object, pop.pred, aggregation = NULL, observed = FALSE, ...)

get.pop.ex(expression, pop.pred, observed = FALSE, ...)

get.pop.exba(expression, pop.pred, observed = FALSE, ...)

get.trajectory.indices(pop.pred, country, 
    what = c("TFR", "e0M", "e0F", "migM", "migF"))

extract.trajectories.eq(pop.pred, country = NULL, expression = NULL, 
    quant = 0.5, values = NULL, nr.traj = 1, ...)
    
extract.trajectories.ge(pop.pred, country = NULL, expression = NULL, 
    quant = 0.5, values = NULL, all = TRUE, ...)
    
extract.trajectories.le(pop.pred, country = NULL, expression = NULL, 
    quant = 0.5, values = NULL, all = TRUE, ...)

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 function searches for available aggregations and gives priority to the one called “country”.

observed

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

expression

Expression defining the trajectories measure. For syntax see pop.expressions. It must be define by age (i.e. contain curly braces) if used in get.pop.exba, and the opposite applies to get.pop.ex.

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), “migF” (female migration).

quant

Quantile used to select the closest trajectories to.

values

Vector of values used to select the closest trajectories to. If it is not of length 1, it has to be of the same length as the number of projected time periods. If it is not given, quant is used.

nr.traj

Number of trajectories to return. This argument can be passed to any of the functions that contains ....

all

Logical indicating if the corresponding condition should apply to all time periods of a trajectory. If it is FALSE, a trajectory is extracted if the condition is fulfilled in at least one time period.

...

Additional argument passed to the underlying functions. In case of get.pop, get.pop.ex and get.pop.exba, this is only used for observed=FALSE. It can be either nr.traj giving the number of trajectories or logical typical.trajectory.

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.

Functions get.pop.ex and get.pop.exba evaluate a whole expression and the dimensions of the resulting array is collapsed depending on the specific expression. Use get.pop.ex if the expected result of the expression does not contain the age dimension, i.e. it uses no brackets or square brackets. If it is not the case, i.e. the expression is defined using curly braces in order to include the age dimension, the get.pop.exba function is to be used. Argument nr.traj can be used to restrict the number of trajectories returned.

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.

Function extract.trajectories.eq can be used to select a given number of trajectories of any population quantity, including vital events, that are close to either specific values or to a given quantile. For example the default seting with quant=0.5 and nr.traj=1 returns the one trajectory that is “closest” to the median projection. As a measure of “closeness” the sum of absolute differences (across all time periods) is used.

Similarly, function extract.trajectories.ge (extract.trajectories.le) selects all trajectories that are greater (less) equal to the specific values or a given quantile. The argument all specifies, if the greater/less condition should be valid for all time periods of the selected trajectories or at least one time period.

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.

Functions get.pop.ex and get.pop.exba return an array of trajectories. Its dimensions depend on the expression and whether it is evaluated on observed data or projections.

Function get.trajectory.indices returns a 1-d array of indices. If the given component is deterministic, it returns NULL.

Functions extract.trajectories.eq, extract.trajectories.ge, extract.trajectories.le return a list with two components. trajectories: 2-d array of trajectories; index: indices of the selected trajectories relative to the whole set of available trajectories.

Author(s)

Hana Sevcikova

See Also

pop.expressions

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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; 1x21x14x1 array
popFNL <- get.pop("PNL_F{}", pred, observed=TRUE)

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

# projection population for Ecuador with 3 trajectories; 
# 1x1x18x3 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)
# should return the same result as
FtoMa <- get.pop.exba("PNL_F{} / PNL_M{}", pred)

# the same expression by time (summed over ages) 
FtoMt <- get.pop.ex("PNL_F / 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")

# The three trajectories of the population ratio of Ecuador to Netherlands
get.pop.ex("PEC/PNL", pred)
# Returns the trajectory closest to the upper 80% bound, including the corresponding index
extract.trajectories.eq(pred, expression="PEC/PNL", quant=0.9)
# Returns the median trajectory and the high variant, including the corresponding index
extract.trajectories.ge(pred, expression="PEC/PNL", quant=0.45)

bayesPop documentation built on Oct. 30, 2019, 9:57 a.m.