Vignette for the pio package

Giulio Caravagna

29/04/2019

The pretty I/O R package pio provides functions to print coloured outputs in an organized way to console. This allows organizing outputs in a tidy way, making it easier to spot information while interacting with a tool.

pio provides a few types of functions that display:

• a header, that is meant to display a summary string (like a program name, a function name etc.);
• a title, that is meant to display a string surrounded by some separators (like a title for a task within a multi-step function);
• a string in the format Variable = Value, meant to display a pair (descriptor plus value).

Other functions and simple ways to manipulate color schema are available and shown in this vignette.

Note. pio relies on crayon, which provides core functions to add colours to terminals. This vignette is generated using the fansi package that renders ANSI modified strings from crayon into HTML code. However, some of the generated layout still renders poorly in HTML, but try the package yourself to see how the layout looks like.

# The hook for this vignette, via fansi
old.hooks <- fansi::set_knit_hooks(knitr::knit_hooks)

# Activate crayon and pio
options(crayon.enabled = TRUE)
require(pio)

Header

A header is a one-line information that can be used to communicate the name of a tool, model, algorithm etc.

It’s simpler form is just some lines of text, which in the baseline setting is white on blue background. The function accepts an ellipsis to allow easy concatenation of multiple values.

version = '1.0'
tool_name = 'COOLTOOL'

pioHdr("My new", tool_name, version)

 [ My new COOLTOOL 1.0 ] 

The header function can accepts also parameters, and use other pio functions to print them (pioTkn and pioStr, see below). This helps using pioHdr in the beginning of a compplex function call, where we want to summarize some behaviour to the user. Notice that, if the parameters have no names associated, automatic names are generated.

# Parameters
x = 12345
y = TRUE
z = NA  # Notice this how it gets printed

# Vector (without names)
params = c(x, y, z)

pioHdr("My new", tool_name, version, 
       toPrint = params)

 [ My new COOLTOOL 1.0 ] 
Arg. #1 12345 
Arg. #2 1 
Arg. #3  NA  

# Add names, and re-print
names(params) = c("Input = ", "Test = ", "Plot = ")

pioHdr("My new", tool_name, version, 
       toPrint = params)

 [ My new COOLTOOL 1.0 ] 
Input =  12345 
Test =  1 
Plot =   NA  

The list of parameters can be displaied with some extra prefix, (e.g., an intendation, a separator etc.), that is added to all values in toPrint using the pioStr function. For instance, if we want to add a tabulation to arrange all parameters we can use prefix = '\t- '.

Titles

A title is just a piece of text surrounded by some nice separator. In its simpler form is can contain one or more strings (like the header, via an ellipsis).

# A title with variables
x = 12345
y = "myFun"

pioTit('We now call', y, 'with', x, "as input")

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 We now call myFun with 12345 as input
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

This function accepts also a prefix argument that can ben used to append some string before all strings print by pioTit.

# A title with escape chars in the prefix
pioTit('We now call', y, 'with', x, "as input",
       prefix = '>--\\/\\/\\/-->>\t')

>--\/\/\/-->>    =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
>--\/\/\/-->>  We now call myFun with 12345 as input
>--\/\/\/-->> =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

The separator can also be customized.

pioTit('We now call', y, 'with', x, "as input", 
       separator_motif = '~')

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 We now call myFun with 12345 as input
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Strings

Function pioStr can print a pair of values which are thought to represent a description, followed its a value. For instance P-value = 0.05 could be print by passing the string "P-value =" together with 0.05 as arguments to pioStr. Notice that the value content is tokenized by function pioTkn (see below).

# Simple call
pioStr('N = ', 12345)

N =  12345 

# Observe the tokenization
pioStr('A & B = ', TRUE, 'while the result is', NULL)

A & B =  TRUE while the result is  NULL  

This function accepts both a prefix and a suffix argument.

x = 1:5

invisible(sapply(x, pioStr,  str = 'N = ', prefix = '\t- ', suffix = '\n'))

    - N =  1 
    - N =  2 
    - N =  3 
    - N =  4 
    - N =  5 

Color schema

pio provides a default color schema colorscheme_default, which is a combination of blue, cyan and white colours from crayon. The colours are essentially controlled via some global variables named pio.XXX, and there are options to control pretty much the background and foreground colour of each pio function.

A colour scheme is defined as in this function

print(colorscheme_default)

function () 
{
    options(pio.header_bg_colour = crayon::bgBlue)
    options(pio.header_fg_colour = crayon::white)
    options(pio.title_sep_colour = crayon::cyan)
    options(pio.title_fg_colour = crayon::cyan)
    options(pio.string_bg_colour = crayon::bgBlack)
    options(pio.string_fg_colour = crayon::cyan)
}
<bytecode: 0x7fd8585c7b90>
<environment: namespace:pio>

If you want to change colour scheme you just need to call the appropriate function. There are 2 extra color schema available in the package, colorscheme_orange_black which combines yellow and black colours, and colorscheme_purple_ivory which combines violet and white colours.

colorscheme_orange_black()

pioHdr("My function name")

 [ My function name ] 

pioTit("A long title for my computation")

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 A long title for my computation
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

pioStr("Variable X = ", TRUE)

Variable X =  TRUE