Title: | Risk Metrics to Evaluating R Packages |
---|---|
Description: | Facilities for assessing R packages against a number of metrics to help quantify their robustness. |
Authors: | R Validation Hub [aut], Doug Kelkhoff [aut], Marly Gotti [aut], Eli Miller [cre, aut], Kevin K [aut], Yilong Zhang [aut], Eric Milliman [aut], Juliane Manitz [aut], Mark Padgham [ctb], PSI special interest group Application and Implementation of Methodologies in Statistics [cph] |
Maintainer: | Eli Miller <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.2.4.9000 |
Built: | 2024-11-22 05:39:27 UTC |
Source: | https://github.com/pharmar/riskmetric |
A default list of assessments to perform for each package
all_assessments()
all_assessments()
a list of assess_* functions exported from riskmetric
pkg_metric
Convert an object to a pkg_metric
as_pkg_metric(x, class = c())
as_pkg_metric(x, class = c())
x |
data to store as a |
class |
a subclass to differentiate the |
a pkg_metric
object
Assess a package code coverage using the 'covr' package
assess_covr_coverage(x, ...)
assess_covr_coverage(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing a list containing fields 'filecoverage' and 'totalcoverage' containing a named numeric vector of file unit test coverage and a singular numeric value representing overall test coverage respectively.
metric_score.pkg_metric_covr_coverage
## Not run: assess_covr_coverage(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_covr_coverage(pkg_ref("riskmetric")) ## End(Not run)
Only Depends, Imports and LinkingTo dependencies are assessed because they are required
assess_dependencies(x, ...)
assess_dependencies(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
The more packages a package relies on the more chances for errors exist.
a pkg_metric
containing a dataframe of package names and they type of dependency the package being assess has to them
metric_score.pkg_metric_dependencies
## Not run: assess_dependencies(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_dependencies(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for the number of downloads in the past year
assess_downloads_1yr(x, ...)
assess_downloads_1yr(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
The more times a package has been downloaded the more extensive the user testing and the greater chance there is of someone finding a bug and logging it.
a pkg_metric
containing a numeric value between [0,1] indicating the volume of downloads
metric_score.pkg_metric_downloads_1yr
## Not run: assess_downloads_1yr(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_downloads_1yr(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for availability of documentation for exported values
assess_export_help(x, ...)
assess_export_help(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing a logical vector indicating existence of documentation for each namespace export
metric_score.pkg_metric_export_help
## Not run: assess_export_help(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_export_help(pkg_ref("riskmetric")) ## End(Not run)
Assess a package's results from running R CMD check
assess_exported_namespace(x, ...)
assess_exported_namespace(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing List of functions and objects exported by a package, excluding S3methods
metric_score.pkg_metric_exported_namespace
## Not run: assess_exported_namespace(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_exported_namespace(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for the presence of a url field where bugs can be reported.
assess_has_bug_reports_url(x, ...)
assess_has_bug_reports_url(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing a character value containing the BugReports field contents
metric_score.pkg_metric_has_bug_reports_url
## Not run: assess_has_bug_reports_url(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_has_bug_reports_url(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for the presence of example or usage fields in function documentation
assess_has_examples(x, ...)
assess_has_examples(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing an integer value indicating the proportion of discovered files with examples
metric_score.pkg_metric_has_examples
## Not run: assess_has_examples(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_has_examples(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for an associated maintainer
assess_has_maintainer(x, ...)
assess_has_maintainer(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing a character vector of maintainers associated with the package
metric_score.pkg_metric_has_maintainer
## Not run: assess_has_maintainer(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_has_maintainer(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for the presence of a NEWS file
assess_has_news(x, ...)
assess_has_news(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing an integer value indicating the number of discovered NEWS files
metric_score.pkg_metric_has_news
## Not run: assess_has_news(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_has_news(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for an associated source control url
assess_has_source_control(x, ...)
assess_has_source_control(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing a character vector of source control urls associated with the package
metric_score.pkg_metric_has_source_control
## Not run: assess_has_source_control(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_has_source_control(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for the presence of Vignettes files
assess_has_vignettes(x, ...)
assess_has_vignettes(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing an integer value indicating the number of discovered vignettes files
metric_score.pkg_metric_has_vignettes
## Not run: assess_has_vignettes(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_has_vignettes(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for an associated website url
assess_has_website(x, ...)
assess_has_website(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing a character vector of website urls associated with the package
metric_score.pkg_metric_has_website
## Not run: assess_has_website(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_has_website(pkg_ref("riskmetric")) ## End(Not run)
Assess how many recent BugReports have been closed
assess_last_30_bugs_status(x, ...)
assess_last_30_bugs_status(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing a logical vector indicating whether a recent BugReport was closed
metric_score.pkg_metric_last_30_bugs_status
## Not run: assess_last_30_bugs_status(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_last_30_bugs_status(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for an acceptable license
assess_license(x, ...)
assess_license(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing a string indicating the license under which the package is released
metric_score.pkg_metric_license
## Not run: assess_license(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_license(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for an up-to-date NEWS file
assess_news_current(x, ...)
assess_news_current(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing a logical vector indicating whether each discovered NEWS file is up-to-date
metric_score.pkg_metric_news_current
## Not run: assess_news_current(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_news_current(pkg_ref("riskmetric")) ## End(Not run)
Assess a package's results from running R CMD check
assess_r_cmd_check(x, ...)
assess_r_cmd_check(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing Tally of errors, warnings and notes from running R CMD check locally
metric_score.pkg_metric_r_cmd_check
## Not run: assess_r_cmd_check(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_r_cmd_check(pkg_ref("riskmetric")) ## End(Not run)
Assess package checks from CRAN/Bioc or R CMD check
assess_remote_checks(x, ...)
assess_remote_checks(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing Tally of R CMD check results run on differnt OS flavors by BioC or CRAN
metric_score.pkg_metric_remote_checks
## Not run: assess_remote_checks(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_remote_checks(pkg_ref("riskmetric")) ## End(Not run)
Generate list of Reverse Dependencies for a package
assess_reverse_dependencies(x, ...)
assess_reverse_dependencies(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
The more packages that depend on a package the more chance for errors/bugs to be found
a pkg_metric
containing A character vector of reverse dependencies
metric_score.pkg_metric_reverse_dependencies
## Not run: assess_reverse_dependencies(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_reverse_dependencies(pkg_ref("riskmetric")) ## End(Not run)
Assess a package for size of code base
assess_size_codebase(x, ...)
assess_size_codebase(x, ...)
x |
a |
... |
additional arguments passed on to S3 methods, rarely used |
a pkg_metric
containing a numeric value for number of lines of code base for a package
metric_score.pkg_metric_size_codebase
## Not run: assess_size_codebase(pkg_ref("riskmetric")) ## End(Not run)
## Not run: assess_size_codebase(pkg_ref("riskmetric")) ## End(Not run)
Error handler for assessments to deescalate errors to warnings
assessment_error_as_warning(e, name, assessment)
assessment_error_as_warning(e, name, assessment)
e |
an error raised during a package reference assessment |
name |
the name of the package whose package reference assessment raised the error |
assessment |
the name of the assessment function which raised the error |
a pkg_metric object of pkg_metric_error subclass
Other assessment error handlers:
assessment_error_empty()
,
assessment_error_throw()
Error handler for assessments with safe fallback
assessment_error_empty(e, ...)
assessment_error_empty(e, ...)
e |
an error raised during a package reference assessment |
... |
additional arguments unused |
a pkg_metric object of pkg_metric_error subclass
Other assessment error handlers:
assessment_error_as_warning()
,
assessment_error_throw()
Error handler for assessments to throw error immediately
assessment_error_throw(e, name, assessment)
assessment_error_throw(e, name, assessment)
e |
an error raised during a package reference assessment |
name |
the name of the package whose package reference assessment raised the error |
assessment |
the name of the assessment function which raised the error |
the error encountered during assessment
Other assessment error handlers:
assessment_error_as_warning()
,
assessment_error_empty()
Get a specific set of assess_* functions for pkg_assess
get_assessments(fxn_string = "")
get_assessments(fxn_string = "")
fxn_string |
vector of assess functions |
a list of specific assess_* functions exported from riskmetric
Convert a package metric into a numeric value between 0 to 1
metric_score(x, ...)
metric_score(x, ...)
x |
A |
... |
Additional arguments unused |
score of a package risk metric
Returns the overall test coverage from a covr coverage report
## S3 method for class 'pkg_metric_covr_coverage' metric_score(x, ...)
## S3 method for class 'pkg_metric_covr_coverage' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
A numeric
## Not run: metric_score(assess_covr_coverage(pkg_ref("riskmetric")))
## Not run: metric_score(assess_covr_coverage(pkg_ref("riskmetric")))
Calculates a regularized score based on the number of dependencies a package has.
Convert the number of dependencies NROW(x)
into a validation
score [0,1]
## S3 method for class 'pkg_metric_dependencies' metric_score(x, ...)
## S3 method for class 'pkg_metric_dependencies' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
The scoring function is the classic logistic curve
, sigmoid midpoint is 5 reverse dependencies, ie.
,
and logistic growth rate of
.
numeric value between 0
(high number of dependencies) and
1
(low number of dependencies)
## Not run: metric_score(assess_dependencies(pkg_ref("riskmetric")))
## Not run: metric_score(assess_dependencies(pkg_ref("riskmetric")))
Score a package for the number of downloads in the past year regularized
Convert the number of downloads x
in the past year into a validation
score [0,1]
## S3 method for class 'pkg_metric_downloads_1yr' metric_score(x, ...)
## S3 method for class 'pkg_metric_downloads_1yr' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
The scoring function is a simplification of the classic logistic curve
with a log scale for the number of downloads
, sigmoid midpoint is 1000 downloads, ie.
, and logistic growth rate of
.
numeric value between 0
(low) and 1
(high download
volume) converting the number of downloads.
## Not run: metric_score(assess_downloads_1yr(pkg_ref("riskmetric")))
## Not run: metric_score(assess_downloads_1yr(pkg_ref("riskmetric")))
Coerce a logical vector indicating availability of export documentation
## S3 method for class 'pkg_metric_export_help' metric_score(x, ...)
## S3 method for class 'pkg_metric_export_help' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
1
if any NEWS files are found, otherwise 0
## Not run: metric_score(assess_export_help(pkg_ref("riskmetric")))
## Not run: metric_score(assess_export_help(pkg_ref("riskmetric")))
Score a package for the number of exported objects it has; regularized
Convert the number of exported objects length(x)
into a validation
score [0,1]
## S3 method for class 'pkg_metric_exported_namespace' metric_score(x, ...)
## S3 method for class 'pkg_metric_exported_namespace' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
The scoring function is the classic logistic curve
with a square root scale for the number of exported objects
, sigmoid midpoint is 25 exported objects, ie.
, and logistic growth rate of
.
numeric value between 0
(high number of exported objects) and
1
(low number of exported objects)
## Not run: metric_score(assess_exported_namespace(pkg_ref("riskmetric")))
## Not run: metric_score(assess_exported_namespace(pkg_ref("riskmetric")))
Score a package for the presence of a bug report url
## S3 method for class 'pkg_metric_has_bug_reports_url' metric_score(x, ...)
## S3 method for class 'pkg_metric_has_bug_reports_url' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
A logical value indicating whether the package has a BugReports field filled in
## Not run: metric_score(assess_has_bug_reports_url(pkg_ref("riskmetric")))
## Not run: metric_score(assess_has_bug_reports_url(pkg_ref("riskmetric")))
Coerce a logical vector indicating availability of example or usage documentation
## S3 method for class 'pkg_metric_has_examples' metric_score(x, ...)
## S3 method for class 'pkg_metric_has_examples' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
1
if any example or usage fields are found, otherwise 0
## Not run: metric_score(assess_has_examples(pkg_ref("riskmetric")))
## Not run: metric_score(assess_has_examples(pkg_ref("riskmetric")))
Coerce a list of maintainers into a numeric value indicating whether the number of listed maintainers is greater than 0.
## S3 method for class 'pkg_metric_has_maintainer' metric_score(x, ...)
## S3 method for class 'pkg_metric_has_maintainer' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
1
if any maintainer is provided, otherwise 0
## Not run: metric_score(assess_has_maintainer(pkg_ref("riskmetric")))
## Not run: metric_score(assess_has_maintainer(pkg_ref("riskmetric")))
Coerce the number of news files to binary indication of valid NEWS files
## S3 method for class 'pkg_metric_has_news' metric_score(x, ...)
## S3 method for class 'pkg_metric_has_news' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
1
if any NEWS files are found, otherwise 0
## Not run: metric_score(assess_has_news(pkg_ref("riskmetric")))
## Not run: metric_score(assess_has_news(pkg_ref("riskmetric")))
Coerce a list of source control urls into a numeric value indicating whether the number of listed urls is greater than 0.
## S3 method for class 'pkg_metric_has_source_control' metric_score(x, ...)
## S3 method for class 'pkg_metric_has_source_control' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
1
if any source control url is provided, otherwise 0
## Not run: metric_score(assess_has_source_control(pkg_ref("riskmetric")))
## Not run: metric_score(assess_has_source_control(pkg_ref("riskmetric")))
Coerce the number of vignettes files to binary indication of valid Vignettes
## S3 method for class 'pkg_metric_has_vignettes' metric_score(x, ...)
## S3 method for class 'pkg_metric_has_vignettes' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
1
if any Vignettes files are found, otherwise 0
## Not run: metric_score(assess_has_vignettes(pkg_ref("riskmetric")))
## Not run: metric_score(assess_has_vignettes(pkg_ref("riskmetric")))
Coerce a list of website urls into a numeric value indicating whether the number of listed urls is greater than 0.
## S3 method for class 'pkg_metric_has_website' metric_score(x, ...)
## S3 method for class 'pkg_metric_has_website' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
1
if any website url is provided, otherwise 0
## Not run: metric_score(assess_has_website(pkg_ref("riskmetric")))
## Not run: metric_score(assess_has_website(pkg_ref("riskmetric")))
Score a package for number of recently opened BugReports that are now closed
## S3 method for class 'pkg_metric_last_30_bugs_status' metric_score(x, ...)
## S3 method for class 'pkg_metric_last_30_bugs_status' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
a fractional value indicating percentage of last 30 bug reports that are now closed
## Not run: metric_score(assess_last_30_bugs_status(pkg_ref("riskmetric")))
## Not run: metric_score(assess_last_30_bugs_status(pkg_ref("riskmetric")))
Maps a license string to a score
## S3 method for class 'pkg_metric_license' metric_score(x, ...)
## S3 method for class 'pkg_metric_license' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
score of metric license
## Not run: metric_score(assess_license(pkg_ref("riskmetric")))
## Not run: metric_score(assess_license(pkg_ref("riskmetric")))
Coerce a logical vector of discovered up-to-date NEWS to a metric score
## S3 method for class 'pkg_metric_news_current' metric_score(x, ...)
## S3 method for class 'pkg_metric_news_current' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
1
if any NEWS files are up-to-date, otherwise 0
## Not run: metric_score(assess_news_current(pkg_ref("riskmetric")))
## Not run: metric_score(assess_news_current(pkg_ref("riskmetric")))
The scoring function is the weighted sum of notes (0.1), errors (1) and warnings (0.25), with a maximum score of 1 (no errors, notes or warnings) and a minimum score of 0. Essentially, the metric will allow up to 10 notes, 1 error or 4 warnings before returning the lowest score of 0
## S3 method for class 'pkg_metric_r_cmd_check' metric_score(x, ...)
## S3 method for class 'pkg_metric_r_cmd_check' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
A weighted sum of errors and warnings of all tests preformed
## Not run: metric_score(assess_r_cmd_check(pkg_ref("riskmetric")))
## Not run: metric_score(assess_r_cmd_check(pkg_ref("riskmetric")))
The scoring function is the number of OS flavors that passed with OK or NOTES + 0.5*the number of OS's that produced WARNINGS divided by the number of OS's checked
## S3 method for class 'pkg_metric_remote_checks' metric_score(x, ...)
## S3 method for class 'pkg_metric_remote_checks' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
a fractional value indicating percentage OS flavors that did not produce an error or warning from R CMD check
## Not run: metric_score(assess_remote_checks(pkg_ref("riskmetric")))
## Not run: metric_score(assess_remote_checks(pkg_ref("riskmetric")))
Score a package for the number of reverse dependencies it has; regularized
Convert the number of reverse dependencies length(x)
into a validation
score [0,1]
## S3 method for class 'pkg_metric_reverse_dependencies' metric_score(x, ...)
## S3 method for class 'pkg_metric_reverse_dependencies' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
The scoring function is the classic logistic curve
with a square root scale for the number of reverse dependencies
, sigmoid midpoint is 5 reverse dependencies, ie.
, and logistic growth rate of
.
numeric value between 1
(high number of reverse dependencies) and
0
(low number of reverse dependencies)
## Not run: metric_score(assess_reverse_dependencies(pkg_ref("riskmetric")))
## Not run: metric_score(assess_reverse_dependencies(pkg_ref("riskmetric")))
Scores packages based on its codebase size, as determined by number of lines of code.
## S3 method for class 'pkg_metric_size_codebase' metric_score(x, ...)
## S3 method for class 'pkg_metric_size_codebase' metric_score(x, ...)
x |
a |
... |
additional arguments unused |
numeric value between 0
(for large codebase) and 1
(for small codebase)
## Not run: metric_score(assess_size_codebase(pkg_ref("riskmetric")))
## Not run: metric_score(assess_size_codebase(pkg_ref("riskmetric")))
By default, use all assess_*
funtions in the riskmetric
namespace and produce a tibble
with one column per
assessment applied.
pkg_assess( x, assessments = all_assessments(), ..., error_handler = assessment_error_empty )
pkg_assess( x, assessments = all_assessments(), ..., error_handler = assessment_error_empty )
x |
A single |
assessments |
A list of assessment functions to apply to each package reference. By default, a list of all exported assess_* functions from the riskmetric package. |
... |
additional arguments unused |
error_handler |
A function, which accepts a single parameter expecting the raised error, which will be called if any errors occur when attempting to apply an assessment function. |
Either a list_of_pkg_metric
object when a single
pkg_ref
object is passed as x
, or a
tibble
of metrics when a list_of_pkg_ref
or
tibble
is passed as x
. When a tibble
is returned, it has one row per package reference and a new column per
assessment function, with cells of that column as package metric objects
returned when the assessment was called with the associated pacakge
reference.
assess_last_30_bugs_status
vector indicating whether BugReports status is closed
assess_covr_coverage
Package unit test coverage
assess_size_codebase
number of lines of code base
assess_export_help
exported objects have documentation
assess_r_cmd_check
Package check results
assess_dependencies
Package dependency footprint
assess_reverse_dependencies
List of reverse dependencies a package has
assess_license
software is released with an acceptable license
assess_has_maintainer
a vector of associated maintainers
assess_remote_checks
Number of OS flavors that passed/warned/errored on R CMD check
assess_exported_namespace
Objects exported by package
assess_has_website
a vector of associated website urls
assess_downloads_1yr
number of downloads in the past year
assess_has_news
number of discovered NEWS files
assess_has_vignettes
number of discovered vignettes files
assess_has_examples
proportion of discovered function files with examples
assess_has_source_control
a vector of associated source control urls
assess_has_bug_reports_url
presence of a bug reports url in repository
assess_news_current
NEWS file contains entry for current version number
A helper for structuring assessment return objects for dispatch with the score function
pkg_metric(x = NA, ..., class = c())
pkg_metric(x = NA, ..., class = c())
x |
data to store as a |
... |
additional attributes to bind to the |
class |
a subclass to differentiate the |
a pkg_metric
object
Create a package reference from package name or filepath, producing an object in which package metadata will be collected as risk assessments are performed. Depending on where the package was found - whether it is found as source code, in a local library or from a remote host - an S3 subclass is given to allow for source-specific collection of metadata. See 'Details' for a breakdown of subclasses. Different sources can be specified by passing a subclass as an arguemnt named 'source', see details.
pkg_ref(x, ...) pkg_install(x, lib.loc = NULL) pkg_source(x) pkg_cran(x, repos = getOption("repos", "https://cran.rstudio.com")) pkg_bioc(x) pkg_missing(x) pkg_library(lib.loc) as_pkg_ref(x, ...)
pkg_ref(x, ...) pkg_install(x, lib.loc = NULL) pkg_source(x) pkg_cran(x, repos = getOption("repos", "https://cran.rstudio.com")) pkg_bioc(x) pkg_missing(x) pkg_library(lib.loc) as_pkg_ref(x, ...)
x |
A singular |
... |
Additional arguments passed to methods. |
lib.loc |
The path to the R library directory of the installed package. |
repos |
URL of CRAN repository to pull package metadata. |
Package reference objects are used to collect metadata pertaining to a given package. As data is needed for assessing a package's risk, this metadata populates fields within the package reference object.
The pkg_ref
S3 subclasses are used extensively for divergent metadata
collection behaviors dependent on where the package was discovered. Because
of this, there is a rich hierarchy of subclasses to articulate the different
ways package information can be found.
A source argument can be passed using the 'source' argument. This will override the logic that riskmetric does when determining a package source. This can be useful when you are scoring the most recent version present on a repository, or testing a specific library.
pkg_ref
A default class for general metadata
collection.
pkg_source
A reference to a source code directory.
pkg_install
A reference to a package installation
location in a package library. A specific library can be passed by passing
the path to the library as the parameter 'lib.loc'
pkg_remote
A reference to package metadata on a
remote server.
pkg_cran_remote
A reference to package
information pulled from the CRAN repository.
pkg_bioc_remote
A reference to package
information pulled from the Bioconductor repository.
pkg_git_remote
A reference to a package source
code git repository. (not yet implemented)
When a single value is provided, a single pkg_ref
object is
returned, possibly with a subclass based on where the package was found. If
a vector
or list
is provided, a list_of_pkg_ref
object
constructed with list_of
is returned, which can be
considered analogous to a list
. See 'Details' for further
information about pkg_ref
subclasses.
*Experimental!* Package cohorts are structures to determine the risk of a set of packages. 'pkg_library()' can be called to create a object containing the pkg_ref objects of all packages in a system library.
## Not run: # riskmetric will check for installed packages by default ref_1 <- pkg_ref("utils") ref_1$source # returns 'pkg_install' # lib.loc can be used to specify a library for pkg_install ref_3 <- pkg_ref("utils", source = "pkg_install", lib.loc = .libPaths()[1]) # You can also override this behavior with a source argument ref_2 <- pkg_ref("utils", source = "pkg_cran_remote") ref_2$source # returns 'pkg_cran_remote' ## End(Not run)
## Not run: # riskmetric will check for installed packages by default ref_1 <- pkg_ref("utils") ref_1$source # returns 'pkg_install' # lib.loc can be used to specify a library for pkg_install ref_3 <- pkg_ref("utils", source = "pkg_install", lib.loc = .libPaths()[1]) # You can also override this behavior with a source argument ref_2 <- pkg_ref("utils", source = "pkg_cran_remote") ref_2$source # returns 'pkg_cran_remote' ## End(Not run)
Reactively retrieve and cache 'pkg_ref' metadata
a pkg_ref
field
pkg_ref
class fieldsThe pkg_ref
class structures an environment with special handling
for indexing into the pkg_ref
class using the $
or [[
operators. For all intents and purposes, the pkg_ref
class is works
conceptually similar to a lazy, immutable list
, and uses the
pkg_ref_cache
function internally to lazily retrieve package
reference fields.
Laziness in a pkg_ref
object refers to the delayed evaluation of the
contents of its fields. Since some metadata is time or computationally
intensive to retrieve, and unnessary for some assessments, we want to avoid
that retrieval until it is needed.
The first time that a field is accessed within a pkg_ref
object
x
, a corresponding pkg_ref_cache
S3 generic is called. For
example, when x$description
is first accessed, the pkg_ref
object uses the function pkg_ref_cache.description
to attempt to
retrieve the contents of the corresponding DESCRIPTION
file.
Often, the way that this data is collected might be different depending on
the subclass of the pkg_ref
. In the case of the description
metadata, a reference to a local install might be able to read in a local
file directly, whereas a reference to a remote source of metadata might
require first downloading the file. For this reason, many
pkg_ref_cache.*
functions are themselves S3 generics that dispatch
on the class of the pkg_ref
object, allowing for divergent behaviors
for different source of package metadata.
pkg_ref
field immutabilityOnce a field has been calculated, its value is immutable. This behavior was chosen because of the long time frame over which package metadata changes, rendering it unnecessary to continually reevaluate fields each time they are accesssed.
This means that within an assessment, a given field for a package will only ever be calculated once and preserved for downstream use.
## Not run: # implementing a new field called "first_letter" that is consistently derived # across all pkg_ref objects: pkg_ref_cache.first_letter <- function(x, name, ...) { substring(x$name, 1, 1) } x <- pkg_ref("riskmetric") x$first_letter # implementing a new field called "subclass_enum" that dispatches on # the subclass of the pkg_ref object: pkg_ref_cache.subclass_enum <- function(x, name, ...) { UseMethod("pkg_ref_cache.subclass_enum") } pkg_ref_cache.subclass_enum.pkg_ref <- function(x, name, ...) { 0 } pkg_ref_cache.subclass_enum.pkg_install <- function(x, name, ...) { 1 } x$subclass_enum ## End(Not run)
## Not run: # implementing a new field called "first_letter" that is consistently derived # across all pkg_ref objects: pkg_ref_cache.first_letter <- function(x, name, ...) { substring(x$name, 1, 1) } x <- pkg_ref("riskmetric") x$first_letter # implementing a new field called "subclass_enum" that dispatches on # the subclass of the pkg_ref object: pkg_ref_cache.subclass_enum <- function(x, name, ...) { UseMethod("pkg_ref_cache.subclass_enum") } pkg_ref_cache.subclass_enum.pkg_ref <- function(x, name, ...) { 0 } pkg_ref_cache.subclass_enum.pkg_install <- function(x, name, ...) { 1 } x$subclass_enum ## End(Not run)
The 'pkg_ref' subclass hierarchy, used for pkg_ref object creation with a specified subclass
pkg_ref_class_hierarchy
pkg_ref_class_hierarchy
An object of class list
of length 1.
pkg_score() calculates the risk involved with using a package. Risk ranges from 0 (low-risk) to 1 (high-risk).
pkg_score(x, ..., error_handler = score_error_default)
pkg_score(x, ..., error_handler = score_error_default)
x |
A |
... |
Additional arguments passed to |
error_handler |
Specify a function to be called if the class can't be
identified. Most commonly this occurs for |
A numeric value if a single pkg_metric
is provided, or a
tibble
with pkg_metric
objects scored and
returned as numeric values when a tibble
is provided.
score_error_default score_error_zero score_error_NA
## Not run: # scoring a single assessment metric_score(assess_has_news(pkg_ref("riskmetric"))) # scoring many assessments as a tibble library(dplyr) pkg_score(pkg_assess(as_tibble(pkg_ref(c("riskmetric", "riskmetric"))))) ## End(Not run)
## Not run: # scoring a single assessment metric_score(assess_has_news(pkg_ref("riskmetric"))) # scoring many assessments as a tibble library(dplyr) pkg_score(pkg_assess(as_tibble(pkg_ref(c("riskmetric", "riskmetric"))))) ## End(Not run)
Default score error handling, emitting a warning and returning 0
score_error_default(x, ...)
score_error_default(x, ...)
x |
A |
... |
Additional arguments unused |
a value of package score
Score error handler to silently return NA
score_error_NA(...)
score_error_NA(...)
... |
Additional arguments unused |
a value of package score
Score error handler to silently return 0
score_error_zero(...)
score_error_zero(...)
... |
Additional arguments unused |
a value of package score
This function serves as an example for how a risk score might be derived.
Assuming all assessments provided by riskmetric
are available in a
dataset, this function can be used to calculate a vector of risks.
summarize_scores(data, weights = NULL)
summarize_scores(data, weights = NULL)
data |
a |
weights |
an optional vector of non-negative weights to be assigned to each assessment. |
a numeric vector of risk scores
## Not run: library(dplyr) summarize_scores(pkg_score(pkg_assess(as_tibble(pkg_ref("riskmetric"))))) library(dplyr) pkg_ref("riskmetric") %>% pkg_assess() %>% pkg_score() %>% summarize_scores() ## End(Not run)
## Not run: library(dplyr) summarize_scores(pkg_score(pkg_assess(as_tibble(pkg_ref("riskmetric"))))) library(dplyr) pkg_ref("riskmetric") %>% pkg_assess() %>% pkg_score() %>% summarize_scores() ## End(Not run)