Package 'FuncMap'

Hive Plots of R Package Function Calls

Description

Analyzes the function calls in an R package and creates a hive plot of the calls, dividing them among functions that only make outgoing calls (sources), functions that have only incoming calls (sinks), and those that have both incoming calls and make outgoing calls (managers). Function calls can be mapped by their absolute numbers, their normalized absolute numbers, or their rank. FuncMap should be useful for comparing packages at a high level for their overall design. Plus, it's just plain fun. The hive plot concept was developed by Martin Krzywinski (www.hiveplot.com) and inspired this package. Note: this package is maintained for historical reasons. HiveR is a full package for creating hive plots. FuncMap contains only one function, FuncMap. It is released under the GPL-3 license.

Author(s)

Bryan A. Hanson DePauw University, Greencastle Indiana USA
Maintainer: Bryan A. Hanson <[email protected]>

References

FuncMap was inspired by the work of Martin Krzywinski on hive plots (www.hiveplot.com).

---

Hive Plots of R Package Function Calls

Description

FuncMap analyzes the function calls in an R package and creates a hive plot of the calls, dividing them among functions that only make outgoing calls (sources), functions that have only incoming calls (sinks), and those that have both incoming calls and make outgoing calls (managers). Function calls can be mapped by their absolute numbers, their normalized absolute numbers, or their rank. FuncMap should be useful for comparing packages at a high level for their overall design. Plus, it's just plain fun and makes great artwork!

Usage

FuncMap(fwb = foodweb, pkg = "none", method = "abs",
	sm.title = FALSE, newpage = TRUE, debug = FALSE)

Arguments

fwb	An object of class foodweb created by the function foodweb in package mvbutils.
pkg	The name of the package being analyzed; used for the plot title.
method	One of c("abs", "norm", "rank"). If "abs", the absolute count of incoming + outgoing calls. If "norm", the absolute count of calls is normalized to the interval 0:1. If "rank", the number of calls is ranked before plotting.
sm.title	Logical. Defaults to FALSE. Set = TRUE when placing several hive plots on one page, and the text annotations are kept to minimum.
newpage	Logical. Defaults to TRUE. Clears the page before plotting. If making multiple plots on a single page, set = FALSE.
debug	Logical. Defaults to FALSE. If TRUE, grey concentric circles are plotted to guide in troubleshooting or understanding.

Details

The list of which functions call which other functions is in fwb$funmat, and is used to determine which functions are sources, managers and sinks. In the process, the total number of outgoing calls are determined for source functions, the total of incoming and outgoing calls is calculated for managers, and the total incoming calls determined for sink functions. Each is plotted on the appropriate axis as either the absolute numbers, the normalized absolute numbers, or by rank. The absolute plot axis lengths give a sense of which kind of functions dominate in a package, and whether there are a few functions that do most of the work. The normalized plot axes are the same length, which spreads out the absolute plot but is otherwise the same data. For the absolute and norm plots, where there is more than one function making n calls to another function which receives p calls, the line width of the spline curve is set to n. Also, a black dot is plotted at each position along the axis where there is a function. The rank plot spreads out the functions so that each function has a unique position on the axis; each node connects to only one other node and hence the linewidths are all 1. If there are stand alone functions that make no calls at all, these are plotted as a dot at the center of the hive.

Some relatively simple packages that make interesting plots are pcaPP and cluster. More complex packages are survival, colorspace and rgl. Quite complex packages are lattice, mclust and ggplot2. colorspace is quite interesting if you compare the absolute and rank plots. seriation and mvoutlier are packages that have no manager functions.

For package MASS and presumably some others, only part of the hive plot is drawn before throwing an error. This is the result of how foodweb reads code and determines when a function has been called (M. Bravington, personal communication).

Value

A list of two data frames:

points	Coordinates of the points (nodes) to be plotted on each axis, representing the counts of calls (in absolute, normalized or ranked units).
curves	Coordinates and line widths for drawing the edges, which are spline curves representing the calls.

Author(s)

Bryan A. Hanson <[email protected]>

References

The hive plot concept was developed by Martin Krzywinski (www.hiveplot.com) and inspired this package.

See Also

Function foodweb in package mvbutils.

Examples

require(mvbutils)
require(lattice)
require(grid)
# draw the foodweb using mvbutils
fw <- foodweb(where = "package:lattice", charlim = 20, cex = 0.5, lwd = 1)
# draw the hive plot
ans <- FuncMap(fwb = fw, pkg = "lattice", method = "abs")

---