personograph (version 0.1.3)

personograph: Plots a personograph

Description

Plots a personograph from a named list with percentages (must sum to 1). A personograph is a graphical represenation of relative benefit or harm, using a grid of icons with different colors. Its intended use is similar to that of Cates Plots (Visual Rx, Number Needed to Treat visualization). Although these could be seen as Kuiper-Marshall plots.

Usage

personograph(data, fig.title = NULL, fig.cap = NULL, draw.legend = T, icon = NULL, icon.dim = NULL, icon.style = 1, n.icons = 100, plot.width = 0.75, dimensions = ceiling(sqrt(c(n.icons, n.icons))), fudge = 0.0075, legend.show.zeros = TRUE, force.fill = "ignore", round.fn = round.standard, colors = as.colors(data))

Arguments

data

A list of names to percentages (from 0 to 1)

fig.title

Figure title

fig.cap

Figure caption

draw.legend

Logical if TRUE (default) will draw the legend

icon

A grImport Picture for the icon, overwrites icon.style

icon.dim

The dimensions of icon as a vector c(width, height) as numerical. Calculated from the dimensions if not supplied

icon.style

A numeric from 1-11 indicating which of the included icons to use, they are mostly variations on the theme

n.icons

Number of icons to draw, defaults to 100

plot.width

The percentage of width that the main plotting area should take (with respect to the frame)

dimensions

A vector of c(rows, columns) for the dimensions of the grid

fudge

Fudge factor for the icon size, substracted from the icon.size

legend.show.zeros

Logical if TRUE indicating whether to show zero (0) values in the legend.

force.fill

A character vector of 'ignore' (default), 'most', 'least', or one of the names from data. Defines the behaviour for cases when the rounding doesn't add up to n.icons. 'ignore' simply draws less icons, 'most' adds an icon to the largest group, 'least' to the smallest. If a name from data is supplied it will added to that element

round.fn

Function that is applied to round the percentages from data to n.icons. See also force.fill

colors

A vector of names to colors, must match the names in data. Uses gray.colors style if none supplied

Value

None.

Details

Supplying your own icon You can supply your own icon by setting icon to a grImport Picture. A Picture can be loaded with grImport::readPicture which requires a grImport XML file. Obtaining this file from a standard SVG or PDF graphics file requires conversion. The easiest way is to convert your original file to PDF and then to PostScript (PS) with the command-line pdf2ps tool, then tracing it with grImport::PostScriptTrace. See the grImport package documentation for more details.

Examples

data <- list(first=0.9, second=0.1)
personograph(data)
# With colors
personograph(data, colors=list(first="red", second="blue"))
# With different icon.style
personograph(data, icon.style=4) # numeric from 1-11
# Plot a thousand in a 20x50 grid
personograph(data, n.icons=1000, dimensions=c(20,50), plot.width=0.75)