foodweb {mvbutils}R Documentation

Shows which functions call what

Description

foodweb is applied to a group of functions (e.g. all those in a workspace); it produces a graphical display showing the hierarchy of which functions call which other ones. This is handy, for instance, when you have a great morass of functions in a workspace, and want to figure out which ones are meant to be called directly. callers.of(funs) and callees.of(funs) show which functions directly call, or are called directly by, funs.

Usage

foodweb( funs, where=1, charlim=80, prune=character(0), rprune, ancestors=TRUE, descendents=TRUE, plotting =TRUE, plotmath=FALSE, generics=c( "c","print","plot", "["), lwd=0.5, xblank=0.18, border="transparent", boxcolor="white", textcolor="black", color.lines=TRUE, highlight="red", ...)
## S3 method for class 'foodweb':
plot(x, textcolor, boxcolor, xblank, border, textargs = list(), use.centres = TRUE, color.lines = TRUE, poly.args = list(), expand.xbox = 1.05, expand.ybox = expand.xbox * 1.2, plotmath = FALSE, cex=par( "cex"), ...) # plot.foodweb
callers.of( funs, fw=foodweb( plotting=FALSE))
callees.of( funs, fw=foodweb( plotting=FALSE))

Arguments

funs character vector OR (in foodweb only) the result of a previous foodweb call
where position(s) on search path, or an environment, or a list of environments
charlim controls maximum number of characters per horizontal line of plot
prune character vector. If omitted, all funs will be shown; otherwise, only ancestors and descendants of functions in prune will be shown. Augments funs if required.
rprune regexpr version of prune; prune <- funs %matching% rprune. Does NOT augment funs. Overrides prune if set.
ancestors show ancestors of prune functions?
descendents show descendents of prune functions?
plotting graphical display?
plotmath leave alone
generics calls TO functions in generics won't be shown
lwd see par
xblank leave alone
border border around name of each object (TRUE/FALSE)
boxcolor background colour of each object's text box
textcolor of each object
color.lines will linking lines be coloured according to the level they originate at?
highlight seemingly not used
cex text size (see "cex" in ?par)
... passed to plot.foodweb and thence to par
textargs not currently used
use.centres where to start/end linking lines. TRUE is more accurate but less tidy with big webs.
expand.xbox how much horizontally bigger to make boxes relative to text?
expand.ybox how much vertically bigger to ditto?
poly.args other args to rect when boxes are drawn
fw an object of class foodweb, or the funmat element thereof (see Value)
x a foodweb (as an argument to plot.foodweb)

Details

The main value is in the graphical display. At the top ("level 0"), functions which don't call any others, and aren't called by any others, are shown without any linking lines. Functions which do call others, but aren't called themselves, appear on the next layer ("level 1"), with lines linking them to functions at other levels. Functions called only by level 1 functions appear next, at level 2, and so on. Functions which call each other will always appear on the same level, linked by a bent double arrow above them. The colour of a linking line shows what level of the hierarchy it came from.

foodweb makes some effort to arrange the functions on the display to keep the number of crossing lines low, but this is a hard problem! Judicious use of prune will help keep the display manageable. Perhaps counterintuitively, any functions NOT linked to those in prune (which all will be, by default) will be pruned from the display.

foodweb tries to catch names of functions that are stored as text, and it will pick up e.g. glm in do.call( "glm", glm.args). There are limits to this, of course (?methods?).

The argument list may be somewhat daunting, but the only ones normally used are funs, where, and prune. Also, to get a readable display, you may need to reduce cex and/or charlim. A number of the less-obvious arguments are set by other functions which rely on plot.foodweb to do their display work. Several may disappear in future versions.

If the display from foodweb is unclear, try foodweb( .Last.value, cex=<<something below 1>>, charlim=<<something probably less than 100>>). This works because foodweb will also accept a foodweb-class object as its argument. You can also assign the result of foodweb to a variable, which is useful if you expect to do a lot of tinkering with the display, or to inspect the who-calls-whom matrix by hand.

callers.of and callees.of process the output of foodweb, looking for immediate dependencies only. The second argument will call foodweb by default, so it may be more efficient to call foodweb first and assign the result to a variable.

Value

foodweb returns an object of (S3) class foodweb. This has three components: funmat: a matrix of 0's and 1's showing what (row) calls what (column). The dimnames are the function names. x: shows the x-axis location of the centre of each function's name in the display, in par("usr") units level: shows the y-axis location of the centre of each function's name in the display, in par("usr") units. For small numbers of functions, this will be an integer; for larger numbers, there will some adjustment around the nearest integer Apart from graphical annotation, the main useful thing is funmat, which can be used to work out the "pecking order" and e.g. which functions directly call a given function. callers.of and callees.of return a character vector of function names.

Examples

foodweb( ) # functions in .GlobalEnv
foodweb( where="package:mvbutils", cex=0.4, charlim=60) # yikes!
foodweb( c( find.funs("package:mvbutils"), "paste"))
# functions in .GlobalEnv, and "paste"
foodweb( find.funs("package:mvbutils"), prune="paste")
# only those parts of the tree connected to "paste";
# NB that funs <- unique( c( funs, prune)) inside "foodweb"
foodweb( where="package:mvbutils", rprune="aste")
# doesn't include "paste" as it's not in "mvbutils", and rprune doesn't augment funs
foodweb( where="package:mvbutils", rprune="name") # does work
foodweb( where=asNamespace( "mvbutils")) # secret stuff
fw <- foodweb( where="package:mvbutils")
fw$funmat # a big matrix
callers.of( "mlocal", fw)
callees.of( find.funs() %matching% "name", fw)

[Package mvbutils version 2.5.0 Index]