pop.pyramid: Probabilistic Population Pyramid

In bayesPop: Probabilistic Population Projection

Probabilistic Population Pyramid

Description

Functions for plotting probabilistic population pyramid. pop.pyramid creates a classic pyramid using rectangles; pop.trajectories.pyramid creates one or more pyramids using vertical lines (possibly derived from population trajectories). They can be used to view a prediction object created with this package, or any user-defined sex- and age-specific dataset. For the latter, function get.bPop.pyramid should be used to translate user-defined data into a bayesPop.pyramid object.

Usage

## S3 method for class 'bayesPop.prediction'
pop.pyramid(pop.object, country, year = NULL, 
    indicator = c("P", "B", "D"), pi = c(80, 95), 
    proportion = FALSE, age = NULL, plot = TRUE, pop.max = NULL, ...)
    
## S3 method for class 'bayesPop.pyramid'
pop.pyramid(pop.object, main = NULL, show.legend = TRUE, 
    pyr1.par = list(border="black", col=NA, density=NULL, height=0.9),
    pyr2.par = list(density = -1, height = 0.3), 
    show.birth.year = FALSE,
    col.pi = NULL, ann = par("ann"), axes = TRUE, grid = TRUE, 
    cex.main = 0.9, cex.sub = 0.9, cex = 0.8, cex.axis = 0.8, ...)
    
pop.pyramidAll(pop.pred, year = NULL,
    output.dir = file.path(getwd(), "pop.pyramid"),
    output.type = "png", one.file = FALSE, verbose = FALSE, ...)
	
## S3 method for class 'bayesPop.prediction'
pop.trajectories.pyramid(pop.object, country, year = NULL, 
    indicator = c("P", "B", "D"), pi = c(80, 95), nr.traj = NULL, 
    proportion = FALSE, age = NULL, plot = TRUE, pop.max = NULL, ...)
    
## S3 method for class 'bayesPop.pyramid'
pop.trajectories.pyramid(pop.object, main = NULL, show.legend = TRUE, 
    show.birth.year = FALSE, col = rainbow, col.traj = "#00000020", 
    omit.page.pars = FALSE, lwd = 2, ann = par("ann"), axes = TRUE, grid = TRUE, 
    cex.main = 0.9, cex.sub = 0.9, cex = 0.8, cex.axis = 0.8, ...)
    
pop.trajectories.pyramidAll(pop.pred, year = NULL,
    output.dir = file.path(getwd(), "pop.traj.pyramid"),
    output.type = "png", one.file = FALSE, verbose = FALSE, ...)
	
## S3 method for class 'bayesPop.pyramid'
plot(x, ...)

## S3 method for class 'bayesPop.prediction'
get.bPop.pyramid(data, country, year = NULL, 
    indicator = c("P", "B", "D"), pi = c(80, 95), 
    proportion = FALSE, age = NULL, nr.traj = 0, sort.pi=TRUE, pop.max = NULL, ...)
    
## S3 method for class 'data.frame'
get.bPop.pyramid(data, main.label = NULL, legend = "observed", 
    is.proportion = FALSE, ages = NULL, pop.max = NULL, 
    LRmain = c("Male", "Female"), LRcolnames = c("male", "female"), CI = NULL, ...)
    
## S3 method for class 'matrix'
get.bPop.pyramid(data, ...)

## S3 method for class 'list'
get.bPop.pyramid(data, main.label = NULL, legend = NULL, CI = NULL, ...)

Arguments

pop.object	Object of class bayesPop.prediction or bayesPop.pyramid (see Value section).
pop.pred	Object of class bayesPop.prediction.
x	Object of class bayesPop.pyramid.
data	Data frame, matrix, list or object of class bayesPop.prediction. For data frame and matrix, it must have columns defined by LRcolnames (“male” and “female” by default). The row names will determine the age labels. For lists, it can be a collection of such data frames. The names of the list elements are used for legend, unless legend is given.
country	Name or numerical code of a country. It can also be given as ISO-2 or ISO-3 characters.
year	Year within the projection or estimation period to be plotted. Default is the start year of the prediction. It can also be a vector of years. pop.pyramid draws the first two, pop.trajectories.pyramid draws all of them. In the functions pop.pyramidAll and pop.trajectories.pyramidAll, the year argument can be a list of years, in which case the pyramids are created for all elements in the list.
indicator	One of the characters “P” (population), “B” (births), “D” (deaths) determining the pyramid indicator.
pi	Probability interval. It can be a single number or an array.
proportion	Logical. If TRUE the pyramid contains the distribution of rates of age-specific counts and population totals.
age	Integer vector of age indices. In a 5-year simulation, value 1 corresponds to age 0-4, value 2 corresponds to age 5-9 etc. In a 1x1 simulation, values 1, 2, 3 correpond to ages 0, 1, 2. Last available age goup is 130+ which corresponds to index 27 in a 5-year simulation and index 131 in an annual simulation. The purpose of this argument here is mainly to control the height of the pyramid.
plot	If FALSE, nothing is plotted. It can be used to retrieve the pyramid object without drawing it.
main	Titel of the plot. By default it is the country name and projection year if known.
show.legend	Logical controlling if the plot legend is drawn.
pyr1.par, pyr2.par	List of graphical parameters (color, border, density and height) for drawing the pyramid rectangles, for the first and second pyramid, respectively (see Details). The height component should be a number between 0 (corresponds to a line) and 1 (for non-overelapping rectangles). If density is NULL, the rectangles are transparent, see the argument density in rect.
show.birth.year	Logical. If TRUE the corresponding birth years are shown on the right vertical axis.
col.pi	Vector of colors for drawing the probability boxes. If it is given, it must be of the same length as pi.
ann	Logical controlling if any annotation (main and legend) is plotted.
axes	Logical controlling if axes are plotted.
grid	Logical controlling if grid lines are plotted.
cex.main, cex.sub, cex, cex.axis	Magnification to be used for the title, secondary titles on the right and left panels, legend and axes, respectively.
output.dir	Directory into which resulting graphs are stored.
output.type	Type of the resulting files. It can be “png”, “pdf”, “jpeg”, “bmp”, “tiff”, or “postscript”.
one.file	Logical. If TRUE the output is put into one single file, by default a PDF.
verbose	Logical switching log messages on and off.
nr.traj	Number of trajectories to be plotted. If NULL, all trajectories are plotted, otherwise they are thinned evenly.
col	Colors generating function. It is called with an argument giving the number of pyramids to be plotted. Each color is then used for one pyramid, including its confidence intervals.
col.traj	Color used for trajectories. If more than one pyramid is drawn with its trajectories, this can be a vector of the size of number of pyramids.
omit.page.pars	Logical. If TRUE, no page parameters are set. Can be used if multiple pyramids are to be put on one page.
lwd	Line width for the pyramids.
sort.pi	Logical controlling if the probability intervals are sorted in decreasing order. This has an effect on the order in which they are plotted and thus on overlapping of pyramid boxes. By default the largest intervals are plotted first.
main.label	Optional argument for the main title.
legend	Legend to be used. In case of multiple pyramids, this can be a vector for each of them. If not given and data is a list, names of the list elements are taken as legend.
is.proportion	Either logical, indicating if the values in data are proportions, or NA in which case the proportions are computed.
ages	Vector of age labels. It must be of the same length as the number of rows of data. If it is not given, the age labels are considered to be the row names of data.
pop.max	Maximum value to be drawn in the pyramid. If it is not given, max(data) is taken.
LRmain	Vector of character strings giving the secondary titles for the left and right panel, respectively.
LRcolnames	Vector of character strings giving the column names of data to be used for the left and right panel of the pyramid, respectively.
CI	Confidence intervals. It should be of the same format as the bayesPop.pyramid$CI object, see below.
...	Arguments passed to the underlying functions. For get.bPop.pyramid, these can be additional items to be added to the resulting object, e.g. pyr.year and is.annual.

Details

The pop.pyramid function generates one or two population pyramids in one plot. The first (main) one is usually the median of a future year prediction, but it can also be the current year or any population estimates. The second one serves the purpose of comparing two pyramids with one another and is drawn on top of the main pyramid. For example, one can use it to compare a future prediction with the present, or two different time points in the past, or two different geographies. The main pyramid can have confidence intervals associated with it, which are also plotted. If pop.pyramid is called on a bayesPop.prediction object, the main and secondary pyramid, respectively, is generated from data of a time period given by the first and second element, respectively, of the year argument. In such a case, confidence intervals only of the first year are shown. Thus, it makes sense to set the first year to be a prediction year and the second year to an observed time period. If pop.pyramid is called on a bayesPop.pyramid object, data in the first and second element, respectively, of the bayesPop.pyramid$pyramid list are used, and only the first element of bayesPop.pyramid$CI is used.

Pyramids generated via the pop.trajectories.pyramid function have different appearance and therefore more than two pyramids can be put into one figure. Furthermore, confidence intervals of more than one pyramid can be shown. Thus, all elements of bayesPop.pyramid$pyramid and bayesPop.pyramid$CI are plotted. In addition, single trajectories given in bayesPop.pyramid$trajectories can be shown by setting the argument nr.traj larger than 0.

Both, pop.pyramid and pop.trajectories.pyramid (if called with a bayesPop.prediction object) use data from one country. Functions pop.pyramidAll and pop.trajectories.pyramidAll create such pyramids for all countries for which a projection is available and for all years given by the year argument which should be a list. In this case, one pyramid figure (possibly containing multiple pyramids) is created for each country and each element of the year list.

The core of these functions operates on a bayesPop.pyramid object which is automatically created when called with a bayesPop.prediction object. If used with a user-defined data set, one has to convert such data into bayesPop.pyramid using the function get.bPop.pyramid (see an example below). In such a case, one can simply use the plot function which then calls pop.pyramid.

Value

pop.pyramid, pop.trajectories.pyramid and get.bPop.pyramid return an object of class bayesPop.pyramid which is a list with the following components:

label	Label used for the main titel.
pyramid	List of pyramid data, one element per pyramid. Each component is a data frame with at least two columns, containing data for the left and right panels of the pyramid. Their names must correspond to LRcolnames (see below). There is one row per age group and the row names are used for labeling the y-axis. Names of the list elements are used in the legend.
CI	List of lists of confidence intervals with one element per pyramid. The order corresponds to the order in the pyramid component and it is NULL if the corresponding pyramid does not have confidence intervals. Each element is a list with one element per probability interval whose names are the values of the intervals. Each element is again a list with components low and high which have the same structure as pyramid and contain the lower and upper bounds of the corresponding interval.
trajectories	List of lists of trajectories with one element per pyramid. As in the case of CI, it is ordered the same way as the pyramid component and is NULL if the corresponding pyramid does not have any trajectories to be shown. Each element is again a list with two components, one for the left part and one for the right part of the pyramid. Their names correspond to LRcolnames and each of them is a matrix of size number of age categories x number of trajectories. This is only used by the pop.trajectories.pyramid function.
is.proportion	Logical indicating if values in the various data frames in this object are proportions or raw values.
is.annual	Logical indicating if the data correspond to 1-year age groups. If FALSE, the ages are considered to be 5-year age groups.
pyr.year	Year of the main pyramid. It is used as the base year when show.birth.year is TRUE.
pop.max	Maximum value for the x-axis.
LRmain	Vector of character strings determining the titles for the left and right panels, respectively.
LRcolnames	Vector of character strings determining the column names in pyramid, CI and trajectories used to plot data into the left and right panel, respectively.

Author(s)

Hana Sevcikova, Adrian Raftery, using feedback from Sam Clark and the bayesPop group at the University of Washington.

See Also

pop.trajectories.plot, bayesPop.prediction, summary.bayesPop.prediction

Examples

# pyramids for bayesPop prediction objects
##########################################
sim.dir <- file.path(find.package("bayesPop"), "ex-data", "Pop")
pred <- get.pop.prediction(sim.dir)
pop.pyramid(pred, "Netherlands", c(2045, 2010))
dev.new()
pop.trajectories.pyramid(pred, "NL", c(2045, 2010, 1960), age=1:25, proportion=TRUE)
# using manual manipulation of the data: e.g. show only the prob. intervals 
pred.pyr <- get.bPop.pyramid(pred, country="Ecuador", year=2090, age=1:27)
pred.pyr$pyramid <- NULL
plot(pred.pyr, show.birth.year = TRUE)

# pyramids for user-defined data
################################
# this example dataset contains population estimates for the Washington state and King county 
# (Seattle area) in 2011
data <- read.table(file.path(find.package("bayesPop"), "ex-data", "popestimates_WAKing.txt"), 
    header=TRUE, row.names=1)
# extract data for two pyramids and put it into the right format
head(data)
WA <- data[,c("WA.male", "WA.female")]; colnames(WA) <- c("male", "female")
King <- data[,c("King.male", "King.female")]; colnames(King) <- c("male", "female")
# create and plot a bayesPop.pyramid object
pyramid <- get.bPop.pyramid(list(WA, King), legend=c("Washington", "King"))
plot(pyramid, main="Population in 2011", pyr2.par=list(height=0.7, col="violet", border="violet"))
# show data as proportions and include birth year
pyramid.prop <- get.bPop.pyramid(list(WA, King), is.proportion=NA, 
    legend=c("Washington", "King"), pyr.year = 2011)
pop.pyramid(pyramid.prop, main="Population in 2011 (proportions)",
    pyr1.par=list(col="lightgreen", border="lightgreen", density=2), 
    pyr2.par=list(col="darkred", border="darkred"),
    show.birth.year = TRUE)

bayesPop documentation built on Aug. 10, 2023, 1:10 a.m.