README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# trace.package

<!-- badges: start -->
<!-- badges: end -->

The goal of trace.package is to make it easy to trace, profile and benchmark 

## Installation

You can install the development version of trace.package like so:

```{r, eval = FALSE}
remotes::install_github("maxsutton/trace.package")
```

## Usage

This is a basic example which shows you how to trace calls of functions from the
`ggplot2` package when creating an empty ggplot scale. `run_trace()` returns a
data.frame that can be analysed in any way that the user would like.
`run_trace()` also accepts a vector of packages to trace.

```{r example}
library(trace.package)

df <- run_trace(ggplot2::scale_y_continuous(), "ggplot2")
head(df)
```

However, `trace.package` comes baked in with some functions to kick-start
analysis of the traces. The first is a traditional flame graph, which shows a
stack of function calls and the time spent in each of those stacks. The ggplot
object is returned, and so you can apply ggplot functions to change the
appearance of the graph.

In this case, it shows also shows some `rlang` functions that are imported by
`ggplot2`.

```{r flame}
gg <- flame_graph(df)

gg
```
Another tool is printing a tree of the function calls, to see the flow of code
when executing an expression. Here we can choose what we want to print, either
the exact call made at each point, or just the function in that call, or any
other variable in the data.frame.

```{r code}
code_tree(df, label = fun)
```

`trace.package` also comes with a useful utility to add colour to the text
labels, in a way just like `dplyr::recode`. We can do that to colour the
`ggplot2` and `rlang` package like in the flame graph above. Colours are limited
to those available in the `crayon` package. It doesn't come across well on
github, but looks good in the console (I promise).

```{r code_colour}
code_tree(df, label = recolour(fun, pkg, "ggplot2" = "red", rlang = "blue"))
```