Movatterモバイル変換

pkgnet : Network Analysis of R Packages

Description

R packages can be complex bodies of code and functionality withhard-to-intuit underlying structure.pkgnet provides tools to analyze andunderstand that structure through the lens ofnetwork theory.

Package Report

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

    CreatePackageReport("lubridate")

This will create a standalone HTML report containing analyses of variousaspects 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. Eachtype of reporter is used to analyze a particular aspect of the subjectpackage. The currently available reporters are:

DependencyReporter

analyze the recursivenetwork of packages that the subject package depends on.

FunctionReporter

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

InheritanceReporter

analyze the classinheritance trees for subject packages that use object-orientedprogramming.

SummaryReporter

get an overview of thesubject package through its DESCRIPTION file.

CreatePackageReport uses astandardset of reporters by default. You can customize the reporters you want bypassing 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 reporterinstantiated, check our that reporter's documentation to see what you cando.

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

Author(s)

Maintainer: Brian Burnsbrian.burns.opensource@gmail.com

Authors:

• James Lambjaylamb20@gmail.com

• Jay Qijayqi.opensource@gmail.com

See Also

Useful links:

• https://github.com/uptake/pkgnet

• https://uptake.github.io/pkgnet/

• Report bugs athttps://github.com/uptake/pkgnet/issues

Base class for Graphs

Description

pkgnet uses R6 classes to define and encapsulate the graphmodels for representing package networks. These classes implementdifferent types of graphs and functionality to calculate their respectivegraph theory measures. The base classAbstractGraph defines thestandard interfaces and functionality.

Currently the only implemented type of graph isDirectedGraph.

Active bindings

Methods

Public methods

• AbstractGraph$new()

• AbstractGraph$node_measures()

• AbstractGraph$graph_measures()

• AbstractGraph$print()

• AbstractGraph$clone()

Methodnew()

Instantiate new object of the class.

Usage

AbstractGraph$new(nodes, edges)

Arguments

Returns

Self, invisibly.

Methodnode_measures()

Return specified node-level measures, calculating if necessary.SeeNode Measures section inDirectedGraphMeasures for details about each measure.

Usage

AbstractGraph$node_measures(measures = NULL)

Arguments

Returns

a data.table with specified node meaures as columns

Methodgraph_measures()

Return specified graph-level measures, calculating if necessary. SeeGraph Measures section inDirectedGraphMeasures for details about each measure.

Usage

AbstractGraph$graph_measures(measures = NULL)

Arguments

Returns

list with specified graph measures.

Methodprint()

print igraph object

Usage

AbstractGraph$print()

Returns

Self, invisibly.

Methodclone()

The objects of this class are cloneable with this method.

Usage

AbstractGraph$clone(deep = FALSE)

Arguments

Abstract Network Reporter Class

Description

pkgnet defines several package reporter R6 classes that modela particular network aspect of a package as a graph. These networkreporter classes are extended fromAbstractGraphReporter, whichitself extends theAbstractPackageReporterwith graph-modeling-related functionality.

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

Super class

pkgnet::AbstractPackageReporter ->AbstractGraphReporter

Active bindings

Methods

Public methods

• AbstractGraphReporter$calculate_default_measures()

• AbstractGraphReporter$get_summary_view()

• AbstractGraphReporter$clone()

Methodcalculate_default_measures()

Calculates the default node and network measures for this reporter.

Usage

AbstractGraphReporter$calculate_default_measures()

Returns

Self, invisibly.

Methodget_summary_view()

Creates a summary table formatted for display.

Usage

AbstractGraphReporter$get_summary_view()

Returns

ADT object

Methodclone()

The objects of this class are cloneable with this method.

Usage

AbstractGraphReporter$clone(deep = FALSE)

Arguments

Abstract Package Reporter

Description

pkgnet defines several package reporter R6 classes that analyze some particular aspect of a package. These reporters share commonfunctionality and interfaces defined by a base reporter classAbstractPackageReporter.

Active bindings

Methods

Public methods

• AbstractPackageReporter$set_package()

• AbstractPackageReporter$get_summary_view()

• AbstractPackageReporter$clone()

Methodset_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

Returns

Self, invisibly.

Methodget_summary_view()

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

Usage

AbstractPackageReporter$get_summary_view()

Returns

Self, invisibly.

Methodclone()

The objects of this class are cloneable with this method.

Usage

AbstractPackageReporter$clone(deep = FALSE)

Arguments

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

Value

an instantiatedPackageReport object

pkgnet Report as Vignette

Description

Create pkgnet package report as an R Markdown vignette. Thisvignette can be rendered into a standard HTML vignette with theknitr::rmarkdown vignette engineinto 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 thisfunction, as well asour example for pkgnet.

Usage

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

Arguments

Default Reporters

Description

Instantiates a list of default reporters to feed intoCreatePackageReport.

Usage

DefaultReporters()

Details

Default reporters are:

• SummaryReporter

• DependencyReporter

• FunctionReporter

Note,InheritanceReporter is not included in the default list.

If desired, append a new instance ofInheritanceReporter to theDefaultReporters 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 dependencieson other packages. This allows a developer to understand how individualdependencies might lead to a much larger set of dependencies, potentiallyinforming decisions on including or removing them.

Super classes

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

Active bindings

Methods

Public methods

• DependencyReporter$new()

• DependencyReporter$clone()

Methodnew()

Initialize an instance of the reporter.

Usage

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

Arguments

Returns

Self, invisibly.

Examples

\donttest{# Instantiate an objectreporter <- DependencyReporter$new()# Seed it with a packagereporter$set_package("ggplot2")}

Methodclone()

The objects of this class are cloneable with this method.

Usage

DependencyReporter$clone(deep = FALSE)

Arguments

See Also

Other Network Reporters:FunctionReporter,InheritanceReporter

Other Package Reporters:FunctionReporter,InheritanceReporter,SummaryReporter

Examples

## ------------------------------------------------## Method `DependencyReporter$new`## ------------------------------------------------# Instantiate an objectreporter <- DependencyReporter$new()# Seed it with a packagereporter$set_package("ggplot2")

Directed Graph Network Model

Description

R6 class defining a directed graph model for representing anetwork, including methods to calculate various measures from graphtheory. Theigraph package is used as abackend for calculations.

This class isn't intended to be initialized directly; instead,network reporter objects will initialize it asitspkg_graph field. If you have a network reporter namedreporter, then you access this object's publicinterface throughpkg_graph—for example,

reporter$pkg_graph$node_measures('hubScore')

Super class

pkgnet::AbstractGraph ->DirectedGraph

Active bindings

Methods

Public methods

• DirectedGraph$clone()

Methodclone()

The objects of this class are cloneable with this method.

Usage

DirectedGraph$clone(deep = FALSE)

Arguments

See Also

DirectedGraphMeasures

Measures for Directed Graph Class

Description

Descriptions for all available node and graph measures fornetworks modeled byDirectedGraph.

Node Measures

outDegree

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

inDegree

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

outCloseness

closeness centrality (out), a measure ofpath lengths to other nodes along edge directions.Calculated byigraph::closeness.[Wikipedia]

inCloseness

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

numRecursiveDeps

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

numRecursiveRevDeps

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

betweenness

betweenness centrality, a measure ofthe number of shortest paths in graph passing through this nodeCalculated byigraph::betweenness.[Wikipedia]

pageRank

Google PageRank.Calculated byigraph::page_rank.[Wikipedia]

hubScore

hub score from Hyperlink-Induced TopicSearch (HITS) algorithm.Calculated byigraph::hub_score.[Wikipedia]

authorityScore

authority score fromHyperlink-Induced Topic Search (HITS) algorithm.Calculated byigraph::authority_score.[Wikipedia]

Graph Measures

graphOutDegree

graph freeman centralization foroutdegree. A measure of the most central node by outdegree in relation toall other nodes.Calculated byigraph::centralize.[Wikipedia]

graphInDegree

graph Freeman centralization forindegree. A measure of the most central node by indegree in relation toall other nodes.Calculated byigraph::centralize.[Wikipedia]

graphOutClosness

graph Freeman centralization forout-closeness. A measure of the most central node by out-closeness in relation toall other nodes.Calculated byigraph::centralize.[Wikipedia]

graphInCloseness

graph Freeman centralization foroutdegree. A measure of the most central node by outdegree in relation toall other nodes.Calculated byigraph::centralize.[Wikipedia]

graphBetweennness

graph Freeman centralization forbetweenness A measure of the most central node by betweenness in relation toall other nodes.Calculated byigraph::centralize.[Wikipedia]

Function Interdependency Reporter

Description

This reporter looks at the network of interdependencies of itsdefined functions. Measures of centrality from graph theory can indicatewhich function is most important to a package. Combined with unit testcoverage information—also provided by this reporter— it can be usedas a powerful tool to prioritize test writing.

Details

R6 Method Support:

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

• R6 methods will be named like<classname>$<methodtype>$<methodname>, e.g.,FunctionReporter$private_methods$extract_nodes.

• Note that the class name used will be thename of thegenerator object in the package's namespace.

• Theclassname attribute of the class isnot used.In general, it is not required to be defined or the same as thegenerator object name. This attribute is used primarily forS3 dispatch.

Known Limitations:

• Using non-standard evaluation to refer to things (e.g, dataframecolumn names) that have the same name as a function will trickFunctionReporter into thinking the function was called. Thiscan be avoided if you don't use reuse function names for otherpurposes.

• Functions stored as list items and not assigned to the packagenamespace will be invisible toFunctionReporter.

• Calls to methods of instantiated R6 or reference objects willnot be recognized. We don't have a reliable way of identifyinginstantiated objects, or identifying their class.

• Reference class methods are not yet supported. They will not beidentified as nodes byFunctionReporter.

Super classes

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

Active bindings

Methods

Public methods

• FunctionReporter$calculate_default_measures()

• FunctionReporter$clone()

Methodcalculate_default_measures()

Calculates the default node and network measures for this reporter.

Usage

FunctionReporter$calculate_default_measures()

Returns

Self, invisibly.

Methodclone()

The objects of this class are cloneable with this method.

Usage

FunctionReporter$clone(deep = FALSE)

Arguments

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 inheritancestructure. Currently the following object-oriented systems are supported:

• S4 Classes

• Reference Classes (sometimes informally called "R5")

• R6 Classes

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

Details

Note the following details about class naming:

• Reference Classes : The name passed asClass insetRefClass is used as the nodename by this reporter. This is the class name that is used whenspecifying inheritance. The generator object returned bysetRefClass does not have to beassigned and can have a different name.

• R6 Classes : The name of the generator object in the packagenamespace is used as the node name by this reporter. The generatorobject returned byR6::R6Class is what isused when specifying inheritance. The name passed asclassnamepassed toR6::R6Class can be a different nameor even NULL.

For more info about R's built-in object-oriented systems, check out therelevant chapter inHadleyWickham'sAdvanced R. For more info about R6, check out theirdocs website or the chapter inAdvanced R's second edition.

Super classes

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

Active bindings

Methods

Public methods

• InheritanceReporter$clone()

Methodclone()

The objects of this class are cloneable with this method.

Usage

InheritanceReporter$clone(deep = FALSE)

Arguments

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 packagereport for a specified package.PackageReport is an R6 class thatholds all of those reporters and has a methodrender_report()to generate an HTML report file. You can access each individual reporterand modify it using its methods if you wish.

The functionCreatePackageReport() is a shortcut for bothgenerating aPackageReport object with instantiated reportersand creating the HTML report in one call.

Value

Self, invisibly.

Active bindings

Methods

Public methods

• PackageReport$new()

• PackageReport$add_reporter()

• PackageReport$render_report()

• PackageReport$clone()

Methodnew()

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

Returns

Instantiated package report object.

Methodadd_reporter()

Add a reporter to the package report.

Usage

PackageReport$add_reporter(reporter)

Arguments

Returns

Self, invisibly

Methodrender_report()

Render html pkgnet package report.

Usage

PackageReport$render_report()

Methodclone()

The objects of this class are cloneable with this method.

Usage

PackageReport$clone(deep = FALSE)

Arguments

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

Methods

Public methods

• SummaryReporter$get_summary_view()

• SummaryReporter$clone()

Methodget_summary_view()

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

Usage

SummaryReporter$get_summary_view()

Returns

Self, invisibly.

Methodclone()

The objects of this class are cloneable with this method.

Usage

SummaryReporter$clone(deep = FALSE)

Arguments

See Also

Other Package Reporters:DependencyReporter,FunctionReporter,InheritanceReporter