How to Create Custom R Functions

If you need to repeat R code in lots of places in your document or lines in an output, you may want to create a custom R function to streamline your code. You can do this within an R item directly or add the function code to a Calculation > Custom Code output to be able to reference the function by name in all R items in your document. This article covers the basics around functions in R as well as how you can use those and create your own within Displayr. More specifically it covers:

Different types of functions that you can use with R in Displayr
Where you can create a custom function
Rules for standalone custom functions
How to use other custom functions and data inside custom functions

A document covering this content that you can copy down and interact with can be found here.

Different types of functions that you can use with R in Displayr

Base R and basic Displayr functions - these functions are loaded automatically when R code is processed and include base R functions (i.e. head(), colnames(), dim()) and basic functions written by Displayr (i.e. Sum(), Average(), Max()).
R package functions - specialized functions are grouped and loaded via packages in R using library() common packages used are stringr, tidyverse, dplyr, and haven. Specific functions from packages can also be ran individually using the :: notation (i.e. stringr::str_length) as well.
Custom R functions - you can also write your own custom functions inside R CODE in any Calculation in Displayr, but see the Where you can create a custom function below to see requirements for this.

Where you can create a custom function

Because Calculations are each processed individually via a separate request to the R servers, there is no shared Global Environment across them. Therefore to use a custom function, you can have its code in one of the following places:

The Calculation that is using it - used to do very specialized things for minimal outputs in a document.
A separate standalone Calculation to be referenced by others - used when several outputs need to use the custom function. It can also be copied to other documents.
A pseudo package to be loaded from the cloud - used to share custom functions across documents and ensure that the function code is not exposed for editing. This requires intermediate to advanced R skills, see How to Share Custom R Functions in Displayr.
An RScript saved to the cloud accessible via your company menu - clicking the menu item then creates a new Calculation in the document for the function. This is only available to Enterprise customers.

Rules for standalone custom functions

Standalone custom functions are where a separate Calculation is created in the document for the function. This Calculation can be referenced by other Calculations to generate outputs, see How to Create Chart Templates Using R Functions for an example. This is useful when multiple outputs in a document need to use this function. The rules below are due to how R CODE is processed by Displayr, so you may want to review How R Works Differently in Displayr Compared to Other Programs before reading more.

Only the last function in the output is used

So the add function in the Calculations below cannot be used:

Only the final Calculation's R CODE is reviewed for items/outputs to send along for processing (references to other items are not recursive)

This means that data and functions needed for the final output must be referenced in the final output or created within the custom function that needs it. For users that create lots of custom functions, it's easy to over look this as things appear to be found in the custom function, but when using the custom function there is an error returned. See the custom function below on the left that uses the standalone minus function and the resulting error on the right:

Also see an example referencing data in the document that appears to be found by the function on the left, but cannot be used by the final output on the right because thetable was not in the final R CODE.

How to use other custom functions and data inside custom functions

There are a few different ways to use other custom functions and data inside custom functions:

Other item is created within the function - useful when other functions don't need the additional function (addmore below) or you are reading data from an external source and don't need the data being used elsewhere in your document (find.abb below):
Other item is referenced or created within the final output - use if you are also using those functions/data directly in the final code or across multiple custom functions within your final output. Below, see the custom function on top that references another custom function minus, then the two different solutions in the two outputs underneath.