example of creating extensions?

22 views
Skip to first unread message

per.n...@gmail.com

unread,
Dec 17, 2018, 10:07:50 AM12/17/18
to Renjin
Hi,

The documentation for writing extensions is very nice. However I find it hard to grasp the details of creating extensions. Would it be possible to add a very simple, but complete, extension example to the docs?

1. Lets say I wanted to create a meanTrim function that takes a vector as argument and trims off the min and max values first. i.e.

meanTrim <- function(x) {
  x <- x[x != max(x)]
  x <- x[x != min(x)]
  return(mean(x))
}

# Example:
vec <- c(2.3, 2.7, 3.1, 4.9, 1.0, 2.4, 2.6, 2.1, 2.0, 1.9)
print(mean(vec))
print(meanTrim(vec))


2. A more involved example would be something where I have a java class that does something useful and i want to take advantage of that in an  R function

e.g. i have the Java class
public class StringTransformer {
  
  /** strips off any non numeric char from the string. */
  public static String toNumber(String txt) {
    StringBuilder result = new StringBuilder();
    txt.chars().mapToObj( i -> (char)i )
    .filter( c -> Character.isDigit(c) ).forEach( c -> result.append(c) );
    return result.toString();
  }
  
}  

and I want to make a library which has a function called makeNumeric which uses the StringTransformer.toNumber() functionality.

3. Lets say i want to override (mask) existing functionality .e.g i want to override library() with something that guesses the correct package so i can do e.g. library("dplyr") and get the same thing as if I would have written library("org.renjin.cran:dplyr"), what do i need to do to make that happen?

If you answer here, I'd be happy to type up a tutorial and submit a patch suggestion to the docs.

Best regards,
Per

Solaimani, Parham

unread,
Dec 17, 2018, 6:56:34 PM12/17/18
to renji...@googlegroups.com
Hi Per,

You refer to documentation part about writing Renjin extensions. 

<1>
  • create files src/main/R/meantrim.R and src/test/R/test.meantrim.R
    • in meanTrim.R write your function:
      meanTrim <- function(x) {
    • x <- x[x != max(x)]
      x <- x[x != min(x)]
    • mean(x)
      }
    • in test.meantrim.R write your tests using Renjins hamcrest package:
      library("com.mydomain:meantrim")
      library("hamcrest")
      assertThat(meanTrim(1:10), identicalTo(5.5))
  • create the NAMESPACE file and export your function
    export(meanTrim)
  • copy the example po.xml and change the groupId and artefactId to "com.mydomain" and "meantrim", respectively.
  • your extension/package folder should now look like this:
    pom.xml
    NAMESPACE
    src
    |-- main
    |    |-- R
    |        |- meantrim.R
    |-- test
         |-- R
             |- test.meantrim.R  
  • now you can do "mvn test" to test your package and "mvn package" to create the fat binary jar file from your package which will be stored in your "target" folder
  • you can now import this package in your Renjin session and use it

<2> following the documentation about importing java classes: http://docs.renjin.org/en/latest/importing-java-classes-in-r-code.html
  • create src/main/java/
    • create StringTransformer.java:
      package transformers;
      public class StringTransformer {

    •   public static String toNumber(String txt) {
          StringBuilder result = new StringBuilder();
          txt.chars().mapToObj(i -> (char) i)
            .filter(c -> Character.isDigit(c))
            .forEach(c -> result.append(c));
          return result.toString();
        }
      }

  • add extractDigits function (to your meantrim.R file):
    • extractDigits <- function(x) {
          import(transformers.StringTransformer)
          sapply(x, function(txt) StringTransformer$toNumber(txt = txt), USE.NAMES = FALSE)
      }
      makeNumber <- function(x) as.numeric(extractDigits(x))
    • add test case to test.meantrim.R file:
      assertThat(extractDigits(c("5", "6Y8", "He", "02")), identicalTo(c("5", "68", "", "02")))
      assertThat(makeNumber(c("5", "6Y8", "He", "02")), identicalTo(c(5, 68, NA, 2)))
  • export the new functions in your NAMESPACE and use mvn to test and package your extension
<3> depending on whether you want to do this inside your package or java application, you need to have a list of CRAN and BioConductor package names and depending in which list the input name resides add to correct prefix to the input and pass that to base::library()

If you want to do it in your application follow the instructions here: http://docs.renjin.org/en/latest/library/evaluating.html

Kind regards,
Parham

--
You received this message because you are subscribed to the Google Groups "Renjin" group.
To unsubscribe from this group and stop receiving emails from it, send an email to renjin-dev+...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.


--
Parham Solaimani, PhD
Bioinformatics Scientist
BeDataDriven B.V.
Binckhorstlaan 36
2516 BE, The Hague, The Netherlands
T: +31 (0) 70 221 14 84
SkypeID: psolaimani

Per Nyfelt

unread,
Dec 18, 2018, 3:28:15 AM12/18/18
to Renjin
Wonderful! Perfect answer, thank you so much!

I'll type something up and submit this as a suggestion to add to the docs.

Best regards,
Per

Kallen, Maarten-Jan

unread,
Dec 18, 2018, 4:07:08 AM12/18/18
to renji...@googlegroups.com
Thanks Parham!

The answer is *almost* perfect, because the JAR file created with mvn package is not actually a fat JAR.

Maarten-Jan


Per Nyfelt

unread,
Dec 18, 2018, 9:04:00 AM12/18/18
to Renjin
Hi,

I've tried to implement as per your suggestion. The code is here https://github.com/perNyfelt/renjinextensionsdemo

Unfortunately i get an NPE which I cannot figure out: Failed to execute goal org.renjin:renjin-maven-plugin:0.9.2716:test (test) on project meantrim: Execution test of goal org.renjin:renjin-maven-plugin:0.9.2716:test failed. NullPointerException -> [Help 1]

I think this is because in the test i use e.g.
library("se.alipsa:meantrim")

and in the pom i have set 
<parent>
<artifactId>renjin-extensions-demo</artifactId>
<groupId>se.alipsa</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>

<artifactId>meantrim</artifactId>
<packaging>jar</packaging>

The DESCRIPTION file in target/classes/se/alipsa/meantrim/ contains
Package: meantrim
GroupId: se.alipsa

So that seems to be OK. However i suspect that there is some wiring that I did not do correctly and hence the NPE since the stacktrace from mvn -e test never touches my code but throws it at org.renjin.maven.test.TestReporter.testCaseFailed (TestReporter.java:129)

Any suggestions?

Best regards,
Per

Parham Solaimani

unread,
Dec 20, 2018, 5:31:35 AM12/20/18
to Renjin
Hi Per,

In your meantrim test case your are calling meanTrim while you have defined and exported meantrim

Best,
Parham

Per Nyfelt

unread,
Dec 20, 2018, 7:56:59 AM12/20/18
to Renjin
Indeed is was, stupid mistake. It is working now, thank you! I will submit a suggestion to the docs within the next few days.

Best regards,
Per
Reply all
Reply to author
Forward
0 new messages