Assessment Example

As an example, take a look at how assess_has_news has been implemented. We’ll focus on just the generic and the pkg_install functions:

#> assess_has_news <- function (x, ...) 
#> {
#>     UseMethod("assess_has_news")
#> }
#> attr(,"column_name")
#> [1] "has_news"
#> attr(,"label")
#> [1] "number of discovered NEWS files" 
#> 
#> assess_has_news.pkg_install <- NULL

There are a couple things to note. First, the S3 system is used to dispatch functionality for the appropriate package reference class. Since the way we’d assess the inclusion of a NEWS file might be different for an installed package or remotely sourced metadata, we may have separate functions to process these datatypes in distinct ways.

Second, for each assessment, a pkg_metric object is returned. This stores the atomic data pertaining to the metric and importantly adopts a unique subclass for the assessment function.

Finally, a cosmetic "column_name" attribute is tagged to the function. This is used when calling the assess function. The assess verb is a convenience function which steps through all available assessments returning a tibble of assessment outputs. The "column_name" provides a more user-friendly label for the assessment in this tibble.

Writing a New Assessment

Now we’ll write our assessment. Eventually we want to consider a package high risk if the name does not start with “r”. We’ll need to make a pkg_metric object containing the first letter of the name.

assess_name_first_letter <- function(x, ...) {
  UseMethod("assess_name_first_letter")
}
attr(assess_name_first_letter, "column_name") <- "name_first_letter"

assess_name_first_letter.pkg_ref <- function(x, ...) {
  pkg_metric(substr(x$name, 0, 1), class = "pkg_metric_name_first_letter")
} 

Example Metadata Caching

This is how the riskmetric package handles parsing the DESCRIPTION file so that it can feed into all downstream assessments without having to re-parse the file each time or copy the code to do so.

#> pkg_ref_cache.description <- function (x, name, ...) 
#> {
#>     UseMethod("pkg_ref_cache.description")
#> } 
#> 
#> pkg_ref_cache.description.pkg_install <- function (x, name, ...) 
#> {
#>     read.dcf(file.path(x$path, "DESCRIPTION"))
#> }

Once these are defined, they’ll be automatically called when the field is first accessed by the pkg_ref object, and then stored for any downstream uses.

library(riskmetric)
package <- pkg_ref("riskmetric")

#> <pkg_install, pkg_ref> riskmetric v0.2.4
#> $path
#>   [1] "/home/user/username/R/4.3/Resources/library/riskmetric"
#> $source
#>   [1] "pkg_install"
#> $version
#>   [1] '0.2.4'
#> $name
#>   [1] "riskmetric"
#> $bug_reports...
#> $bug_reports_host...
#> $bug_reports_url...
#> $description...
#> $downloads...
#> $examples...
#> $help...
#> $help_aliases...
#> $license...
#> $maintainer...
#> $news...
#> $r_cmd_check...
#> $release_date...
#> $remote_checks...
#> $source_control_url...
#> $vignettes...
#> $website_urls...

Notice that upon initialization, the description field indicates that it hasn’t yet been evaluated with a trailing ... in the name. When accessed, the object will call a caching function to go out and grab the package metadata and return the newly derived value.

package$description

Because the pkg_ref object stores an environment, caching this value once makes them available for any future attempts to access the field. This is helpful because we, as developers of the package, don’t need to think critically about the order that assessments are performed, and allows users to redefine the order of assessments without worry about how metadata is acquired.

Writing a Metadata Cache

Now, for our new metric, we want to cache the package name’s first letter. We need to add a new pkg_ref_cache function for our field. Thankfully, any subclass of pkg_ref can access the first letter the same way, so we just need the one function.

pkg_ref_cache.name_first_letter <- function(x, name, ...) {
  substr(x$name, 0, 1)
}

After adding this caching function, we need to make a small modification to assess_name_first_letter.pkg_ref in order use our newly cached value.

assess_name_first_letter.pkg_ref <- function(x, ...) {
  pkg_metric(x$name_first_letter, class = "pkg_metric_name_first_letter")
} 

Let’s try it out!

package$name
#> [1] "riskmetric"
package$name_first_letter
#> [1] "r"