bayesPop (version 6.0-1)

pop.map: World Map of Population Measures

Description

Generates a world map of various population measures for a given quantile and a projection or observed period.

Usage

pop.map(pred, sex = c("both", "male", "female"), age = "all", expression = NULL, ...)
get.pop.map.parameters(pred, expression = NULL, sex = c('both', 'male', 'female'),  age = 'all', range = NULL, nr.cats = 50, same.scale = TRUE, quantile = 0.5, ...) 
pop.map.gvis(pred, ...)

Arguments

pred

Object of class bayesPop.prediction.

sex

One of “both” (default), “male” or “female”. By default the male and female counts are summed up. This argument is only used if expression is NULL.

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. This argument is only used if expression is NULL.

expression

Expression defining the population measure to be plotted. For syntax see pop.expressions. The country components of the expression should be given as “XXX”.

range

Range of the population measure to be displayed. It is of the form c(min, max).

nr.cats

Number of color categories.

same.scale

Logical controlling if maps for all years of this prediction object should be on the same color scale.

quantile

Quantile for which the map should be generated. It must be equal to one of the values in dimnames(pred$quantiles[[2]]), i.e. 0, 0.025, 0.05, 0.1, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.75, 0.8, 0.9, 0.95, 0.975, 1. Value 0.5 corresponds to the median.

...

Additional arguments passed to the underlying functions. In pop.map, these are quantile, year, projection.index, device, main, and device.args (see tfr.map). In pop.map.gvis, these are all arguments that can be passed to tfr.map.gvis. In addition, the first two functions accept arguments passed to the mapCountryData function of the rworldmap package.

Value

get.pop.map.parameters returns a list with elements:

pred

The object of class bayesPop.prediction used in the function.

quantile

Value of the argument quantile.

catMethod

If the argument same.scale is TRUE, this element contains breakpoints for categorization. Otherwise, it is NULL.

numCats

Number of categories.

coulourPalette

Subset of the rainbow palette, starting from dark blue and ending at red.

...

Additional arguments passed to the function.

Performance and Caching

If the expression argument or a non-standard combination of sex and age is used, quantiles are computed on the fly. In such a case, trajectory files for all countries have to be loaded from disk, which can be quite time expensive. Therefore a simple caching mechanism was added to the prediction object which allows re-using data from previously used expressions. The prediction object points to an environment called cache which is a collection of data arrays that are results of evaluating expressions. The space-trimmed expressions are the names of the cache entries. Every time a map function is called, it is checked if the corresponding expression is contained in the cache. If it is not the case, the quantiles are computed on the fly, otherwise the existing values are taken. When computing on the fly, the function tries to process it in parallel if possible, using the package parallel. In such a case, the computation is split into $n$ nodes where $n$ is either the number of cores detected automatically (default), or the value of getOption('cl.cores'). Use options(cl.cores=n) to modify the default. If a sequential processing is desired, set cl.cores to 1. The cache data are also stored on disk, namely in the simulation directory of the prediction object. By default, every update of the cache in memory is also updated on the disk. Thus, data expression results can be re-used in multiple R sessions. Function pop.cleanup.cache deletes the content of the cache. This behaviour can be turned off by setting the argument write.to.cache=FALSE in the get.pop.prediction function. We use this settings in the examples throughout this manual whenever the example data from the installation directory is used, in order to prevent writing into the installation directory.

Details

pop.map creates a single map for the given time period and quantile. If the package fields is installed, a color bar legend at the botom of the map is created.

Function get.pop.map.parameters can be used in combination with pop.map. It sets breakpoints for the color scheme.

Function pop.map.gvis creates an interactive map using the googleVis package and opens it in an internet browser. It also generates a table of the mapped values that can be sorted by columns interactively in the browser.

See Also

tfr.map

Examples

## Not run: 
# ##########################
# # This example only makes sense if there is a simulation 
# # for all countries. Below, only two countries are included,
# # so the map is useless.
# ##########################
# sim.dir <- file.path(find.package("bayesPop"), "ex-data", "Pop")
# pred <- get.pop.prediction(sim.dir=sim.dir, write.to.cache=FALSE)
# # Uses heat colors with seven categories by default
# pop.map(pred, sex='female', age=4:10)
# # Female population in child-bearing age as a proportion of totals
# pop.map(pred, expression='PXXX_F[4:10] / PXXX')
# # The same with more colors
# params <- get.pop.map.parameters(pred, expression='PXXX_F[4:10] / PXXX')
# do.call('pop.map', params)
# # Another projection year on the same color scale
# do.call('pop.map', c(list(year=2043), params))
# # Potential support ratio using googleVis
# pop.map.gvis(pred, expression="PXXX[5:13] / PXXX[14:27]")## End(Not run)