Nullable Optional Arguments in Rcpp functions

May 17, 2020
By

[This article was first published on Rcpp Gallery, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Introduction

Often we need to have optional arguments in R of Rcpp functions with default values. Sometimes,
the default value for the optional parameters is set to be NULL. Rcpp provides the Nullable <>
to set default value as to be R_NilValue (equivalent of NULL in Rcpp). There have been several
StackOverflow posts on using the
Nullable behavior. As seen from quite a few posts, the key step in using Rcpp::Nullable<> is
to cast it to the underlying type first (i.e., instantiation) after checking that the input is not
NULL.

Nullability of Vector, Matrix or Logical Vector

// Checking setting Vector, Matrix and LogicalVector to NULL by default and 
// using the input if not set to NULL
#include 
using namespace Rcpp;

// [[Rcpp::export]]
void nullable1(Nullable<NumericVector> NV_ = R_NilValue, 
               Nullable<NumericMatrix> NM_ = R_NilValue, 
               Nullable<LogicalVector> LG_ = R_NilValue){
  
    if (NV_.isNotNull()) {
        NumericVector NV(NV_);        // casting to underlying type NumericVector
        Rcout << "Numeric Vector is set to not NULL." << std::endl;
        Rcout << NV << std::endl;
    } else if (NM_.isNotNull()){
        NumericMatrix NM(NM_);       // casting to underlying type NumericMatrix
        Rcout << "Numeric Matrix is set to not NULL." << std::endl;
        Rcout << NM << std::endl;
    } else if (LG_.isNotNull()){
        LogicalVector LG(LG_);       // casting to underlying type Boolean
        Rcout << "Logical Vector is set to not NULL." << std::endl;
        Rcout << LG << std::endl;
    } else {
        warning("All arguments are set to NULL.\n");
    }
}

Running a few examples with setting NULL for a vector, matrix or a boolean value gives us the
expected results.

nullable1(c(1,2), NULL, NULL)
Numeric Vector is set to not NULL.
1 2
m <- matrix(-0.5, 3, 3)
nullable1(NULL, m, NULL)
Numeric Matrix is set to not NULL.
-0.500000 -0.500000 -0.500000
-0.500000 -0.500000 -0.500000
-0.500000 -0.500000 -0.500000
nullable1(NULL, NULL, FALSE)
Logical Vector is set to not NULL.
0
nullable1(NULL, NULL, NULL)
Warning in nullable1(NULL, NULL, NULL): All arguments are set to NULL.
nullable1(c(), NULL, NULL)
Warning in nullable1(c(), NULL, NULL): All arguments are set to NULL.

We get the same result when the input to the NumericVector argument is not NULL but an empty
vector, i.e., c(), which is also expected since is.null(c()) is TRUE in R.

A stricter test whether the input is usable can be (aptly named) isUsable().

// Testing another check, isUsable for a Nullable Vector
#include 
using namespace Rcpp;

// [[Rcpp::export]]
void nullable2(Nullable<NumericVector> NV_ = R_NilValue) {
  
    if (NV_.isUsable()) {
        NumericVector NV(NV_);        // casting to underlying type NumericVector
        Rcout << "Input is usable." << std::endl;
        Rcout << NV << std::endl;
    } else {
        Rcout << "Input is either NULL or not usable." << std::endl;
    }
}

Nullability of DataFrame and List

Rcpp::Nullable<> works for SEXP based Rcpp types, so Rcpp::DataFrame and Rcpp::List can
also be set to Nullable and instantiated if not NULL.

// Checking setting List and DataFrame to NULL by default and 
// using the input if not set to NULL
#include 
using namespace Rcpp;

// [[Rcpp::export]]
void nullable3(Nullable<List> ls_ = R_NilValue, Nullable<DataFrame> df_ = R_NilValue){

    if (ls_.isNotNull()){
        Rcpp::List ls(ls_);                          // casting to underlying type List
        Rcout << "List is not NULL." << std::endl;
        Rcout << "List length of " << ls.length() << " elements." << std::endl;
    } else if(df_.isNotNull()) {
        Rcpp::DataFrame df(df_);                    // casting to underlying type DataFrame
        Rcout << "DataFrame is not NULL." << std::endl;
        Rcout << "DataFrame of " << df.nrows() << " rows and " << df.length() << " columns." << std::endl;
    } else {
        warning("Both inputs are NULL.\n");
    }
}

Testing with Rcpp::List and Rcpp::DataFrame gives expected results, i.e.,

mylist <- list(A = 1:10, B = letters[1:10])
nullable3(mylist, NULL)
List is not NULL.
List length of 2 elements.
df  <- data.frame(A = 1:20, B = letters[1:20])
nullable3(NULL, df)
DataFrame is not NULL.
DataFrame of 20 rows and 2 columns.

Nullability of RcppGSL::Matrix

In addition to Rcpp types, RcppGSL::Matrix can also be set with Nullable type (e.g, in the
mvlabund
package):
e.g.,

// Checking setting RcppGSL Matrix to NULL by default and 
// using the input if not set to NULL
// [[Rcpp::depends(RcppGSL)]]
#include 

using namespace Rcpp;

// [[Rcpp::export]]
void nullable4(Rcpp::Nullable<RcppGSL::Matrix> M_ = R_NilValue) {
  
    if (M_.isNotNull()){
        RcppGSL::Matrix M(M_);      // casting to underlying type RcppGSL::Matrix
        Rcout << "Input is not NULL." << std::endl;
        Rcout << "Input GSL matrix has " << M.nrow() << " and " << M.ncol() << " columns.\n";
    } else {
        warning("Input GSL Matrix is NULL.\n");
    }
}

Finally, testing with RcppGSL::Matrix which can also be set to Nullable<>, i.e.,

nullable4(NULL)  # testing with NULL 
Warning in nullable4(NULL): Input GSL Matrix is NULL.
m <- matrix(-0.5, 3, 3) # testing with a non-NULL matrix
nullable4(m)
Input is not NULL.
Input GSL matrix has 3 and 3 columns.

Summary

Rcpp provides a convenient construct to set datatypes to NULL using R_NilValue and application
of the datatype if not set to NULL using the .isNotNull() check. This construct to applied to
set datatypes to NULL as default values and possible simple simplification.

To leave a comment for the author, please follow the link and comment on their blog: Rcpp Gallery.

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.



If you got this far, why not subscribe for updates from the site? Choose your flavor: e-mail, twitter, RSS, or facebook...

Comments are closed.

Search R-bloggers

Sponsors

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)