srr

Software Review Roclets

https://github.com/ropensci-review-tools/srr

Keywords

Repository

Software Review Roclets

README.Rmd

---
title: "srr"
output:
  md_document:
    variant: gfm

  rmarkdown::html_vignette:
    self_contained: no
---


[![R build status](https://github.com/ropensci-review-tools/srr/workflows/R-CMD-check/badge.svg)](https://github.com/ropensci-review-tools/srr/actions)
[![codecov](https://codecov.io/gh/ropensci-review-tools/srr/branch/main/graph/badge.svg)](https://codecov.io/gh/ropensci-review-tools/srr)
[![Project Status:
Concept](https://www.repostatus.org/badges/latest/concept.svg)](https://www.repostatus.org/#concept)





# srr

"srr" stands for **S**oftware **R**eview **R**oclets, and is
[rOpenSci](https://ropensci.org)'s package for extending documentation to
include additional components specific to the software review process. The
package currently facilitates documenting how statistical software complies
with our collections of [Statistical Software
Standards](https://stats-devguide.ropensci.org/standards.html). Before
proceeding, the answer to an important question: **[What is
a "roclet"](https://github.com/r-lib/roxygen2/issues/1086)?**

- A roclet is an object used by the [`roxygen2`](https://roxygen2.r-lib.org)
  package to convert [`roxygen2`](https://roxygen2.r-lib.org)-style
  documentation lines into some desired form of output.

## Why then?

This package currently serves to aid developers and reviewers of statistical
software in aligning their software against our extensive [lists of
standards](https://stats-devguide.ropensci.org/standards.html).
In acknowledgement of [Colin Gillespie](https://github.com/csgillespie)'s
sentiments expressed in his keynote speech at the [European R Users Meeting
2020](https://2020.erum.io/program/keynotes-invited-speakers/):

> Standards are good

> Standards should be strict

> No-one reads standards

the `srr` package aims to integrate the task of aligning software with
standards within the practice of coding itself, and to make standards adherence
as painless as possible. 

## How?

The [`roxygen2`](https://roxygen2.r-lib.org) package parses all documentation
lines from all files in the `R/` directory of a package which begin with `#'`.
Special tags beginning with `@`, such as `@param` or `@export`, may follow
these symbols, and roclets define what is done with different kinds of tags.
The [`roxygen2`](https://roxygen2.r-lib.org) package includes roclets to
process a number of tags; the `srr` package implements custom roclets to
process several additional tags for use with [rOpenSci](https://ropensci.org)'s
software review systems, and to process tags in locations other than just the
`R/` directory.

At present, the package only contains roclets and associated functions to help
those developing and reviewing packages submitted to rOpenSci's system for
[Statistical Software
Review](https://stats-devguide.ropensci.org/).
The functions are mostly intended to ease alignment and assessment of software
against the standards detailed in the [main project
book](https://stats-devguide.ropensci.org/standards.html)
(from here on referred to as the "SSR Book").

## Installation

The easiest way to install this package is via the associated
[`r-universe`](https://ropensci-review-tools.r-universe.dev/ui#builds). As
shown there, simply enable the universe with

```{r options, eval = FALSE}
options (repos = c (
    ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev",
    CRAN = "https://cloud.r-project.org"
))
```

And then install the usual way with,

```{r install, eval = FALSE}
install.packages ("srr")
```

Alternatively, the package can be installed by running one of the following
lines:


```{r remotes, eval = FALSE}
remotes::install_github ("ropensci-review-tools/srr")
pak::pkg_install ("ropensci-review-tools/srr")
```

and loaded for use with,
```{r lib-fakey, eval = FALSE}
library (srr)
```
```{r lib, echo = FALSE, message = FALSE}
devtools::load_all (".", export_all = FALSE)
```

## Overview

Both this `README`, and the main package vignette, describe the functionality
of the package in the specific context of the statistical software review
project. Both the roclet and all functions intended for use in this context are
prefixed with `srr_stats_`. The remainder of this document is in two main
sections. If you're developing a statistics package for submission to our peer
review system, keep straight on reading. If you've been invited to review a
package, you may skip the following section and just read the subsequent
section. The general procedures for both developers and reviewers are described
at length in the [SSR
book](https://stats-devguide.ropensci.org/standards.html),
with this `README` intended to provide supporting technical details.

Note that the `srr` package can be applied only within the working directory of
a package. There are no `package` or `path` arguments to allow functions to be
applied to packages anywhere other than in the current working directory.

## For Package Developers

People intending to develop packages for submission to our system for peer
reviewing statistical software will need to follow the following general steps.
Note that, while the `srr` package has a few functions which developers may
call directly to aid their submission process, most functionality of this
package is implemented via custom [`roxygen2`
"roclets"](https://roxygen2.r-lib.org). The third of the following steps
describes how to link your package with `srr` in order to use these roclets.

1. Ensure that your package successfully passes all
   [`autotest`](https://github.com/ropensci-review-tools/autotest) tests, potentially
   including setting `test = FALSE` flags to switch off any tests you consider
   not to be applicable to your package. For details, please see the [package
   documentation for `autotest`](https://docs.ropensci.org/autotest/).
2. Decide which of our in-scope categories of statistical software best
   describe your package. The function
   [`srr_stats_categories()`](https://docs.ropensci.org/srr/reference/srr_stats_categories.html)
   provides a list of currently developed categories for which standards
   have been developed, along with links to the online standards for each
   category:

    ```{r available}
    srr_stats_categories ()$title
    ```
    That function also returns links to the full descriptions of each category
    in the [main project
    book](https://stats-devguide.ropensci.org/standards.html).
    Any software within one or more of these categories may be considered for
    review. 
3. Enable your package to use the `srr_stats` roclets by modifying the
   package's `DESCRIPTION` file so that the `Roxygen` line looks like this:
    ```{r roxygen, eval = FALSE}
    Roxygen:list (markdown = TRUE, roclets = c ("namespace", "rd", "srr::srr_stats_roclet"))
    ```
    That will load the ["roclet"](https://roxygen2.r-lib.org) used by this
    package to process the documentation of statistical standards within your
    actual code. Note that you do not need to add, import, or depend upon the
    `srr` package anywhere else within the `DESCRIPTION` file or your actual
    package.
4. Load the `srr` package and generate lists of standards within your
   package's `/R` folder by running,
   [`srr_stats_roxygen(category = c("", ""))`](https://docs.ropensci.org/srr/reference/srr_stats_roxygen.html).
   This will by default create a new file called by default
   `R/srr_stats_standards.R`, the first few lines of which will look like this:
    ```{r srr_stats_roxygen, echo = FALSE, message = FALSE}
    f <- "./R/srr-stats-standards.R"
    if (!file.exists (f)) {
        srr_stats_roxygen ()
    }
    rso <- readLines (f)
    head (rso)
    ```
    The file will contain a list of all standards from your nominated
    categories. This file may be renamed, and the individual items moved to
    other locations in other files, but all nominated standards should remain
    in [`roxygen2`](https://roxygen2.r-lib.org) blocks somewhere in your source
    code.

    The `@srrstatsVerbose` line defines a variable which may be used to
    suppress output from the `srrstats` roclet when updating package
    documentation (by setting to `FALSE`). After that comes the list of
    standards, each of which is prefixed by
    a [`roxygen2`](https://roxygen2.r-lib.org) tag, `@srrstatsTODO`. A package
    can only be submitted once all of these `TODO` items have been addressed
    via one of the options described in the following two items.
5. A standard may be addressed by moving the item in the
   `srr-stats-standards.R` file (or wherever you've chosen to list these within
   your own package) to one or more places in your code where these standards
   have been addressed. In doing so, the
   [`roxygen2`](https://roxygen2.r-lib.org) tag should be changed from
   `@srrstatsTODO` to `@srrstats`, and the text which initially lists the
   actual standard should be changed to provide a brief description of how that
   standard has been met. Tags for one particular standard may be repeated in
   multiple places within your code, and we encourage locating multiple
   `@srrstats` tags which refer to a particular standard at all locations which
   directly address that standard.
6. Alternatively, any standards which you consider not applicable to your
   software may remain listed in the templated section of the main
   `srr-stats-standards.R` document (or any alternative location), with their
   tag changed from `@srrstatsTODO` to `@srrstatsNA`, and the description of
   the standard removed and replaced by an explanation of why you consider that
   standard not to be applicable to your software. These `@srrstatsNA` tags
   should be collected together within a single `roxygen2` block with a title
   of `NA_standards`, as provided in the initial template generated by the
   [`srr_stats_roxygen()`](https://docs.ropensci.org/srr/reference/srr_stats_roxygen.html)
   function. Any non-applicable standards can then just be moved into this
   block, with their `@srrstatsTODO` tags changed to `@srrstatsNA` 
7. Each time you run 
    [`devtools::document()`](https://devtools.r-lib.org/reference/document.html)
    or the equivalent
    [`roxygen2::roxygenise()`](https://roxygen2.r-lib.org/reference/roxygenize.html),
    the roclet will scan your package's documentation for the state of
    standards, and will generate a summary of the result on your screen. Note,
    however, that the `roxygen2` package [only scans files in the R
    directory](https://github.com/r-lib/roxygen2/blob/9652d15221109917d46768e836eaf55e33c21633/R/package_files.R#L1-L10),
    and so this screen output will only summarise standards documented there.
    Standards documented in other locations such as test files or vignettes
    will be recognised and processed by the `srr` package, even through they
    will not be recognised by the `document()/roxygenise()` functions, and so
    will not appear in their output.

To help developers understand how to use these roclets, this package includes a
function,
[`srr_stats_pkg_skeleton()`](https://docs.ropensci.org/srr/reference/srr_stats_pkg_skeleton.html),
which will generate a skeleton of a package with several
[`roxygen2`](https://roxygen2.r-lib.org) tags inserted throughout the code.
This function returns the directory where the skeleton package has been
created, so running the following two lines will illustrate the roclets in
action:

```{r demo, eval = FALSE}
d <- srr_stats_pkg_skeleton ()
roxygen2::roxygenise (d)
```

Note that the skeleton package also includes C++ code in a `src/` directory, so
will be compiled the first time your run
[`roxygensise()`](https://roxygen2.r-lib.org/reference/roxygenize.html).
Running a second time will generate cleaner output from the `srr_stats` roclets
only. The tags included in 
[`roxygen2`](https://roxygen2.r-lib.org/) blocks in this skeleton package may
be modified, moved, copied, and changed in any way you like to help you
understand how the roclets work. Simply play around with the 
[`roxygen2`](https://roxygen2.r-lib.org/) lines and run 
[`roxygensise()`](https://roxygen2.r-lib.org/reference/roxygenize.html) each
time to see the effect. Individual standards may be moved to, and addressed in,
any location including the directories `R/`, `src/`, or `tests/`, and well as
in `.Rmd` documentation files such as `README.Rmd` or package vignettes. The
`srr_stats` roclet associated with this package is able to parse the various
`@srrstats` tags in all of these locations.

### Places where standards can NOT be inserted

While the `srr` package enables standards compliance to be documented through
inserting `@srrstats` tags in as many locations as possible, in order to ensure
compliance is documented as close as possible to the point within the code
where each standard is addressed, it is not possible to insert `roxygen2` tags
in every type of file. In general, standards may be inserted in any `.R` or
`.Rmd` file, and most types of files in `src` or `inst/include` directories, as
long as they are used with a package able to convert documentation to
a corresponding R file (such as [`Rcpp`](http://www.rcpp.org/)'s generation of
`RcppExports.R` files which include the C++ documentation).

Tags may generally not be placed in any other kinds of files, including `.md`
files such as `CONTRIBUTING.md`, or other files without extensions such as
`DESCRIPTION`, `NAMESPACE`, or `NEWS`. Standards which are best addressed in
such files must be placed in some other generic location (such as
`R/srr-standards.R`), with a cross-reference to the file in which they are
actually addressed.

## Code of Conduct

Please note that this package is released with a [Contributor Code of
Conduct](https://ropensci.org/code-of-conduct/). By contributing to this
project, you agree to abide by its terms.

## Contributors






All contributions to this project are gratefully acknowledged using the [`allcontributors` package](https://github.com/ropenscilabs/allcontributors) following the [all-contributors](https://allcontributors.org) specification. Contributions of any kind are welcome!

### Code









mpadge






christophsax






maelle






### Issue Authors









santikka






schneiderpy






### Issue Contributors









jeroen

Owner

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "srr",
  "description": "Companion package to 'rOpenSci' statistical software review project.",
  "name": "srr: 'rOpenSci' Review Roclets",
  "relatedLink": "https://docs.ropensci.org/srr/",
  "codeRepository": "https://github.com/ropensci-review-tools/srr",
  "issueTracker": "https://github.com/ropensci-review-tools/srr/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "0.1.4.009",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.4.3 (2025-02-28)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Mark",
      "familyName": "Padgham",
      "email": "mark@ropensci.org",
      "@id": "https://orcid.org/0000-0003-2172-5265"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Mark",
      "familyName": "Padgham",
      "email": "mark@ropensci.org",
      "@id": "https://orcid.org/0000-0003-2172-5265"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "pkgbuild",
      "name": "pkgbuild",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=pkgbuild"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 3.0.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "cli",
      "name": "cli",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=cli"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "clipr",
      "name": "clipr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=clipr"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "fs",
      "name": "fs",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=fs"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "gert",
      "name": "gert",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=gert"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "here",
      "name": "here",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=here"
    },
    "6": {
      "@type": "SoftwareApplication",
      "identifier": "methods",
      "name": "methods"
    },
    "7": {
      "@type": "SoftwareApplication",
      "identifier": "Rcpp",
      "name": "Rcpp",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=Rcpp"
    },
    "8": {
      "@type": "SoftwareApplication",
      "identifier": "roxygen2",
      "name": "roxygen2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=roxygen2"
    },
    "SystemRequirements": {}
  },
  "fileSize": "1375.502KB",
  "citation": [
    {
      "@type": "SoftwareSourceCode",
      "datePublished": "2021",
      "author": [
        {
          "@type": "Person",
          "givenName": "Mark",
          "familyName": "Padgham"
        }
      ],
      "name": "srr",
      "url": "https://github.com/ropensci-review-tools/srr",
      "description": "R package version 0.0.1"
    }
  ],
  "readme": "https://github.com/ropensci-review-tools/srr/blob/main/README.md",
  "contIntegration": [
    "https://github.com/ropensci-review-tools/srr/actions",
    "https://codecov.io/gh/ropensci-review-tools/srr"
  ],
  "developmentStatus": "https://www.repostatus.org/#concept",
  "keywords": [
    "compliance-automation",
    "r",
    "statistical-software"
  ]
}

GitHub Events