mvbutils (version 1.1.0)

foodweb: 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", ...)
 plot.foodweb(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, ...)
 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

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

...

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)

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.

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=<>, charlim=<>). 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.

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
fw <- foodweb( where="package:mvbutils")
fw$funmat # a big matrix
callers.of( "mlocal", fw)
callees.of( find.funs() %matching% "name", fw)