\HeaderA{summaryRprof}{Summarise Output of R Sampling Profiler}{summaryRprof}
\keyword{utilities}{summaryRprof}
\begin{Description}\relax
Summarise the output of the \code{\LinkA{Rprof}{Rprof}} function to show the
amount of time used by different \R{} functions.
\end{Description}
\begin{Usage}
\begin{verbatim}
summaryRprof(filename = "Rprof.out", chunksize = 5000,
              memory=c("none","both","tseries","stats"),
              index=2, diff=TRUE, exclude=NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{filename}] Name of a file produced by \code{Rprof()}
\item[\code{chunksize}] Number of lines to read at a time
\item[\code{memory}] Summaries for memory information. See Details below
\item[\code{index}] How to summarize the stack trace for memory
information. See Details below.
\item[\code{diff}] If \code{TRUE} memory summaries use change in memory
rather than current memory
\item[\code{exclude}] Functions to exclude when summarizing the stack trace
for memory summaries
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This function is an alternative to \code{R CMD Rprof}. It provides the
convenience of an all-\R{} implementation but will be slower for large
files.

As the profiling output file could be larger than available memory, it
is read in blocks of \code{chunksize} lines. Increasing \code{chunksize}
will make the function run faster if sufficient memory is available.

When called with \code{memory.profiling=TRUE}, the profiler writes
information on three aspects of memory use: vector memory in small
blocks on the R heap, vector memory in large blocks (from
\code{malloc}), memory in nodes on the R heap.  It also records the number of
calls to the internal function \code{duplicate} in the time
interval. \code{duplicate} is called by C code when arguments need to be
copied. Note that the profiler does not track which function actually
allocated the memory.

With \code{memory="both"} the change in total memory (truncated at zero)
is reported in addition to timing data. 

With \code{memory="tseries"} or \code{memory="stats"} the \code{index}
argument specifies how to summarize the stack trace. A positive number
specifies that many calls from the bottom of the stack; a negative
number specifies the number of calls from the top of the stack.  With
\code{memory="tseries"} the index is used to construct labels and may be
a vector to give multiple sets of labels. With \code{memory="stats"} the
index must be a single number and specifies how to aggregate the data to
the maximum and average of the memory statistics.  With both
\code{memory="tseries"} and \code{memory="stats"} the argument
\code{diff=TRUE} asks for summaries of the increase in memory use over
the sampling interval and \code{diff=FALSE} asks for the memory use at
the end of the interval.
\end{Details}
\begin{Value}
If \code{memory="none"},a  list with components
\begin{ldescription}
\item[\code{by.self}] Timings sorted by \sQuote{self} time
\item[\code{by.total}] Timings sorted by \sQuote{total} time
\item[\code{sampling.time}] Total length of profiling run
\end{ldescription}


If \code{memory="both"} the same list but with memory consumption in Mb
in addition to the timings.  

If \code{memory="tseries"} a data frame giving memory statistics over
time

If \code{memory="stats"} a \code{by} object giving memory statistics by function.
\end{Value}
\begin{SeeAlso}\relax
The chapter on \dQuote{Tidying and profiling R code} in
\dQuote{Writing \R{} Extensions} (see the \file{doc/manual} subdirectory
of the \R{} source tree).

\code{\LinkA{Rprof}{Rprof}}

\code{\LinkA{tracemem}{tracemem}} traces copying of an object via the C function
\code{duplicate}.

\code{\LinkA{Rprofmem}{Rprofmem}} is a non-sampling memory use profiler.

\url{http://developer.r-project.org/memory-profiling.html}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
## Rprof() is not available on all platforms
Rprof(tmp <- tempfile())
example(glm)
Rprof()
summaryRprof(tmp)
unlink(tmp)
## End(Not run)
\end{ExampleCode}
\end{Examples}

