tfr.map: TFR World Map

In PPgp/bayesTFR: Bayesian Fertility Projection

TFR World Map

Description

Generate world maps of the total fertility rate for given projection period and quantile, using different techniques: tfr.map and tfr.map.all use rworldmap, tfr.ggmap uses ggplot2, and tfr.map.gvis creates an interactive map via GoogleVis. In addition to TFR, all these functions allow to project country specific Phase II MCMC parameters into the world maps.

Usage

tfr.map(pred, quantile = 0.5, 
    year = NULL, par.name = NULL, adjusted = FALSE,
    projection.index = 1, device = "dev.new", main = NULL, 
    resolution=c("coarse","low","less islands","li","high"),
    device.args = NULL, data.args = NULL, ...)

tfr.ggmap(pred, quantile = 0.5, 
    year = NULL, par.name = NULL, adjusted = FALSE,
    projection.index = 1, main = NULL, data.args = NULL, 
    viridis.option = "B", nr.cats = 10, same.scale = FALSE, 
    plot = TRUE, file.name = NULL, plot.size = 4, ...)
    
tfr.map.gvis(pred, year = NULL, quantile = 0.5, pi = 80, 
    par.name = NULL, adjusted = FALSE, ...)
    
tfr.map.all(pred, output.dir, output.type = "png", 
    tfr.range = NULL, nr.cats = 50, same.scale = TRUE, 
    quantile = 0.5, file.prefix='TFRwrldmap_', ...)
			
get.tfr.map.parameters(pred, tfr.range = NULL, 
    nr.cats = 50, same.scale = TRUE, quantile = 0.5, ...)

Arguments

pred	Object of class bayesTFR.prediction.
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.
year	Year to be plotted. It can be a year within a projection period or a year within an estimation period. In the latter case, the observed data are plotted. If not given, projection.index determines the projection year.
par.name	Name of a country-specific parameter to be plotted. If NULL, the TFR is plotted. Allowed values are any of those returned by tfr.parameter.names.cs.extended() and ‘lambda’ (see Details).
adjusted	Logical indicating if the measure to be plotted is based on adjusted TFRs.
projection.index	Index of the projection to be displayed. It is only relevant if year is NULL. projection.index=1 means the present year, projection.index=2 means the first projection period after present year, etc..
device	Device for displaying the map. It is passed to the mapDevice function of the rworldmap package. If it is equal to ‘dev.cur’, the current device is used. Otherwise, it can be ‘dev.new’, ‘png’, ‘pdf’ etc.
main	Title for the map. If it is NULL, a default title is constructed from the projection year and quantile.
resolution	Map resolution as implemented in getMap. High resolution requires the rworldxtra package.
device.args	List of additional arguments to be passed to the mapDevice function of the rworldmap package.
data.args	List of additional arguments to be passed to the underlying data retrieving function.
viridis.option	Argument option passed to the ggplot2::scale_fill_viridis_c function indicating the colormap. Available are ‘magma’ (or ‘A’), ‘inferno’ (or ‘B’, default), ‘plasma’ (or ‘C’), ‘viridis’ (or ‘D’) and ‘cividis’ (or ‘E’).
nr.cats	Number of color categories.
same.scale	Logical controlling if maps for all projection years of this prediction object should be on the same color scale.
plot	Logical indicating if a plot should be shown. If FALSE, the function only returns the ggplot object.
file.name	Name of a file to save the plot. If NULL nothing is saved. The type of the file is determined by its extension. Only used if plot is TRUE.
plot.size	Height of the plotting device in inches. The width is automatically set using the aspect ratio of 2.36. Only used if plot is TRUE.
output.dir	Directory into which resulting maps are stored.
output.type	Type of the resulting files. It can be “png”, “pdf”, “jpeg”, “bmp”, “tiff”, or “postscript”.
tfr.range	Range of the total fertility rate to be displayed. It is of the form c(tfr.min, tfr.max). By default, the whole range is considered. Note that countries with values outside of the given range will appear white.
file.prefix	Prefix for file names.
...	Arguments passed to the mapCountryData function of the rworldmap package. In case of tfr.map.gvis these are passed to the underlying data retrieving function (the same as data.args). In case of tfr.ggmap which uses ggplot2 they are passed to the geom_sf function.
pi	Probability interval to be shown when a country is selected in an interactive map. The corresponding quantiles must be available (see argument quantile above).

Details

tfr.map creates a single map for a given projection period and quantile using the rworldmap package. tfr.map.all generates a sequence of such maps, namely one for each projection period. If the package fields is installed, a color bar legend at the botom of the map is created.

Function get.tfr.map.parameters can be used in combination with tfr.map. (Note that get.tfr.map.parameters is called from inside of tfr.map.all.) It sets breakpoints for the color scheme using quantiles of a fitted gamma distribution.

Function tfr.ggmap is similar to tfr.map, but used the ggplot2 package in combination with the geom_sf function.

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

By default, tfr.map, tfr.ggmap and tfr.map.gvis produce maps of TFRs. Alternatively, the functions can be used to plot country-specific Phase II MCMC parameters into a world map. They are given by the argument par.name. In addition to the MCMC parameters, if par.name='lambda', the period of the end of TFR decline (i.e. start of Phase III) is computed for each country and projected into the map. In such a case, for tfr.map we recommend to adjust the color scale in tfr.map e.g. using the arguments catMethod='pretty' and numCats=20 (see mapCountryData).

Value

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

pred	The object of class bayesTFR.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. It is generated from a fitted gamma distribution. 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.

Author(s)

Hana Sevcikova, Patrick Gerland, Adrian Raftery

Examples

## Not run: 
sim.dir <- file.path(find.package("bayesTFR"), "ex-data", "bayesTFR.output")
pred <- get.tfr.prediction(sim.dir=sim.dir)

# Using ggplot2
tfr.ggmap(pred)
tfr.ggmap(pred, year = 2100)

# Using rworldmap
# Uses heat colors and seven categories by default
tfr.map(pred)
# Uses more colors with more suitable categorization
params <- get.tfr.map.parameters(pred)
do.call("tfr.map", params)
# Another projection year on the same scale
do.call("tfr.map", c(list(year=2043), params))

# Using Google Vizualization tool
tfr.map.gvis(pred)

## End(Not run)

PPgp/bayesTFR documentation built on Nov. 5, 2024, 1:57 p.m.