Overview
Diagnostic prints in R are vital for communicating to both users and developers what the function is doing and how it may be going wrong. GiottoUtils exports a collection of utility functions that facilitate pretty printing and readability.
There are several types of console printouts in R. Giotto uses the following types of functions for specific purposes:
- message() - Descriptive messages of what a function is doing (most common)
- cat() and print() - Diagnostic outputs, usually comments and previews of the data
- warning() - When a function behavior is potentially problematic, given the context and/or inputs
- stop() - Error messages
Text Formatting
GiottoUtils::wrap_txt() can be used to format text to wrap to to console size or 100 char by default - whichever is less. New lines are treated like “\n” and it also applies an indent to all lines after the first.
This function is wrapped by the convenient print functions detailed below.
library(GiottoUtils)
cat(wrap_txt("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."))## Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
## incididunt ut labore et dolore magna aliqua.
## Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
## aliquip ex ea commodo consequat.You can also use sprintf formatting using wrap_txtf
wrap_txtf("%s morning", "good")## [1] "good morning"See base behavior
Base functions for console prints lack text wrapping. Linebreaks also require usage of “\n” to be formatted as expected.
# Code formatting causes " " to be added the next line
cat("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.")## Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
## Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
# Using \n instead
cat("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.")## Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
## Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.Messages
Giotto primarily uses messages to write helpful console prints. Whenever a function has a message print, we also encourage adding a verbose param so that it can be turned off. The standard implementation looks like this.
test_fun1 <- function(verbose = TRUE) {
if (verbose) message("hello world")
}
test_fun1()## hello worldGiottoUtils v0.1.1 introduces vmsg() which simplifies this to a single function without a preceding if statement. It also applies text wrapping. Note that the verbose default should be NULL with this implementation since vmsg() checks for a default using the "giotto.verbose" option that can be set globally.
test_fun2 <- function(verbose = NULL) {
vmsg(.v = verbose, "hello world")
}
test_fun2()## hello worldDebug messages
vmsg() also provides other modes of prints. For debugging purposes, it can be helpful to include more abstract or wordy printouts such as messages for every successful step. These can be included by flagging as "debug"
test_debug <- function(verbose = NULL) {
vmsg(.v = verbose, .is_debug = TRUE, "this is a debug statement")
vmsg(.v = verbose, "this is a normal message")
}
test_debug(verbose = TRUE)## this is a normal message
test_debug(verbose = "debug")## this is a debug statement
## this is a normal messageLogging messages
For cases where a record of the messages would be helpful, but it would be preferred that nothing is actually printed to the console, vmsg() also supports writing to a logfile. This can be done by passing either "log" or "log_debug" for the desired level of verbosity to the verbose param or "giotto.verbose" option.
The logfile defaults to being created in tempdir(), but this can be set to a directory of choice using the "giotto.logdir" option. The specific path to the logfile is stored within the "giotto.last_logpath".
vmsg(.v = "log", "Write this to a logfile in tempdir")## Logging to:/tmp/RtmpXDgr5h/giotto_20241209_1.txtTo read the log items, use giottoReadLog().
## [1] " (2024-12-09 07:25:44) Write this to a logfile in tempdir"You can start a new logfile using giottoNewLog()
Errors
With the modularization of Giotto in v4.0.0, it can be hard to find which module a specific error came from. .gstop() is an error handling internal function within each of the modules that seeks to solve this. This function will pre-pend which module the error happened in. It also provides the .n param that allows developers to specify how many stackframes back the error should be reported from.
foo <- function(x, y) {
GiottoUtils:::.gstop("This is an error.")
}
bar <- function() {
foo(1, 2)
}
bar()## Error: [GiottoUtils] foo(1, 2):
## This is an error.
foo <- function(x, y) {
GiottoUtils:::.gstop("This is an error.", .n = 2) # report from one stackframe back
}
bar()## Error: [GiottoUtils] bar():
## This is an error.## R version 4.4.2 (2024-10-31)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 22.04.5 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.20.so; LAPACK version 3.10.0
##
## locale:
## [1] LC_CTYPE=C.UTF-8 LC_NUMERIC=C LC_TIME=C.UTF-8
## [4] LC_COLLATE=C.UTF-8 LC_MONETARY=C.UTF-8 LC_MESSAGES=C.UTF-8
## [7] LC_PAPER=C.UTF-8 LC_NAME=C LC_ADDRESS=C
## [10] LC_TELEPHONE=C LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C
##
## time zone: UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] GiottoUtils_0.2.2 BiocStyle_2.34.0
##
## loaded via a namespace (and not attached):
## [1] cli_3.6.3 knitr_1.49 rlang_1.1.4
## [4] xfun_0.49 textshaping_0.4.1 data.table_1.16.4
## [7] gtools_3.9.5 jsonlite_1.8.9 backports_1.5.0
## [10] htmltools_0.5.8.1 ragg_1.3.3 sass_0.4.9
## [13] rmarkdown_2.29 evaluate_1.0.1 jquerylib_0.1.4
## [16] fastmap_1.2.0 yaml_2.3.10 lifecycle_1.0.4
## [19] bookdown_0.41 BiocManager_1.30.25 compiler_4.4.2
## [22] fs_1.6.5 systemfonts_1.1.0 digest_0.6.37
## [25] R6_2.5.1 parallel_4.4.2 magrittr_2.0.3
## [28] bslib_0.8.0 checkmate_2.3.2 tools_4.4.2
## [31] pkgdown_2.1.1 cachem_1.1.0 desc_1.4.3