Type: Package
Title: Get Network Representation of an R Package
Version: 0.5.0
Maintainer: Brian Burns <brian.burns.opensource@gmail.com>
Description: Tools from the domain of graph theory can be used to quantify the complexity and vulnerability to failure of a software package. That is the guiding philosophy of this package. 'pkgnet' provides tools to analyze the dependencies between functions in an R package and between its imported packages. See the pkgnet website for vignettes and other supplementary information.
Imports: assertthat, covr, data.table, DT, futile.logger, glue, igraph(≥ 1.3), knitr, magrittr, methods, R6, rlang, rmarkdown(≥ 1.9), tools, visNetwork
Suggests: ggplot2, pkgdown, testthat, webshot, withr
License: BSD_3_clause + file LICENSE
URL: https://github.com/uptake/pkgnet, https://uptake.github.io/pkgnet/
BugReports: https://github.com/uptake/pkgnet/issues
RoxygenNote: 7.3.1
NeedsCompilation: no
Packaged: 2024-05-03 20:45:00 UTC; brianburns
Author: Brian Burns [aut, cre], James Lamb [aut], Jay Qi [aut]
Repository: CRAN
Date/Publication: 2024-05-03 21:00:02 UTC

pkgnet : Network Analysis of R Packages

Description

R packages can be complex bodies of code and functionality with hard-to-intuit underlying structure. pkgnet provides tools to analyze and understand that structure through the lens of network theory.

Package Report

The simplest way of using pkgnet is through the function CreatePackageReport, e.g.,

    CreatePackageReport("lubridate")

This will create a standalone HTML report containing analyses of various aspects of the specified subject package.

For more info, check out our introductory vignette with

    vignette("pkgnet-intro")

Individual Reporters

Reporters are the basic modules of functionality within pkgnet. Each type of reporter is used to analyze a particular aspect of the subject package. The currently available reporters are:

DependencyReporter

analyze the recursive network of packages that the subject package depends on.

FunctionReporter

analyze the network of interdependencies of the functions defined in the subject package

InheritanceReporter

analyze the class inheritance trees for subject packages that use object-oriented programming.

SummaryReporter

get an overview of the subject package through its DESCRIPTION file.

CreatePackageReport uses a standard set of reporters by default. You can customize the reporters you want by passing in your own list of instantiated reporters, e.g.

      CreatePackageReport(
          "lubridate",
          pkg_reporters = list(FunctionReporter$new(), InheritanceReporter$new())
      )
  

You can also use reporters interactively. Once you have a reporter instantiated, check our that reporter's documentation to see what you can do.

      reporter <- DependencyReporter$new()
      reporter$set_package("lubridate")
  

Author(s)

Maintainer: Brian Burns brian.burns.opensource@gmail.com

Authors:

See Also

Useful links:


Base class for Graphs

Description

pkgnet uses R6 classes to define and encapsulate the graph models for representing package networks. These classes implement different types of graphs and functionality to calculate their respective graph theory measures. The base class AbstractGraph defines the standard interfaces and functionality.

Currently the only implemented type of graph is DirectedGraph.

Active bindings

nodes

node data.table, read-only.

edges

edge data.table, read-only.

igraph

igraph object, read-only.

available_node_measures

character vector of all supported node measures. See Node Measures section in DirectedGraphMeasures for details about each measure.

available_graph_measures

character vector of all supported graph measures. See Graph Measures section in DirectedGraphMeasures for details about each measure. Read-only.

default_node_measures

character vector of default node measures. See Node Measures section in DirectedGraphMeasures for details about each measure.

default_graph_measures

character vector of default graph measures. See Graph Measures section in DirectedGraphMeasures for details about each measure. Read-only.

Methods

Public methods


Method new()

Instantiate new object of the class.

Usage
AbstractGraph$new(nodes, edges)
Arguments
nodes

a data.table containing nodes

edges

a data.table containing edges

Returns

Self, invisibly.


Method node_measures()

Return specified node-level measures, calculating if necessary. See Node Measures section in DirectedGraphMeasures for details about each measure.

Usage
AbstractGraph$node_measures(measures = NULL)
Arguments
measures

character vector of measure names. Default NULL will return those that are already calculated.

Returns

a data.table with specified node meaures as columns


Method graph_measures()

Return specified graph-level measures, calculating if necessary. See Graph Measures section in DirectedGraphMeasures for details about each measure.

Usage
AbstractGraph$graph_measures(measures = NULL)
Arguments
measures

character vector of measure names. Default NULL will return those that are already calculated.

Returns

list with specified graph measures.


Method print()

print igraph object

Usage
AbstractGraph$print()
Returns

Self, invisibly.


Method clone()

The objects of this class are cloneable with this method.

Usage
AbstractGraph$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.


Abstract Network Reporter Class

Description

pkgnet defines several package reporter R6 classes that model a particular network aspect of a package as a graph. These network reporter classes are extended from AbstractGraphReporter, which itself extends the AbstractPackageReporter with graph-modeling-related functionality.

This article describes the additional fields added by the AbstractGraphReporter class definition.

Super class

pkgnet::AbstractPackageReporter -> AbstractGraphReporter

Active bindings

nodes

A data.table, containing information about the nodes of the network the reporter is analyzing. The node column acts the identifier. Read-only.

edges

A data.table, containing information about the edge connections of the network the reporter is analyzing. Each row is one edge, and the columns SOURCE and TARGET specify the node identifiers. Read-only.

network_measures

A list, containing any measures of the network calculated by the reporter. Read-only.

pkg_graph

a graph model object. See DirectedGraph for additional documentation. Read-only.

graph_viz

a graph visualization object. A visNetwork::visNetwork object. Read-only.

layout_type

a character string, the current layout type for the graph visualization. Can be assigned a new valid layout type value. Use use grep("^layout_\\S", getNamespaceExports("igraph"), value = TRUE) to see valid options.

Methods

Public methods

Inherited methods

Method calculate_default_measures()

Calculates the default node and network measures for this reporter.

Usage
AbstractGraphReporter$calculate_default_measures()
Returns

Self, invisibly.


Method get_summary_view()

Creates a summary table formatted for display.

Usage
AbstractGraphReporter$get_summary_view()
Returns

A DT object


Method clone()

The objects of this class are cloneable with this method.

Usage
AbstractGraphReporter$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.


Abstract Package Reporter

Description

pkgnet defines several package reporter R6 classes that analyze some particular aspect of a package. These reporters share common functionality and interfaces defined by a base reporter class AbstractPackageReporter.

Active bindings

pkg_name

(character string) name of set package. Read-only.

report_markdown_path

(character string) path to R Markdown template for this reporter. Read-only.

Methods

Public methods


Method set_package()

Set the package that the reporter will analyze. This can only be done once for a given instance of a reporter. Instantiate a new copy of the reporter if you need to analyze a different package.

Usage
AbstractPackageReporter$set_package(pkg_name, pkg_path = NULL)
Arguments
pkg_name

(character string) name of package

pkg_path

(character string) optional directory path to source code of the package. It is used for calculating test coverage. It can be an absolute or relative path.

Returns

Self, invisibly.


Method get_summary_view()

Returns an htmlwidget object that summarizes the analysis of the reporter. Used when creating a package report.

Usage
AbstractPackageReporter$get_summary_view()
Returns

Self, invisibly.


Method clone()

The objects of this class are cloneable with this method.

Usage
AbstractPackageReporter$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.


pkgnet Analysis Report for an R package

Description

Create a standalone HTML report about a package and its networks.

Usage

CreatePackageReport(
  pkg_name,
  pkg_reporters = DefaultReporters(),
  pkg_path = NULL,
  report_path = tempfile(pattern = pkg_name, fileext = ".html")
)

Arguments

pkg_name

(string) name of a package

pkg_reporters

(list) a list of package reporters

pkg_path

(string) The path to the package repository. If given, coverage will be calculated for each function. pkg_path can be an absolute or relative path.

report_path

(string) The path and filename of the output report. Default report will be produced in the temporary directory.

Value

an instantiated PackageReport object


pkgnet Report as Vignette

Description

Create pkgnet package report as an R Markdown vignette. This vignette can be rendered into a standard HTML vignette with the knitr::rmarkdown vignette engine into HTML vignettes upon package building. It is also compatible with #' pkgdown sites. See the vignette "Publishing Your pkgnet Package Report" for details about how to use this function, as well as our example for pkgnet.

Usage

CreatePackageVignette(
  pkg = ".",
  pkg_reporters = list(DependencyReporter$new(), FunctionReporter$new()),
  vignette_path = file.path(pkg, "vignettes", "pkgnet-report.Rmd")
)

Arguments

pkg

(string) path to root directory of package of interest

pkg_reporters

(list) a list of initialized package reporters

vignette_path

(string) The location of a file to store the output vignette file at. Must be an .Rmd file. By default, this will be '<pkg>/vignettes/pkgnet-report.Rmd' relative to the input to pkg


Default Reporters

Description

Instantiates a list of default reporters to feed into CreatePackageReport.

Usage

DefaultReporters()

Details

Default reporters are:

Note, InheritanceReporter is not included in the default list.

If desired, append a new instance of InheritanceReporter to the DefaultReporters list.

ex: c(DefaultReporters(), InheritanceReporter$new())

Value

list of instantiated reporter objects


Recursive Package Dependency Reporter

Description

This reporter looks at the recursive network of its dependencies on other packages. This allows a developer to understand how individual dependencies might lead to a much larger set of dependencies, potentially informing decisions on including or removing them.

Super classes

pkgnet::AbstractPackageReporter -> pkgnet::AbstractGraphReporter -> DependencyReporter

Active bindings

report_markdown_path

(character string) path to R Markdown template for this reporter. Read-only.

Methods

Public methods

Inherited methods

Method new()

Initialize an instance of the reporter.

Usage
DependencyReporter$new(
  dep_types = c("Imports", "Depends", "LinkingTo"),
  installed = TRUE
)
Arguments
dep_types

(character vector) The sections within the DESCRIPTION file to be counted as dependencies. By default, c("Imports", "Depends", "LinkingTo") is chosen.

installed

(logical) If TRUE, consider only installed packages when building dependency network.

Returns

Self, invisibly.

Examples
\donttest{

# Instantiate an object
reporter <- DependencyReporter$new()

# Seed it with a package
reporter$set_package("ggplot2")

}

Method clone()

The objects of this class are cloneable with this method.

Usage
DependencyReporter$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

See Also

Other Network Reporters: FunctionReporter, InheritanceReporter

Other Package Reporters: FunctionReporter, InheritanceReporter, SummaryReporter

Examples


## ------------------------------------------------
## Method `DependencyReporter$new`
## ------------------------------------------------



# Instantiate an object
reporter <- DependencyReporter$new()

# Seed it with a package
reporter$set_package("ggplot2")



Directed Graph Network Model

Description

R6 class defining a directed graph model for representing a network, including methods to calculate various measures from graph theory. The igraph package is used as a backend for calculations.

This class isn't intended to be initialized directly; instead, network reporter objects will initialize it as its pkg_graph field. If you have a network reporter named reporter, then you access this object's public interface through pkg_graph—for example,

reporter$pkg_graph$node_measures('hubScore')

Super class

pkgnet::AbstractGraph -> DirectedGraph

Active bindings

default_node_measures

character vector of default node measures. See Node Measures section in DirectedGraphMeasures for details about each measure. Read-only.

default_graph_measures

character vector of default graph measures. See Graph Measures section in DirectedGraphMeasures for details about each measure. Read-only.

Methods

Public methods

Inherited methods

Method clone()

The objects of this class are cloneable with this method.

Usage
DirectedGraph$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

See Also

DirectedGraphMeasures


Measures for Directed Graph Class

Description

Descriptions for all available node and graph measures for networks modeled by DirectedGraph.

Node Measures

outDegree

outdegree, the number of outward edges (tail ends). Calculated by igraph::degree. [Wikipedia]

inDegree

indegree, number of inward edges (head ends). Calculated by igraph::degree. [Wikipedia]

outCloseness

closeness centrality (out), a measure of path lengths to other nodes along edge directions. Calculated by igraph::closeness. [Wikipedia]

inCloseness

closeness centrality (in), a measure of path lengths to other nodes in reverse of edge directions. Calculated by igraph::closeness. [Wikipedia]

numRecursiveDeps

number recursive dependencies, i.e., count of all nodes reachable by following edges out from this node. Calculated by igraph::neighborhood.size. [Wikipedia]

numRecursiveRevDeps

number of recursive reverse dependencies (dependents), i.e., count all nodes reachable by following edges into this node in reverse direction. Calculated by igraph::neighborhood.size. [Wikipedia]

betweenness

betweenness centrality, a measure of the number of shortest paths in graph passing through this node Calculated by igraph::betweenness. [Wikipedia]

pageRank

Google PageRank. Calculated by igraph::page_rank. [Wikipedia]

hubScore

hub score from Hyperlink-Induced Topic Search (HITS) algorithm. Calculated by igraph::hub_score. [Wikipedia]

authorityScore

authority score from Hyperlink-Induced Topic Search (HITS) algorithm. Calculated by igraph::authority_score. [Wikipedia]

Graph Measures

graphOutDegree

graph freeman centralization for outdegree. A measure of the most central node by outdegree in relation to all other nodes. Calculated by igraph::centralize. [Wikipedia]

graphInDegree

graph Freeman centralization for indegree. A measure of the most central node by indegree in relation to all other nodes. Calculated by igraph::centralize. [Wikipedia]

graphOutClosness

graph Freeman centralization for out-closeness. A measure of the most central node by out-closeness in relation to all other nodes. Calculated by igraph::centralize. [Wikipedia]

graphInCloseness

graph Freeman centralization for outdegree. A measure of the most central node by outdegree in relation to all other nodes. Calculated by igraph::centralize. [Wikipedia]

graphBetweennness

graph Freeman centralization for betweenness A measure of the most central node by betweenness in relation to all other nodes. Calculated by igraph::centralize. [Wikipedia]


Function Interdependency Reporter

Description

This reporter looks at the network of interdependencies of its defined functions. Measures of centrality from graph theory can indicate which function is most important to a package. Combined with unit test coverage information—also provided by this reporter— it can be used as a powerful tool to prioritize test writing.

Details

R6 Method Support:

R6 classes are supported, with their methods treated as functions by the reporter.

Known Limitations:

Super classes

pkgnet::AbstractPackageReporter -> pkgnet::AbstractGraphReporter -> FunctionReporter

Active bindings

report_markdown_path

(character string) path to R Markdown template for this reporter. Read-only.

Methods

Public methods

Inherited methods

Method calculate_default_measures()

Calculates the default node and network measures for this reporter.

Usage
FunctionReporter$calculate_default_measures()
Returns

Self, invisibly.


Method clone()

The objects of this class are cloneable with this method.

Usage
FunctionReporter$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

See Also

Other Network Reporters: DependencyReporter, InheritanceReporter

Other Package Reporters: DependencyReporter, InheritanceReporter, SummaryReporter


Class Inheritance Reporter

Description

This reporter takes a package and traces the class inheritance structure. Currently the following object-oriented systems are supported:

S3 classes are not supported, as their inheritance is defined on an ad hoc basis per object and not formally by class definitions.

Details

Note the following details about class naming:

For more info about R's built-in object-oriented systems, check out the relevant chapter in Hadley Wickham's Advanced R. For more info about R6, check out their docs website or the chapter in Advanced R's second edition.

Super classes

pkgnet::AbstractPackageReporter -> pkgnet::AbstractGraphReporter -> InheritanceReporter

Active bindings

report_markdown_path

(character string) path to R Markdown template for this reporter. Read-only.

Methods

Public methods

Inherited methods

Method clone()

The objects of this class are cloneable with this method.

Usage
InheritanceReporter$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

See Also

Other Network Reporters: DependencyReporter, FunctionReporter

Other Package Reporters: DependencyReporter, FunctionReporter, SummaryReporter


R6 Class Representing an R Package Report

Description

pkgnet compiles one or more package reporters into a package report for a specified package. PackageReport is an R6 class that holds all of those reporters and has a method render_report() to generate an HTML report file. You can access each individual reporter and modify it using its methods if you wish.

The function CreatePackageReport() is a shortcut for both generating a PackageReport object with instantiated reporters and creating the HTML report in one call.

Value

Self, invisibly.

Active bindings

pkg_name

(character string) name of package. Read-only.

pkg_path

(character string) path to source code of the package. Read-only.

report_path

(character string) path and filename of output report.

SummaryReporter

Instantiated pkgnet SummaryReporter object

DependencyReporter

Instantiated pkgnet DependencyReporter object

FunctionReporter

Instantiated pkgnet FunctionReporter object

InheritanceReporter

Instantiated pkgnet InheritanceReporter object

Methods

Public methods


Method new()

Initialize an instance of a package report object.

Usage
PackageReport$new(
  pkg_name,
  pkg_path = NULL,
  report_path = tempfile(pattern = pkg_name, fileext = ".html")
)
Arguments
pkg_name

(character string) name of package

pkg_path

(character string) optional directory path to source code of the package. It is used for calculating test coverage. It can be an absolute or relative path.

report_path

(character string) The path and filename of the output report. Default report will be produced in the temporary directory.

Returns

Instantiated package report object.


Method add_reporter()

Add a reporter to the package report.

Usage
PackageReport$add_reporter(reporter)
Arguments
reporter

Instantiated package reporter object

Returns

Self, invisibly


Method render_report()

Render html pkgnet package report.

Usage
PackageReport$render_report()

Method clone()

The objects of this class are cloneable with this method.

Usage
PackageReport$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.


Package Summary Reporter

Description

This reporter provides a high-level overview of a package via its package DESCRIPTION file.

Super class

pkgnet::AbstractPackageReporter -> SummaryReporter

Active bindings

report_markdown_path

(character string) path to R Markdown template for this reporter. Read-only.

Methods

Public methods

Inherited methods

Method get_summary_view()

Returns an htmlwidget object that summarizes the analysis of the reporter. Used when creating a package report.

Usage
SummaryReporter$get_summary_view()
Returns

Self, invisibly.


Method clone()

The objects of this class are cloneable with this method.

Usage
SummaryReporter$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

See Also

Other Package Reporters: DependencyReporter, FunctionReporter, InheritanceReporter