foodweb               package:mvbutils               R Documentation

_S_h_o_w_s _w_h_i_c_h _f_u_n_c_t_i_o_n_s _c_a_l_l _w_h_a_t

_D_e_s_c_r_i_p_t_i_o_n:

     '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'.

_U_s_a_g_e:

      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))

_A_r_g_u_m_e_n_t_s:

    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')

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     '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.

_A_u_t_h_o_r(_s):

     Mark Bravington

_E_x_a_m_p_l_e_s:

     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)

