Subsections


R

References [#!multir!#,#!growl2!#,#!sage!#,#!NCeSS2006!#].

MultiR [#!multir!#] and SabreR [#!NCeSS2005!#,#!NCeSS2006!#] were developed by Dan Grose based on GROWL but written in the R language [#!R!#,#!R-intro!#,#!R-lang!#,#!R-admin!#,#!R-exts!#,#!GROWL-r!#]. They have been applied to longitudinal statistical analysis [#!sage!#], bio-informatics [#!poster:microarray!#] and geography.

Summary

This packge contains functions for remote access to statistical analysis packages and so forth, normally provided through the R fuctional language interface. Note that the remote methods are most likely to be written in another language such as C or Fortran and GROWL is used as an intermediary in a Web service interface. A set of R wrappers and test codes are provided to these and other GROWL functions.

Note that this chapter describes both the R-specific services provided via GROWL and also and introduction to the generic R wrappers to all GROWL functions which are further described separately [#!GROWL-r!#].

Attributes

Version: 1.0
Public calls: growl_testR growl_rCommand
Public modules: libgrowl.a
Other modules required: libbase.a, gSOAP v2.1.4, R v1.8.1
Date: 2004
Origin: Hand-Knitted Software, R.J. Allan, CCLRC Daresbury Laboratory
Language: C
Conditions on external use: Standard, see separate chapter
Workspace: internal workspace is allocated in all these routines by the gSOAP system for the long return string. This should be freed by the user when it is no longer required.
Use of globals: none
Other routines called directly: none
Input/ output: none
Restrictions:
Notes:

How to use the Package

This module is used by including growl.h and linking to the library libgrowl.a. Publically callable procedures are listed here. We first explain the procedures for creating and using R interfaces (wrappers) to GROWL client-side Web services.

R Wrappers to GROWL C Functions

We will use an example to illustrate the procedures followed. More information is available from the extensive developer and user documentation for the Gnu R Project. It illustrates the use of C macros to convert between R and C data objects.

Note that there are multiple function calls here which is inefficient. At some future date we might provide a native R interface to the services accessed through GROWL and thus obviate the need for these wrappers.

User-side C Client and Macros

This is an example C client which wraps a call to the GROWL function growl_rCommand(). The use of macros is explained in Reference [#!R-exts!#].

[frame=single]
#include <R.h>
#include <Rdefines.h>

SEXP rCommandWrapper(SEXP Rcommand, SEXP Rinput1, SEXP Rinput2) {
  SEXP Rresult;
  const char *command;
  const char *input1;
  const char *input2;
  char *result;
  int res;

  PROTECT(Rcommand = AS_CHARACTER(Rcommand));
  command = CHAR(STRING_ELT(Rcommand, 0));
  PROTECT(Rinput1 = AS_CHARACTER(Rinput1));
  input1 = CHAR(STRING_ELT(Rinput1, 0));
  PROTECT(Rinput2 = AS_CHARACTER(Rinput2));
  input2 = CHAR(STRING_ELT(Rinput2, 0));
  res = growl_rCommand(command, input1, input2, &result);
  if(res == 0) {
    printf("length of result = %d\n", strlen(result));
  } else
    printf("WS call failed\n");

  PROTECT(Rresult = NEW_CHARACTER(1));
  SET_STRING_ELT(Rresult, 0, mkChar(result));
   
  UNPROTECT(4);
  free(result);
  return(Rresult);
}

R Function Prototype

The above wrapper is invoked from an R session using the following function prototype.

[frame=single]
rCommand <- function(a, b, c)
  .Call("rCommandWrapper", a, b, c)

Automatic Wrapper Generation

In the present implementation, C wrappers and R prototypes can be generated in a semi-automatic way from the GROWL header file function definition, e.g. the one in growl_r.h. The following Perl script illustrates how this might be done. The actual fuction definition is input as an argument. Note that this is currently a research issue.

[frame=single]
#!/usr/bin/perl -w

$function = $ARGV[0];
$ni = @ARGV - 2;

# generate R prototype
$fname = $function . '.R';
open(RAPPER, ">$fname");
$args = '';
for ($i=1; $i<$ni; ++$i) {
    $args .= "$i, "; 
}
$args .= "$ni";
$line = $function . " <- function($args)";
print RAPPER "$line\n";
$line = "     .Call(\"" . $function . "Wrapper\", $args)";
print RAPPER "$line\n";
close(RAPPER);

# generate C wrapper
$fname = $function . 'Wrapper.c';
open(CRAPPER, ">$fname");

print CRAPPER << EOF;
#include <R.h>
#include <Rdefines.h>
EOF;

$line = 'SEXP ' . $function . '(';
for ($i=1; $i<$ni; ++$i) {
    $line .= 'SEXP Rinput' . $i . ', ';
}
    $line .= 'SEXP Rinput' . $ni . ') {';
print CRAPPER "$line\n";

print CRAPPER "// parameters\n";
$line = "   SEXP Rresult;\n";
for ($i=1; $i<=$ni; ++$i) {
    $line .= "   const char *input$i;\n";
}
$line .= "   char *result;\n";
$line .= "   int res;\n";
print CRAPPER "$line\n";

print CRAPPER "//mapping objects\n";
$line = "";
for ($i=1; $i<=$ni; ++$i) {
    $line .= "   PROTECT(Rinput$i = AS_CHARACTER(Rinput$i));\n";
    $line .= "   input$i = CHAR(STRING_ELT(Rinput$i, 0));\n";
}
print CRAPPER "$line\n";

print CRAPPER "// call remote function \n";
$line = "   res = testR(";
for ($i=1; $i<=$ni; ++$i) {
    $line .= "input$i, ";
}
$line .= "&result);\n";
print CRAPPER "$line\n";

print CRAPPER "// test for error returns\n";
print CRAPPER <<EOF;
   if(res == 0) {
      printf("length of result = %d\\n", strlen(result));
   } else
      printf("WS call failed\\n");

   PROTECT(Rresult = NEW_CHARACTER(1));
   SET_STRING_ELT(Rresult, 0, mkChar(result));
   
EOF;

print CRAPPER "   UNPROTECT($ni);\n";
print CRAPPER <<EOF;
   free(result);
   return(Rresult);
}
EOF;

close(CRAPPER);

Specification of R Module

Specification of growl_rcommand

[frame=single]
     int growl_rCommand(char *command,
                        char *input1,
			char *input2,
			char **result);

Argument List

char *command
On entry: a string made up of R script to be interpreted on the remote R server.

char *input1
On entry: input string (tbd).

char *input2
On entry: input string (tbd).

char **result
On exit: response from R server.

Information returned to the User

Integer, 0=success, !0=failure.

Errors and Warnings

Error Returns

SOAP error message if there is a problem.

Example

Typically routines in this module would be wrapped and used from the R functional language. This is the GROWL R interface, and information on this procedure is given separately. The example below shows screen output during a sample of an R session.

Example R session

[frame=single]
$ R

R : Copyright 2003, The R Foundation for Statistical Computing
Version 1.8.1  (2003-11-21), ISBN 3-900051-00-3

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for a HTML browser interface to help.
Type 'q()' to quit R.

>library(GROWL)
>restore.session(file='Rsession')
Loading all data...
Loading packages...
Restoring search path...
Done.
>grid.login()
...
> string='ls()'
> rCommand(string,'a','b')
...

Rob Allan 2009-11-10