[R-pkgs] proftools package now available from CRAN

[Luke Tierney]

 		PROFILE OUTPUT PROCESSING TOOLS FOR R
                 =====================================


This package provides some simple tools for examining Rprof output
and, in particular, extracting and viewing call graph information.
Call graph information, including which direct calls where observed
and how much time was spent in these calls, can be very useful in
identifying performance bottlenecks.

One important caution: because of lazy evaluation a nested call
f(g(x)) will appear on the profile call stack as if g had been called
by f or one of f's callees, because it is the point at which the value
of g(x) is first needed that triggers the evaluation.


EXPORTED FUNCTIONS

The package exports five functions:

     readProfileData reads the data in the file produced by Rprof into a
         data structure used by the other functions in the package.
         The format of the data structure is subject to change.

     flatProfile is similar to summaryRprof.  It returns either a
         matrix with output analogous to gprof's flat profile or a
         matrix like the by.total component returned by summaryRprof;
         which is returned depends on the value of an optional second
         argument.

     printProfileCallGraph produces a printed representation of the
         call graph.  It is analogous to the call graph produced by
         gprof with a few minor changes.  Reading the gprof manual
         section on the call graph should help understanding this
         output.  The output is similar enough to gprof output for the
         cgprof (http://mvertes.free.fr/) script to be able to produce
         a call graph via Graphviz.

     profileCallGraph2Dot prints out a Graphviz .dot file representing
         the profile graph.  Times spent in calls can be mapped to node
         and edge colors.  The resulting files can then be viewed with
         the Graphviz command line tools.

     plotProfileCallGraph uses the graph and Rgraphviz packages to
         produce call graph visualizations within R.  You will need to
         install these packages to use this function.


A SIMPLE EXAMPLE

Collect profile information  for the examples for glm:

           Rprof("glm.out")
           example(glm)
           Rprof()
           pd <- readProfileData("glm.out")

Obtain flat profile information:

           flatProfile(pd)
           flatProfile(pd, FALSE)

Obtain a printed call graph on the standard output:

           printProfileCallGraph(pd)

If you have the cgprof script and the Graphviz command line tools
available on a UNIX-like system, then you can save the printed graph
to a file,

           printProfileCallGraph(pd, "glm.graph")

and either use

           cgprof -TX glm.graph

to display the graph in the interactive graph viewer dotty, or use

           cgprof -Tps glm.graph > glm.ps
           gv glm.ps

to create a PostScript version of the call graph and display it with
gv.

Instead of using the printed graph and cgprof you can use create a
Graphviz .dot file representation of the call graph with

           profileCallGraph2Dot(pd, filename = "glm.dot", score = "total")

and view the graph interactively with dotty using

           dotty glm.dot

or as a postscript file with

           dot -Tps glm.dot > glm.ps
           gv glm.ps

Finally, if you have the graph package from CRAN and the Rgraphviz
package from Bioconductor installed, then you can view the call graph
within R using

           plotProfileCallGraph(pd, score = "total")

The default settings for this version need some work.]


OPEN ISSUES

My intention was to handle cycles roughly the same way that gprof
does.  I am not completely sure that I have managed to do this; I am
also not completely sure this is the best approach.

The graphs produced by cgprof and by plotProfileGraph and friends when
mergeEdges is false differ a bit.  I think this is due to the
heuristics of cgprof not handling cycle entries ideally and that the
plotProfileGraph graphs are actually closer to what is wanted.  When
mergeEdges is true the resulting graphs are DAGs, which simplifies
interpretation, but at the cost of lumping all cycle members together.

gprof provides options for pruning graph printouts by omitting
specified nodes.  It may be useful to allow this here as well.

Probably more use should be made of the graph package.


IMPLEMENTATION NOTES

The implementation is extremely crude (a real mess would be more
accurate) and will hopefully be improved over time--at this point it
is more of an existence proof than a final product.

Performance is less than ideal, though using these tools it was
possible to identify some problem points and speed up computing the
profile data by a factor of two (in other words, it may be bad now but
it used to be worse).  More careful design of the data structures and
memoizing calculations that are now repeated is likely to improve
performance substantially.




-- 
Luke Tierney
Chair, Statistics and Actuarial Science
Ralph E. Wareham Professor of Mathematical Sciences
University of Iowa                  Phone:             319-335-3386
Department of Statistics and        Fax:               319-335-3017
    Actuarial Science
241 Schaeffer Hall                  email:      luke at stat.uiowa.edu
Iowa City, IA 52242                 WWW:  http://www.stat.uiowa.edu