Have you ever wanted to visualize dependencies between functions for a group of R packages you have developed?
pkgdepR
takes any number of (correctly compiled) R packages and finds
the links between all of the function in those namespaces.
pkgdepR
was created to solve a particular problem when developing
interrelated R packages and wanting to see how all the functions in each
package interacted.
This was particularly useful in managing the function dependencies across a large code base of R packages.
pkgdepR
simply takes as an argument a vector of package names (that
should already be on the search path) and explores how each of the
functions in each of the namespaces interact. It does this in two
stages:
- Getting all intra-package function dependencies for each package; and
- Getting all inter-package function dependencies for each combination of packages.
Each defined name in a particular package’s namespace that is also a
function is then decomposed. From this decomposition, if any function is
found to be called within its contents, then a link is created. To
properly identify distinct name calls, a search is done for a package
tag preceding the name (i.e. ::
). If no tag exists, then a search for
an imported function is conducted. On the other hand, if the function
name is already declared in the primary namespace, then it is obviously
that function being called.
If a function is ambiguously called (without a package tag or not being explicitly imported from another namespace) then it is deliberately ignored in the linkage. This is because the linkage would be environment-dependent and would change depending on the contents of the search path in that particular session.
The main wrapper function for pkgdepR
is pkgdepR::deps(...)
which
returns an object of class pkgdepR
. An S3 method has been created for
objects of class pkgdepR
so they can be easily plotted. See
?pkgdepR::plot.pkgdepR
for further details.
pkgdepR
makes use of the fantastic
visNetwork package for
creating an interactive network visualization of the functions present
in R packages.
All implemented methods for this class are:
methods(class = "pkgdepR")
#> [1] plot print summary
#> see '?methods' for accessing help and source code
The links between functions are determined statically, meaning the
dependencies are identified without executing any code. As such, any
functions that are defined dynamically at run-time will not be picked
up. In the example below, foo()
will be picked up as it is declared in
the package’s namespace. However, bar()
will not be picked up as it is
only defined at run-time when foo()
is called.
# @title foo function
# @export
foo = function() { # - this will be picked up!
bar = function() { # - this won't be picked up!
}
bar()
}
Similarly, there can be cases where linkages are created that may not
occur at run-time. Let’s add to the previous example, by adding a
function bar()
declared in the package namespace we are interested in.
# @title bar function
# @export
bar = function() { # - this will be picked up!
}
Then, statically, it appears that foo()
is calling the bar()
from
the namespace we are interested in. However, at run-time, we know this
is not the case, as bar()
is clearly defined locally and it is the
local function that is called. In this instance, pkgdepR
will show a
link between package::foo()
and package::bar()
when no real run-time
dependency exists.
These cases will rarely arise in normal package development, but it is important to be aware of the behaviour nonetheless.
You can install the released version of pkgdepR
from
CRAN with:
install.packages("pkgdepR")
And the development version from GitHub with:
devtools::install_github("edpeyton/pkgdepR")
Here we’ll show an example of how to use pkgdepR
.
First, let’s load the required packages.
library(magrittr)
library(pkgdepR)
The required packages have now been added to the search path.
Create a pkgdepR
object as follows:
v = pkgdepR::deps(pkg = "pkgdepR")
We can see a summary of the object
v
#>
#> pkgdepR object
#> ------------------------------
#> Packages: pkgdepR
#> Total nodes: 16
#> Total links: 17
#> -Between packages: 0
#> -Within packages: 17
#> --Between functions: 16
#> --Self-referential: 1
To see the network visualization, simply call plot.
plot(dep)
Visualizing multiple packages works in a similar way.
v = pkgdepR::deps(pkg = c("pkgdepR", "magrittr"))
v # alternatively, summary(v) or print(v)
#>
#> pkgdepR object
#> ------------------------------
#> Packages: pkgdepR, magrittr
#> Total nodes: 64
#> Total links: 30
#> -Between packages: 6
#> -Within packages: 24
#> --Between functions: 23
#> --Self-referential: 1
plot(v)