Papers about R packages – The R Journal

Most papers in the R Journal describe an R package. Here are some suggestions (and some requirements) to help you get your paper accepted for publication.

Write for a wide audience

The R community intersects with many scientific and professional communities. This means that you can not expect all readers to be familiar with the jargon in your field.

Focus on the software, not on the method

The R Journal is primarily a software journal. This means that methodology behind a package needs only to be described to the point necessary to understand what the package does. In almost all cases, the underlying methods will be discussed in detail in other papers, which you should cite. We strongly encourage authors to focus on software-related issues such as:

Design considerations
- Why does the package have this particular interface?
- Which user did you have in mind for the package as it was developed? An expert R programmer? A novice? A data analyst with a background in a certain field?
- Did you adhere to a certain design standard? Why?
Performance and limitations
- Is the package parallelized?
- Can you say something about how use of resources (time, memory) scales with input?
- Are there any limits to its use? What is the typical use case?
Important implementation details
- Have you chose a certain object model, such as S4/S3/R6/S7? Why?
- Any considerations regarding dependencies?

Structure of a typical paper describing a package

A typical paper would contain the following elements.

An introduction for a wide audience, describing the context of the problem addressed by the package, any existing solutions or competitor packages, and the gap filled by the package.
If needed, a conceptual description of the methodology, followed by (more important) the main drivers behind the design of the package.
A description of the typical workflow of the package.
Possibly, a detailed use case, demonstrating more options.
A section with technical details regarding implementation or theory.
Discussion and conclusion.

Requirements for consideration

The package must be available on CRAN or Bioconductor.
The content of the package should be substantial and would likely be of significant interest and use within the R community.
The accompanying paper should clearly demonstrate the use of the package and its advantages over any competing packages or existing approaches.
The package must include unit tests to verify functionality.
Each user-facing function must be fully documented with all terms and arguments explained, and examples provided.
Include a vignette describing a full workflow or example analysis.
Use a version control system (e.g., GitHub, GitLab, BitBucket, R-Forge).
Avoid unnecessary dependencies.

Recommended best practices

In addition, we strongly recommend that package authors follow common R package conventions, including but not limited to:

Offer a bug reporting mechanism, such as GitHub issues.
The package interface and functions are designed with the user, and a typical user workflow in mind.
Use a consistent naming scheme for functions (e.g., snake_case or camelCase), with meaningful and descriptive function names.
Follow a consistent code style, such as the tidyverse or Google style guides. A code formatter such as Air or styler can help enforce consistent style.
Use object-oriented programming where appropriate (e.g., define plot() or print() S3 methods for custom classes).
Use message() or warning() instead of cat() or print() within functions (except in print methods).
Avoid reading or writing files unless essential to the package’s purpose.
Use TRUE and FALSE explicitly; avoid T and F as values or variable names.
If the package contains data, include a data-raw directory with code for data generation or cleaning.
Make documentation available on a standalone website online (e.g., via pkgdown).

Additional resources

To learn about best practices in R package development, authors are encouraged to consult these resources: