Callbacks

Although R has been tightly bound to its console, the R-core development team has great progress in letting front-end developpers customize R’s interactive behavior to their needs.

rpy2 is offering to customize R’s interactive behavior through callback functions.

Console I/O

During an interactive session, much of the communication between R and the user happen happen through the console. How the console reads input and writes output, can be defined through callback functions.

Read console

The ‘read console’ function is called whenever console input is expected.

The default callback for inputing data is rinterface.consoleRead()

rpy2.rinterface.consoleRead(prompt)

Parameters:prompt – str Return type:str

A suitable callback function will be such as it accepts one parameter of class str, that is the prompt, and returns the user input as a str.

The pair of functions rpy2.rinterface.set_readconsole() and rpy2.rinterface.get_readconsole() can be used to set and retrieve the callback function respectively.

rpy2.rinterface.set_readconsole(f)

set_readconsole(f)

Set how to handle input to R with either None or a function f such as f(prompt) returns the string message to be passed to R

rpy2.rinterface.get_readconsole()

get_readconsole()

Retrieve the current R alert message handler (see set_readconsole)

Return type:a callable

Write console

The ‘write console’ function is called whenever output is sent to the R console.

A suitable callback function will be such as it accepts one parameter of class str and only has side-effects (does not return anything).

The pairs of functions (rpy2.rinterface.set_writeconsole_regular(), rpy2.rinterface.get_writeconsole_regular()) and (rpy2.rinterface.set_writeconsole_warnerror(), rpy2.rinterface.get_writeconsole_warnerror()) can be used to set and retrieve the callback functions.

The default callback function, called rinterface.consolePrint() is a simple write to sys.stdout

rpy2.rinterface.consolePrint(x)

Parameters:x – str Return type:None

An example should make it obvious:

buf = []
def f(x):
    # function that append its argument to the list 'buf'
    buf.append(x)

# output from the R console will now be appended to the list 'buf'
rinterface.set_writeconsole(f)

date = rinterface.baseenv['date']
rprint = rinterface.baseenv['print']
rprint(date())

# the output is in our list (as defined in the function f above)
print(buf)


# restore default function
rinterface.set_writeconsole(rinterface.consolePrint)

rpy2.rinterface.set_writeconsole_regular(f)

set_writeconsole_regular(f)

Set how to handle regular output from the R console with either None or a function f such as f(output) returns None (f only has side effects).

rpy2.rinterface.set_writeconsole_warnerror(f)

set_writeconsole_warnerror(f)

Set how to handle warning or error output from the R console with either None or a function f such as f(output) returns None (f only has side effects).

rpy2.rinterface.get_writeconsole_regular()

get_writeconsole_regular()

Retrieve the current R console output handler (see set_writeconsole_regular)

Return type:a callable

rpy2.rinterface.get_writeconsole_warnerror()

get_writeconsole_warnerror()

Retrieve the current R console output handler for warnings and errors. (see set_writeconsole_warnerror)

Return type:a callable

Flush console

The ‘write console’ function is called whenever output is sent to the R console.

A suitable callback function will be such as it accepts no parameter and only has side-effects (does not return anything).

The pair of functions rpy2.rinterface.set_flushconsole() and rpy2.rinterface.get_flushconsole() can be used to set and retrieve the callback function respectively.

Files

Showing files

Choosing files

File choosing a on basic R console has very little bells and whistles.

def choose_csv(prompt):
    print(prompt)
    return(filename)

Other

Clean up

When asked to terminate, through either its terminal console win32 or quartz GUI front-end, R will perform a cleanup operation at the begining of which whether the user wants to save the workspace or not.

What is happening during that cleaning step can be specified through a callback function that will take three parameters saveact, status, and runlast, return of 1 (save the workspace), 0 (do not save the workspace), and None (cancel the exit/cleanup, raising an RRuntimeError).

import rpy2.rinterface

rpy2.rinterface.initr()

rquit = rpy2.rinterface.baseenv['q']

def cleanup(saveact, status, runlast):
    # cancel all attempts to quit R programmatically
    print("One can't escape...")
    return None

>>>  orig_cleanup = rpy2.rinterface.get_cleanup()
>>>  rpy2.rinterface.set_cleanup(cleanup)
>>> rquit()

Restore the original cleanup:

>>> rpy2.rinterface.set_cleanup(orig_cleanup)