How to Make a Contribution to Base R

Heather Turner and Ella Kaye

April 14, 2022

Contributing to R

R is maintained by the R Core Team

Members of the R Community can contribute in various ways:

• Analysing and fixing bugs
• Translating R’s messages, warnings and errors
• Testing pre-release versions of R
• Developing new features

In this demo we’ll focus on bug fixing!

R is maintained by the R Core Team

Members of the R Community can contribute in various ways, for example * Analysing and fixing bugs * Translating R’s messages, warnings and errors * Testing pre-release versions of R, or * Developing new features

->

In this demo we’ll focus on bug fixing!

How to find a good bug to work on

First, we need to find a good bug to work on.

Bugzilla, https://bugs.r-project.org

Bugs in R are tracked in R’s Bugzilla, which can be found at bugs.r-project.org. We can browse the bugs by clicking on the browse button in the top menu.

There are two categories to browse, we’ll focus on R, which are the bugs in R itself.

This takes you to a list of components, which are categories of bugs that you can look at. Let’s take a look at Documentation.

This returns a list of bugs that have been categorised as documentation bugs by the bug reporter.

We can browse the summaries to look for bugs that we think we might be able to help with.

Let’s take a look at the last one here: “Clarification needed in ?c”, which refers to the help file for the c() function.

The top of the bug report shows some basic metadata.

If we scroll down, we’ll see a description of the bug by the reporter, in this case Michael Chirico.

Below that, there may be one or more comments from R core developers or other contributors.

What to look for

Good: a bug report where the next step is clear.

• A minimimal reproducible example
• Checking in R-devel
• A diagnosis
• A fix

Even better: an R Core member supports the next step in a comment.

A good first issue is one where the next step is clear.

The bug report might need a minimal reproducible example to use as a test case.

Or the bug might need checking in the development version of R, to see if it is still a bug or has already been fixed.

Alternatively, the bug might need debugging to diagnose the root cause.

Finally, you might contribute to the discussion of how to fix the bug, or even propose a patch.

It is even better if an R Core member has shown support for one of these things in a comment, so you know the next step for sure.

What to avoid

• Too new
• Too old
• Commenters disagree on how to fix
• Someone else is clearly working on it
• Clearly requires specific expertise you lack

Bug reports that are too new are best avoided, as they are often taken up quickly by experienced contributors.

On the other hand, bug reports that are very old often lack consensus on the next step or require a decision to be made by R Core.

You should avoid bugs where there is disagreement on the next step or someone else is clearly working on it.

Finally avoid bugs that are clearly outside your areas of expertise.

Shortcuts

Get help finding a good first issue:

• R Contributor Office Hours
• R Contributor Slack #work-out-loud channel
• Bug BBQ

It can take a while to find an issue to work on, but there are some shortcuts available.

You can attend an R Contributor Office Hour or look on the #work-out-loud channel of the R Contributor Slack where good first issues are sometimes shared.

Or you can attend special events like the Bug BBQ, where good first issues are prepared in advance.

Getting to the root of the issue

One of the hardest tasks is analysing bugs to get to the root of the issue.

Bug 17863

See report on Bugzilla:
https://bugs.r-project.org/show_bug.cgi?id=17863

A 1-factor factor analysis:

test <- factanal(mtcars[, 1:4], factors = 1)

Let’s look at an example: Bug 17863.

The bug reporter provided some test code for a 1-factor factor analysis.

Printing the result

Good

print(test)

Call:
factanal(x = mtcars[, 1:4], factors = 1)

Uniquenesses:
  mpg   cyl  disp    hp 
0.199 0.078 0.120 0.261 

Loadings:
     Factor1
mpg  -0.895 
cyl   0.960 
disp  0.938 
hp    0.859 

               Factor1
SS loadings      3.342
Proportion Var   0.835

Test of the hypothesis that 1 factor is sufficient.
The chi square statistic is 0.5 on 2 degrees of freedom.
The p-value is 0.777 

Bad

print(test, sort = TRUE)

Call:
factanal(x = mtcars[, 1:4], factors = 1)

Uniquenesses:
  mpg   cyl  disp    hp 
0.199 0.078 0.120 0.261 

Loadings:
[1] -0.895  0.960  0.938  0.859

               Factor1
SS loadings      3.342
Proportion Var   0.835

Test of the hypothesis that 1 factor is sufficient.
The chi square statistic is 0.5 on 2 degrees of freedom.
The p-value is 0.777 

When the print function is called on the resulting test object, various elements of the result are printed as expected, including the call, the uniquenesses and the loadings.

Before R 4.3.0, when the print function was called with the argument sort = TRUE, we get an unexpected result. The loadings are printed as a vector rather than a matrix, so we lose the row and column labels.

Finding the print method (1)

class(test)

[1] "factanal"

getAnywhere(print.factanal)

A single object matching 'print.factanal' was found
It was found in the following places
  registered S3 method for print from namespace stats
  namespace:stats
with value

function (x, digits = 3, ...) 
{
    cat("\nCall:\n", deparse(x$call), "\n\n", sep = "")
    cat("Uniquenesses:\n")
    print(round(x$uniquenesses, digits), ...)
    print(x$loadings, digits = digits, ...)
    if (!is.null(x$rotmat)) {
        tmat <- solve(x$rotmat)
        R <- tmat %*% t(tmat)
        factors <- x$factors
        rownames(R) <- colnames(R) <- paste0("Factor", 1:factors)
        if (TRUE != all.equal(c(R), c(diag(factors)))) {
            cat("\nFactor Correlations:\n")
            print(R, digits = digits, ...)
        }
    }
    if (!is.null(x$STATISTIC)) {
        factors <- x$factors
        cat("\nTest of the hypothesis that", factors, if (factors == 
            1) 
            "factor is"
        else "factors are", "sufficient.\n")
        cat("The chi square statistic is", round(x$STATISTIC, 
            2), "on", x$dof, if (x$dof == 1) 
            "degree"
        else "degrees", "of freedom.\nThe p-value is", signif(x$PVAL, 
            3), "\n")
    }
    else {
        cat(paste("\nThe degrees of freedom for the model is", 
            x$dof, "and the fit was", round(x$criteria["objective"], 
                4), "\n"))
    }
    invisible(x)
}
<bytecode: 0x122e84a08>
<environment: namespace:stats>

The print function is an S3 generic, so we need to find out which S3 method is being used here.

First we use the class function to find out that test is an object of class factanal.

If an S3 print method exists for this class, it will be called print.factanal.

We use the getAnwhere function to search for this method. A method is found in the stats package and printed out.

In the body of the function we can see the cat and print calls that print different elements of the factanal object.

In the 4th line of the function, print is called on the loadings element to print the loadings.

Finding the print method (2)

class(test$loadings)

[1] "loadings"

getAnywhere(print.loadings)

A single object matching 'print.loadings' was found
It was found in the following places
  registered S3 method for print from namespace stats
  namespace:stats
with value

function (x, digits = 3L, cutoff = 0.1, sort = FALSE, ...) 
{
    Lambda <- unclass(x)
    p <- nrow(Lambda)
    factors <- ncol(Lambda)
    if (sort) {
        mx <- max.col(abs(Lambda))
        ind <- cbind(1L:p, mx)
        mx[abs(Lambda[ind]) < 0.5] <- factors + 1
        Lambda <- Lambda[order(mx, 1L:p), ]
    }
    cat("\nLoadings:\n")
    fx <- setNames(format(round(Lambda, digits)), NULL)
    nc <- nchar(fx[1L], type = "c")
    fx[abs(Lambda) < cutoff] <- strrep(" ", nc)
    print(fx, quote = FALSE, ...)
    vx <- colSums(x^2)
    varex <- rbind(`SS loadings` = vx)
    if (is.null(attr(x, "covariance"))) {
        varex <- rbind(varex, `Proportion Var` = vx/p)
        if (factors > 1) 
            varex <- rbind(varex, `Cumulative Var` = cumsum(vx/p))
    }
    cat("\n")
    print(round(varex, digits))
    invisible(x)
}
<bytecode: 0x122e2aee8>
<environment: namespace:stats>

So now we repeat this exercise on the loadings element of our test object.

We find out that the loadings element is an object of class loadings and there is a print.loadings methods in the stats package.

Debugging print.loadings

debugonce(stats::print.loadings)

Error: 'print.loadings' is not an exported object from 'namespace:stats'

debugonce(stats:::print.loadings)
print(test, sort = TRUE)

Call:
factanal(x = mtcars[, 1:4], factors = 1)

Uniquenesses:
  mpg   cyl  disp    hp 
0.199 0.078 0.120 0.261 
debugging in: print.loadings(x$loadings, digits = digits, ...)
debug: {
    Lambda <- unclass(x)
    p <- nrow(Lambda)
    factors <- ncol(Lambda)
    if (sort) {
        mx <- max.col(abs(Lambda))
        ind <- cbind(1L:p, mx)
        mx[abs(Lambda[ind]) < 0.5] <- factors + 1
        Lambda <- Lambda[order(mx, 1L:p), ]
    }
    cat("\nLoadings:\n")
    fx <- setNames(format(round(Lambda, digits)), NULL)
    nc <- nchar(fx[1L], type = "c")
    fx[abs(Lambda) < cutoff] <- strrep(" ", nc)
    print(fx, quote = FALSE, ...)
    vx <- colSums(x^2)
    varex <- rbind(`SS loadings` = vx)
    if (is.null(attr(x, "covariance"))) {
        varex <- rbind(varex, `Proportion Var` = vx/p)
        if (factors > 1) 
            varex <- rbind(varex, `Cumulative Var` = cumsum(vx/p))
    }
    cat("\n")
    print(round(varex, digits))
    invisible(x)
}
Browse[2]> 

If we try running debugonce on stats::print.loadings, we get an error telling us that print.loadings is not exported from the stats package.

We can access internal functions by using three colons instead, so debugonce runs without error.

Now when we run print test with sort = TRUE, the call and uniquenesses are printed, but when print.loadings is called we enter a debugging environment.

The body of this function is printed out to the console … [scroll down] … and at the end we find a Browse prompt.

Press Enter to step through line by line

Browse[2]> 
debug: Lambda <- unclass(x)

Browse[2]> 
debug: p <- nrow(Lambda)

Browse[2]> 
debug: factors <- ncol(Lambda)

Browse[2]> 
debug: if (sort) {
    mx <- max.col(abs(Lambda))
    ind <- cbind(1L:p, mx)
    mx[abs(Lambda[ind]) < 0.5] <- factors + 1
    Lambda <- Lambda[order(mx, 1L:p), ]
}

Browse[2]> 
debug: mx <- max.col(abs(Lambda))

Browse[2]> 
debug: ind <- cbind(1L:p, mx)

Browse[2]> 
debug: mx[abs(Lambda[ind]) < 0.5] <- factors + 1

Browse[2]> 
debug: Lambda <- Lambda[order(mx, 1L:p), ]

We can press the enter or return key to step through the code in the print.loadings function, running one line at a time. (1,2,3)

Here we get to a conditional block that is run if sort = TRUE, as in our test case. When we press return, we enter this block and can continue stepping through line by line. (1, 2, 3, 4)

At the end of this block, there is a line where an object Lambda is overwritten by an ordered version of itself.

Before running this line, we can print Lambda with and without the ordering.

Print objects

Browse[2]> Lambda[order(mx, 1L:p), ]
       mpg        cyl       disp         hp 
-0.8947285  0.9603623  0.9381177  0.8594404 

Browse[2]> Lambda
        Factor1
mpg  -0.8947285
cyl   0.9603623
disp  0.9381177
hp    0.8594404

Browse[2]> Lambda[order(mx, 1L:p), , drop = FALSE]
        Factor1
mpg  -0.8947285
cyl   0.9603623
disp  0.9381177
hp    0.8594404
Browse[2]> 

Here it is with the ordering…

… and here it is without.

Clearly the ordering is changing the structure of the object - we have found the root cause of the issue!

In this case, there is a simple fix.

Experienced R programmers may know that when the rows of a one-column matrix are indexed, a vector is returned, unless we set drop = FALSE, as here.

Modify function

print.loadings <- function (x, digits = 3L, cutoff = 0.1, sort = FALSE, ...) 
{
  Lambda <- unclass(x)
  p <- nrow(Lambda)
  factors <- ncol(Lambda)
  if (sort) {
    mx <- max.col(abs(Lambda))
    ind <- cbind(1L:p, mx)
    mx[abs(Lambda[ind]) < 0.5] <- factors + 1
    Lambda <- Lambda[order(mx, 1L:p), , drop = FALSE]
  }
  cat("\nLoadings:\n")
  fx <- setNames(format(round(Lambda, digits)), NULL)
  nc <- nchar(fx[1L], type = "c")
  fx[abs(Lambda) < cutoff] <- strrep(" ", nc)
  print(fx, quote = FALSE, ...)
  vx <- colSums(x^2)
  varex <- rbind(`SS loadings` = vx)
  if (is.null(attr(x, "covariance"))) {
    varex <- rbind(varex, `Proportion Var` = vx/p)
    if (factors > 1) 
      varex <- rbind(varex, `Cumulative Var` = cumsum(vx/p))
  }
  cat("\n")
  print(round(varex, digits))
  invisible(x)
}

We can check this fix, by creating our own version of print.loadings with the fix applied.

Check

print.loadings(test$loadings, sort = TRUE)

Loadings:
     Factor1
mpg  -0.895 
cyl   0.960 
disp  0.938 
hp    0.859 

               Factor1
SS loadings      3.342
Proportion Var   0.835

After sourcing our version of print.loadings we can test it on the loadings element of our test object.

The fix works!

How to propose a fix

Once we have a fix, how can propose it to R Core?

Comment on Bugzilla

(Requires an account)

If the fix is simple to describe, we can propose it by adding a comment on Bugzilla, as I have done here.

To add comments, you need a Bugzilla account, see the link for more details.

Create a patch via GitHub

Alternatively, create a patch using the r-svn mirror of the R sources: https://github.com/r-devel/r-svn

Alternatively, you can create a patch using the r-svn mirror of the R sources.

Find source file to edit

This will create a fork of the r-svn repo on your GitHub account.

Find the source file containing the code you want to change.

Click the edit button: this will create a fork of the r-svn repo on your GitHub account and open a window where you can edit the file.

Edit the code in the browser

Committing changes will create a branch on your fork

Make the changes in the source file.

When you are ready, click the Commit changes... button to commit these changes to your fork - a new branch will be created with your changes.

Open a PR (1)

Now you will see a Compare & pull request button on your fork.

Click this to open a pull request back to the original r-svn repo.

Open a PR (2)

Enter a description of your changes - here I have written “Minor change for demo”.

If you want, you can add more information in the comment box for people you might ask to review your pull request.

Automated checks

Once you have created a pull request, you will be taken back to the original repo and you’ll see some automated checks starting to run.

These build R on different platforms and run its test suite.

If the checks pass, everything in amber here will turn green.

Create a patch

Add .diff to the URL for your PR, e.g. https://github.com/r-devel/r-svn/pull/124.diff

Right-click to save .diff file.

This patch can be attached to the Bugzilla report, with a comment.

If everything looks good, add .diff to the URL for your Pull Request and enter the modified URL in your browser. This will generate a diff of your changes.

Right-click on the browser window to save this as a .diff file.

You can then attach the diff file to the bug report on Bugzilla, with a comment explaining your proposed fix.

Where next?

• R Development Guide
• R Contributor Events
• R Contributor Slack

This quick demo has run through the basics of contributing to fixing bugs in R.

For more information on this and other ways to contribute, - refer to the online R Development Guide - attend R Contributor Events - or join the Slack group for peer support.

We hope this has inspired you to start contributing to R

Links

• R Core: https://www.r-project.org/contributors.html

• R Contributor Office Hours: https://contributor.r-project.org/events/office-hours/

• R Contributor Slack: https://contributor.r-project.org/slack

• Bug BBQ: https://contributor.r-project.org/events/bug-bbq/

• How to get a Bugzilla account: https://contributor.r-project.org/rdevguide/BugTrack.html#RCorePkgBug

• R Development Guide: https://contributor.r-project.org/rdevguide/

• Slides for this demo: https://hturner.github.io/contributing-demo