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/Rtmp9iVjYE/giotto_20250205_1.txtTo read the log items, use giottoReadLog().
## [1] " (2025-02-05 01:03:19) 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 24.04.1 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.26.so; LAPACK version 3.12.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.4 BiocStyle_2.34.0
##
## loaded via a namespace (and not attached):
## [1] cli_3.6.3 knitr_1.49 rlang_1.1.5
## [4] xfun_0.50 textshaping_1.0.0 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.3 jquerylib_0.1.4
## [16] fastmap_1.2.0 yaml_2.3.10 lifecycle_1.0.4
## [19] bookdown_0.42 BiocManager_1.30.25 compiler_4.4.2
## [22] fs_1.6.5 systemfonts_1.2.1 digest_0.6.37
## [25] R6_2.5.1 parallel_4.4.2 magrittr_2.0.3
## [28] bslib_0.9.0 checkmate_2.3.2 tools_4.4.2
## [31] pkgdown_2.1.1 cachem_1.1.0 desc_1.4.3