A General Message and Error Reporting System.
reportr: Message reporting for R
The reportr
package for R is a simple alternative to R's standard functions for producing informative output, such as message()
, warning()
and stop()
. It offers a certain amount more flexibility than these functions, although it is not (yet) a full logging solution. The package is available on CRAN.
Further alternatives in this area include the futile.logger
, log4r
and logging
packages.
Contents
- Usage
- Using
reportr
to handle standard messages - Output consolidation
- Expression substitution
- Message filtering
- Stack tracing
- The
Question
reporting level
Usage
The key functions in the package are report()
and flag()
. Both take a reporting level as their first argument, which determines the priority of the message. The functions differ only in that report()
reports the message to the console immediately, whereas flag()
, like warning()
, saves it for reporting later. Flagged messages are reported at the next report()
call, to keep output in order.
The setOutputLevel()
function determines the minimal reporting level for which output is actually generated; messages below this level are discarded. This is demonstrated below, by creating a message of level Info
with the output level set first to Warning
(which produces nothing) and then to Info
(which allows the message to be reported).
setOutputLevel(Warning)
report(Info, "Test message")
setOutputLevel(Info)
report(Info, "Test message")
## INFO: Test message
The reporting levels available, in ascending order of priority, are currently Debug
, Verbose
, Info
, Warning
, Question
, Error
and Fatal
. The Error
level raises R's "abort" condition, like stop()
, so execution will stop. The Fatal
level is in practice never used, but can be set as the output level to subdue all reporting.
Using reportr
to handle standard messages
It is possible to arrange for reportr
to handle messages, warnings and errors raised by code that does not itself use report()
or flag()
, by using the wrapper function withReportrHandlers()
. Take, for example, the simple function
f <- function() message("In f()")
Ordinarily calling this function produces
f()
## In f()
Wrapping this will instead give
withReportrHandlers(f())
## * INFO: In f()
Note that calls to message(...)
will translate to report(Info, ...)
, warning(...)
to flag(Warning, ...)
, and stop(...)
to report(Error, ...)
.
This mechanism is not particularly advantageous in itself, but it allows the user to exercise all of the reportr
control options over all code, whether or not it was written with reportr
in mind. These facilities are laid out below.
Output consolidation
Sometimes the same warning is generated many times, and seeing a lot of replication isn't particularly helpful. The following function is somewhat artificial, since it does not take advantage of vectorisation in R, but it illustrates the point.
f <- function(xs) {
ys <- numeric(0)
for (x in xs) ys <- c(ys,sqrt(x))
ys
}
Now let's call the function with input that will produce some warnings.
f(-5:5)
## [1] NaN NaN NaN NaN NaN 0.000000 1.000000 1.414214
## [9] 1.732051 2.000000 2.236068
## Warning messages:
## 1: In sqrt(x) : NaNs produced
## 2: In sqrt(x) : NaNs produced
## 3: In sqrt(x) : NaNs produced
## 4: In sqrt(x) : NaNs produced
## 5: In sqrt(x) : NaNs produced
This duplication of warnings is verbose and unnecessary, and can be consolidated with reportr
:
withReportrHandlers(f(-5:5))
## WARNING: [x5] NaNs produced
## [1] NaN NaN NaN NaN NaN 0.000000 1.000000 1.414214
## [9] 1.732051 2.000000 2.236068
Notice that the five duplicated warnings are reported in one line in this case, along with an indication that the message was produced five times.
Expression substitution
Expression substitution is an alternative to printf
-style syntax for incorporating the values of R expressions into strings. It can make messages more readable, and reduce the need for lots of quotation marks. All reportr
messages are passed through the es()
function for expression substitution, which is part of the ore
package. For example,
x <- 3
report(Info, "The value of x is #{x}")
## INFO: The value of x is 3
Note the #{}
syntax. Everything within the curly braces is evaluated as an R expression, and the result inserted into the string. Please see ?ore::es
for more details.
Message filtering
Sometimes it may be desirable to discard particular messages that would otherwise be reported at the current output level. There are two global options that allow this, reportrMessageFilterIn
and reportrMessageFilterOut
, each of which takes a Perl-style regular expression. The "in" filter is applied first, keeping only messages that match its regex, and then the "out" filter, which keeps only messages that do not match its regex.
f <- function() {
report(Info, "One")
report(Info, "Two")
report(Info, "Three")
}
options(reportrMessageFilterIn="^T")
f()
## * INFO: Two
## * INFO: Three
options(reportrMessageFilterIn=NULL, reportrMessageFilterOut="^T")
f()
## * INFO: One
Stack tracing
The Debug
reporting level is slightly special. When the current output level is Debug
, not only are all messages reported, but stack traces are also automatically provided when the message being reported is of level equal to or above the reportrStackTraceLevel
option (the default is Error
). For example,
f <- function(x) if (!is.numeric(x)) stop("x must be numeric")
g <- function(x) f(x)
withReportrHandlers(g("text"))
## * * ERROR: x must be numeric (in "f(x)")
## --- Begin stack trace ---
## * g("text")
## * * f(x)
## --- End stack trace ---
Notice that the number of asterisks in front of the printed message indicates the depth in the stack of the function reporting the message. This can be useful, in a long stream of output, to determine the structure of the reporting code at a glance. The format of this "prefix" can be customised, however: please see ?report
for details.
The Question
reporting level
In between the Warning
and Error
reporting levels is a level called Question
. This level is used by a function called ask()
, which prompts the user for input and returns the result in a string. If the output level is greater than Question
, or the session is not interactive, a customisable default value is returned.
f <- function() {
name <- ask("What is your name?", default="Nobody")
report(OL$Info, "Hello, #{name}")
invisible(name)
}
setOutputLevel(Info)
f()
## * QUESTION: What is your name? User
## * INFO: Hello, User
setOutputLevel(Error)
(f())
## [1] "Nobody"