Three steps of data documentation

In order to understand how different parts of the report creation can be customized, we will briefly dwell on the structure of the data reports made by dataReporter. Aside from a few pages dedicated to gaining an overview of the full dataset and what was done to document its current state, the report sequentially presents information for each variable. More specifically, each variable is presented with one of the two sets of information:

1. The result of a single eligibility check (referred to as a pre-check below)
2. The results of the three canonical dataReporter steps:
   • Summarize: Produces a summary table
   • Visualize: Produces a distribution visualization
   • Check: Performs and lists the results of a number of checks

The first option will be used for variables that do not pass the initial pre-checks. These are checks that are performed in order to identify variables that are not eligible for detailed documentation for one reason or another. The default pre-checks used in makeDataReport() are

• isKey: Check if the variable is a key, i.e. categorical with unique values for each observation
• isSingular: Check if the variable only takes a single (non-NA) value
• isSupported: Check if the class of the variable is among the classes supported by dataReporter

If any of these checks finds a problem, the relevant problem will be mentioned in the report and the variable will not be exposed to further documentation steps. If the pre-checks do not flag a variable, on the other hand, the variable will be subjected to the three SVC (summarize, visualize, check) steps mentioned above. In the SVC-steps, makeDataReport() calls a number of so-called summaryFunctions, visualFunctions and checkFunctions, with different choices of functions depending on the class of the variable. The customizability features of dataReporter essentially comes down to writing such summaryFunctions, visualFunctions and checkFunctions.

This vignette consists of three parts. First, we describe how new summaryFunctions, visualFunctions and checkFunctions can be made by describing the requirements for their structures that must be fulfilled in order for them to be used in a makeDataReport() call. Secondly, we turn to a worked example of how to write custom made functions in practice. Here, we define and showcase six new SVC functions. Lastly, a built-in dataset about art masterpieces, artData, is documented using the custom-made functions and the thereby obtained data report is included.

In this vignette, we focus on the report creation tools of dataReporter. However, it should be emphasized that by following the guidelines presented here, the user-defined summaryFunctions, visualFunctions and checkFunctions will also be fully integrated with the interactive mode of dataReporter.

Writing a summaryFunction

As mentioned above, dataReporter provides a dedicated class for summaryFunctions. However, this does not imply that they are particularly advanced or complicated to create; in fact, they are nothing but regular functions with a particular input/output-structure. Specifically, they all follow the template below:

mySummaryFunction <- function(v, ...) {
  val <- [result of whatever summary we are doing]
  res <- [properly escaped version of val]
  summaryResult(list(feature = "[Feature name]", result = res,
                     value = val))
}

The last function called here, summaryResult(), changes the class of the output, thereby making a print() method available for it. Note that v is an input vector and that res should be either a character string or something that will be printed as one. In other words an integer would be allowed for res, but a matrix will not. Note that, strictly speaking, only one of the two elements value and result is needed in order to create a summaryResult. If result is provided, this will be printed as the summary result. However, if only value is provided, the summaryResult() function will try to convert it to a character string itself. This might be more or less difficult to do in a reasonable way, so therefore, we really do recommend to provide this conversion yourself by both returning a result and a value.

Though a lot of different things can go into the summaryFunction template, we recommend only using it for summarizing the features of a variable, and leaving tests and checks for the checkFunctions (presented below).

Adhering to the template above is sufficient for using the freshly made mySummaryFunction() in makeDataReport(), but we recommend adding the new function to the overview of all summary functions by converting it to a proper summaryFunction object. This is done by calling the summaryFunction() creator with the user-defined function as the first argument, and additional arguments description (an explanatory text which will be added to the attributes of the function), and classes (a vector of variable classes the user-defined function is intended to be applied to, also stored as an attribute). In other words, a call following the template below should be made:

mySummaryFunction <- summaryFunction(mySummaryFunction,
  description = "[Text describing what the summaryFunction does]",
  classes = c([vector of data types that the function is intended
  for]))

which adds the new function to the output of an allSummaryFunctions() call. If mySummaryFunction is constructed as an S3 generic function with associated methods, the call to summaryFunction() will automatically produce a vector of the names of the classes for which the function can be called. If mySummaryFunction() is not an S3 generic and classes is left unspecified, the attribute will simply be left empty. Note that the helper function allClasses() might be useful for filling out the classes argument, as it simply lists all supported classes in dataReporter:

allClasses()

## [1] "character"      "Date"           "factor"         "integer"       
## [5] "labelled"       "haven_labelled" "logical"        "numeric"

Writing a visualFunction

visualFunctions are the functions that produce the figures in a dataReporter output document. Writing a visualFunction is slightly more complicated than writing a summaryFunction. This is due to the fact that visualFunctions need to be able to output standalone code for plots in order for makeDataReport() to build standalone rmarkdown files. We recommend using the following structure (again shown as pseudo code):

myVisualFunction <- function(v, vnam, doEval) {
  thisCall <- call("[the name of the function used to produce the plot]",
    v, [additional arguments for the plotting function])
  if (doEval) {
    return(eval(thisCall))
  } else return(deparse(thisCall))
}

In this function, v is the variable to be visualized, vnam is its name (which should generally be passed to title or main arguments in plotting functions) and doEval controls whether the output is a plot (if TRUE) or a character string of standalone code for producing a plot (if FALSE). Implementing the doEval = TRUE setting is not strictly necessary for a visualFunction’s use in makeDataReport(), but it makes it easier to assess what visualization options are available, and obviously, it is crucial for interactive usage of myVisualFunction(). In either case, it should be noted that all the parameters listed above, v, vnam and doEval, are mandatory, so they must be left as is, even if they are not in use (c.f., the table).

As with the summary function, we call visualFunction() to register our newly created function:

myVisualFunction <- visualFunction(myVisualFunction,
  description = "[Some text describing the visualFunction]",
  classes = c([data types that this function is intended for]))
  )

Now, myVisualFunction() will be available in a allVisualFunctions() call, just like the two build-in visualFunctions, standardVisual and basicVisual.

Writing a checkFunction

The last, but perhaps most important, dataReporter function type is the checkFunction. These are the functions that flag issues in the data in the check step and/or control the overall flow of the data documenting process in the pre-check stage. A checkFunction follows one of two overall structures, depending on the type of check. Either, it tries to identify problematic values in the variable (as e.g., identifyMissing() does), or it performs a check concerning the variable as a whole (e.g., the functions used for pre-checks and the function identifyNums()). We present templates for both types of checkFunctions below separately, but it should be emphasized that formally, they belong to the same class.

First, a template for the full-variable check function type, where we first define the function and subsequently register it as a check function using checkFunction():

myFullVarCheckFunction <- function(v, ...) {
  [do your check]
  problem <- [is there a problem? TRUE/FALSE]
  message <- "[message describing the problem, if any]"
  checkResult(list(problem = problem,
    message = message,
    problemValues = NULL))
}

myFullVarCheckFunction <- checkFunction(myFullVarCheckFunction,
  description = "[Some text describing the checkFunction]",
  classes = c([the data types that this function is intended to be used for])
  )

Again, as with summaryFunctions and visualFunctions, the change of function class by use of checkFunction() is not strictly necessary. Note however, that if myFullVarCheckFunction is to be used in the summarize/visualize/check steps in makeDataReport(), the description attribute will be printed in the overview table in the Data report overview part of the report.

If problematic values are to be identified, the template from above should be expanded to follow a slightly more complicated structure (again shown as pseudo-code):

myProbValCheckFunction <- function(v, nMax, maxDecimals, ...) {
  [do your check]
  problem <- [is there a problem? TRUE/FALSE]
  problemValues <- [vector of values in v that are problematic]
  problemStatus <- list(problem = problem,
                        problemValues = problemValues)

  problemMessage <- "[Message that is printed prior to listing
                     problem values in the dataReporter output,
                     ending with a colon]"

  outMessage <- messageGenerator(problemStatus, problemMessage, nMax)

  checkResult(list(problem = problem,
    message = outMessage,
    problemValues = problemValues))
}

myProbValCheckFunction <- checkFunction(myProbValCheckFunction,
  description = "[Some text describing the checkFunction]",
  classes = c([the data types that this function is intended to be used for])
)

One comment should be devoted to the helper function, messageGenerator(). This function’s sole purpose is aiding consistent styling of all checkFunction messages. The function simply pastes together the problemMessage and the problemValues, with the latter being quoted and sorted alphabetically. If the nMax argument to messageGenerator() is not Inf, only the first nMax problem values will be pasted onto the message, accompanied by a comment about how many problem values were left out (if any). Note that printing quotes in rmarkdown requires an extensive amount of character escaping, so opting for messageGenerator() really is the easiest solution.

In the template above, the argument maxDecimals is not in use. This argument should be used to round off the problemValues passed to messageGenerator(), if they are numerical. This can be done by adding an extra line of code after defining problemStatus in the template above:

myProbValCheckFunction <- function(v, nMax, maxDecimals, ...) {
  [... more lines of code here ...]
  problemStatus <- list(problem = problem,
    problemValues = problemValues)

  if (!is.null(problemValues)) {
    problemStatus$problemValues <- round(problemValues, maxDecimals)
  }
  [... more lines of code here ...]
}

Now, problematic values will be rounded in the outputted message, while they will still appear in their original format under the entry problemValues in the returned object.

summaryFunction examples: countZeros() and meanSummary()

We start by defining two summary functions. For both functions, we use summaryResult() for creating the function output and then we use summaryFunction() in order to add the functions to the output from a allSummaryFunctions() call.

countZeros <- function(v, ...) {
  val <- length(which(v == 0))
  summaryResult(list(feature = "No. zeros", result = val, value = val))
}

#Called on a numeric variable
countZeros(c(rep(0, 5), 1:100))

## No. zeros: 5

#Called on a character variable
countZeros(c(rep(0, 5), letters))

## No. zeros: 5

countZeros <- summaryFunction(countZeros,
  description = "Count number of zeros",
  classes = c("character", "factor", "integer",
              "labelled", "numeric"))

meanSummary <- function(v, maxDecimals = 2) {
  UseMethod("meanSummary")
}

meanSummary(1)

## Error in UseMethod("meanSummary"): no applicable method for 'meanSummary' applied to an object of class "c('double', 'numeric')"

meanSummaryHelper <- function(v, maxDecimals) {
  #remove missing observations
  v <- na.omit(v)
  
  #compute mean and store "raw" output in `val`
  val <- mean(v)
  
  #store printable (rounded) output in `res`
  res <- round(val, maxDecimals)
  
  #output summaryResult
  summaryResult(list(feature = "Mean", result = res, value  = val))
}

#logical
meanSummary.logical <- function(v, maxDecimals = 2) {
  meanSummaryHelper(v, maxDecimals)
}

#numeric
meanSummary.numeric <- function(v, maxDecimals = 2) {
  meanSummaryHelper(v, maxDecimals)
}

#integer
meanSummary.integer <- function(v, maxDecimals = 2) {
  meanSummaryHelper(v, maxDecimals)
}

#called on a numeric variable (supported)
meanSummary(rnorm(100))

## Mean: -0.01

#called on a character variable - produces error as there is
#no method for characters
meanSummary(letters)

## Error in UseMethod("meanSummary"): no applicable method for 'meanSummary' applied to an object of class "character"

meanSummary <- summaryFunction(meanSummary,  
                               description = "Compute arithmetic mean")

allSummaryFunctions()

visualFunction examples: mosaicVisual() and prettierHist()

We will now define two different visual functions. The first one is a graphics-based function, while the second one is ggplot2-based.

#construct a character variable by sampling 100 values that are 
#either "a" (probability 0.3) or "b" (probability 0.7):
x <- sample(c("a", "b"), size = 100, replace = TRUE,
                   prob = c(0.3, 0.7))

#draw a mosaic plot of the distribution:
mosaicplot(table(x))

mosaicVisual <- function(v, vnam, doEval) {
  #Define a (unevaluated) call to mosaicplot
  thisCall <- call("mosaicplot", table(v), main = vnam, xlab = "")
  
  #if doEval is TRUE, evaluate the call, thereby producing a plot
  #if doEval is FALSE, return the deparsed call
  if (doEval) {
    return(eval(thisCall))
  } else return(deparse(thisCall))
}

mosaicVisual(x, "Variable x", doEval = FALSE)

## [1] "mosaicplot(structure(c(a = 31L, b = 69L), dim = 2L, dimnames = list(" 
## [2] "    v = c(\"a\", \"b\")), class = \"table\"), main = \"Variable x\", "
## [3] "    xlab = \"\")"

mosaicVisual <- visualFunction(mosaicVisual,
                               description = "Mosaic plots using graphics",
                               classes = setdiff(allClasses(), 
                                                 c("numeric", 
                                                   "integer", 
                                                   "Date")))

library(ggplot2)

prettierHistHelper <- function(v, vnam) {
  #define a ggplot2 histogram 
  p <- ggplot(data.frame(v = v), aes(x = v)) + 
          geom_histogram(col = "white", bins = 20) +
          xlab(vnam)
  
  #return the plot
  p
}

prettierHistHelper(rnorm(100), "Standard normal variable")

#define visualFunction-style prettierHist()-function
prettierHist <- function(v, vnam, doEval = TRUE) {
  #define the call
  thisCall <- call("prettierHistHelper", v = v, vnam = vnam)
  
  #evaluate or deparse
  if (doEval) {
    return(eval(thisCall))
  } else return(deparse(thisCall))
}

#Make it a proper visualFunction:
prettierHist <- visualFunction(prettierHist, 
    description = "ggplot2 style histogram with contours",
    classes = c("numeric", "integer", "logical", "Date"))

allVisualFunctions()

checkFunction examples: isID() and identifyColons()

Next up is two new check functions. First, we will define a check function that is intended for use in the pre-check stage, i.e. used for screening variables for eligibility for the summarize/visualize/check-steps. This will be a function that checks the entries in a variable for a certain structure which often used in ID type variables and we will name the new function isID(). Afterwards, we will define a check function that looks for : in categorical variables, as these might be the result of unintended interactions introduced in the data wrangling process.

isID <- function(v, nMax = NULL, ...) {
  #define minimal output. Note that this is not a
  #proper checkResult
  out <- list(problem = FALSE, message = "")
  
  #only perform check if the variable is neither a logical nor a Date
  if (class(v) %in% setdiff(allClasses(), c("logical", "Date"))) {
    
    #count the number of characters in each entry of v
    v <- as.character(v)
    lengths <- c(nchar(v))
    
    #check if all entries of v have at least 8 characters
    #and whether they all have the same length. If so,
    #flag as a problem.
    if (all(lengths >= 8) & length(unique(lengths)) == 1) {
      out$problem <- TRUE
      out$message <- "Warning: This variable seems to contain ID codes."
    }
  }

  #return result of the check
  out
}

#define 9-character ID variable:
idVar <- c("1234-1233", "9221-0289",
           "9831-1201", "6722-1243")

#check for ID resemblance for the ID variable
isID(idVar)

## $problem
## [1] TRUE
## 
## $message
## [1] "Warning: This variable seems to contain ID codes."

#check for ID resemblance for a non-ID variable
isID(rnorm(10))

## $problem
## [1] FALSE
## 
## $message
## [1] ""

identifyColons <- function(v, nMax = Inf, ... ) {
  #remove duplicates (for speed) and missing values:
  v <- unique(na.omit(v))
  
  #Define the message displayed if a problem is found:
  problemMessage <- "Note that the following values include colons:"
  
  #Initialize the problem indicator (`problem`) and 
  #the faulty values (`problemValues`)
  problem <- FALSE
  problemValues <- NULL
  
  #Identify values in v that has the structure: First something (.), 
  #then a colon (:), and then something again (.), i.e. values with
  #non-trailing colons: 
  problemValues <- v[sapply(gregexpr(".:.", v),
                            function(x) all(x != -1))]

  #If any problem values are identified, set the problem indicator
  #accordingly
  if (length(problemValues) > 0) {
    problem <- TRUE
  }

  #Combine the problem indicator and the problem values
  #into a problem status object that can be passed to 
  #the messageGenerator() helper function that will
  #make sure the outputted message is properly escaped
  #for inclusion in the dataReporter report
  problemStatus <- list(problem = problem, 
                        problemValues = problemValues)
  outMessage <- messageGenerator(problemStatus, problemMessage, nMax)

  #Output a checkResult with the problem, the escaped
  #message and the raw problem values.
  checkResult(list(problem = problem,
                   message = outMessage,
                   problemValues = problemValues))
}

identifyColons <- checkFunction(identifyColons,
    description = "Identify non-trailing colons",
    classes = c("character", "factor", "labelled"))

#define a variable as an interaction between between two factors:
iaVar <- factor(c("a", "b", "a", "c")):factor(c(1, 2, 3, 4))

#Check iaVar for colons:
identifyColons(iaVar)

## Note that the following values include colons: a:1, a:3, b:2, c:4.

identifyColons(letters)

## No problems found.

Calling the new summarize/visualize/check functions from makeDataReport()

Now, we are ready to use all the new functions in a makeDataReport() call. We wish to produce a report that utilizes the newly defined functions in the following way:

• We want to add the new pre-check function, isID(), to the already existing pre-checks.
• We wish to change the plot type for factor variables to be mosaicVisual(), while numeric, integer and Date variables should use prettierHist() for their visualizations.
• We want the new summary function, countZeros(), to be added to the summaries performed on all variable types except for Date and logical.
• We want the new summary function, meanSummary(), to be used for numeric, integer and logical variables.
• We want the new check function, identifyColons(), to be added to the checks performed on character, factor and labelled variables.

We will make a data report for the built-in dataset artData that is based on the Master Works of Art data from Data Explorer. The dataset contains 200 observations (corresponding to paintings) of 11 variables, describing different properties of the paintings and their artists. The first 5 observations look like this:

data(artData)
head(artData, 5)

##   ArtistID              ArtistName NoOfMiddlenames
## 1 29da884a          Georges Seurat               0
## 2 f055cbb8           Giacomo Balla               0
## 3 5323b3b8 Lucas Cranach the Elder               2
## 4 ca07b695       Hugo van der Goes               2
## 5 02161eeb              Grant Wood               0
##                                                 Title Year
## 1 A Sunday Afternoon on the Island of La Grande Jatte 1886
## 2                            Abstract Speed and Sound 1914
## 3                            Adam and Eve in Paradise 1531
## 4                              Adoration of the Kings 1470
## 5                                     American Gothic 1930
##                   Location     Continent  Width Height     Media
## 1 Art Institute of Chicago North America 308.00 207.60 oil paint
## 2        Guggenheim Museum North America  76.52  54.61 oil paint
## 3           Gemaldegalerie        Europe  35.50  50.40 oil paint
## 4           Gemaldegalerie        Europe 242.00 147.00 oil paint
## 5 Art Institute of Chicago North America  62.40  74.30 oil paint
##                                           Movement
## 1 Post-Impressionist:Neo-Impressionist:Pointillist
## 2                                         Futurism
## 3                               German Renaissance
## 4                             Northern Renaissance
## 5                                      Regionalist

The 11 variables of artData can be summarized as follows:

• ArtistID: A unique ID used for cataloging the artists (fictional)
• ArtistName: The name of the artist
• NoOfMiddleNames: The number of middle names the artist has
• Title: The title of the painting
• Year: The approximate year in which the painting was made
• Location: The current location of the painting
• Continent: The continent of the current location of the painting
• Width: The width of the painting, in centimeters
• Height: The height of the painting, in centimeters
• Media: The media/materials of the painting
• Movement: The artistic movement(s) the painting belongs to

The options for the data report described above are specified as follows:

makeDataReport(artData,
  #add extra precheck function         
  preChecks = c("isKey", "isSingular", "isSupported", "isID"),
      
  #Add the extra summaries - countZeros() for character, factor, 
  #integer, labelled and numeric variables and meanSummary() for integer, 
  #numeric and logical variables:
  summaries = setSummaries(
    character = defaultCharacterSummaries(add = "countZeros"),
    factor = defaultFactorSummaries(add = "countZeros"),
    labelled = defaultLabelledSummaries(add = "countZeros"),
    numeric = defaultNumericSummaries(add = c("countZeros", "meanSummary")),
    integer = defaultIntegerSummaries(add = c("countZeros", "meanSummary")),
    logical = defaultLogicalSummaries(add =  c("meanSummary"))
  ),
  
  #choose mosaicVisual() for categorical variables,
  #prettierHist() for all others:
  visuals = setVisuals(
    factor = "mosaicVisual",
    numeric = "prettierHist",
    integer = "prettierHist", 
    Date = "prettierHist"
  ), 
      
  #Add the new checkFunction, identifyColons, for character, factor and 
  #labelled variables:
  checks = setChecks(
    character = defaultCharacterChecks(add = "identifyColons"),
    factor = defaultFactorChecks(add = "identifyColons"),
    labelled = defaultLabelledChecks(add = "identifyColons")
  ),
  
  #overwrite old versions of the report, render to html and don't 
  #open the html file automatically:
  replace = TRUE, 
  output = "html",
  open = FALSE
)

We have chosen the output to be html (output = "html") so that it can easily be included in this vignette by use of the includeHTML() function from the htmltools package. We have set open = FALSE so that the outputted html file is not opened automatically. The outputted report is available at the end of this vignette.