foodweb {mvbutils} | R Documentation |
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
.
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))
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 ) |
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.
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.
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)