galaaz 0.5.0 → 2.1.0

data/blogs/oh_my/oh_my.Rmd

@@ -3,8 +3,8 @@ title: "Extending R with classes, modules, procs, lambdas, oh my!"
 author:
     - "Rodrigo Botafogo"
     - "Daniel Mossé - University of Pittsburgh"
-tags: [Tech, Data Science, Ruby, R, GraalVM]
-date: "November 19th, 2018"
+tags: [Tech, Data Science, Ruby, R, JRuby, "GNU R", Galaaz]
+date: "November 19th, 2018 (narrative updated for Galaaz 2.0, 2026)"
 output:
   html_document:
     self_contained: true
@@ -25,17 +25,19 @@ fontsize: 11pt
 
 # Introduction
 
-This paper introduces and compares Galaaz with R's S4.  It is a shameless rip off of 
+This paper introduces and compares Galaaz with R's S4.  It is **modeled closely** on
 ["A '(not so)' Short Introduction to S4"](https://cran.r-project.org/doc/contrib/Genolini-S4tutorialV0-5en.pdf) by Christophe Genolini and follows the same structure and examples presented there.
 
 Galaaz is a Ruby Gem (library) that allows very tight integration between Ruby and R.  
-It's integration is much tigher and transparent from what one can get beetween RinRuby
-or similar solutions in Python
+Its integration is tighter and more transparent than what one can get between RinRuby
+or similar solutions in Python,
 such as [PypeR](https://pypi.python.org/pypi/PypeR/1.1.0), [rpy2](http://rpy2.bitbucket.org/)
-and  other similar solutions.  Galaaz targets the GraalVM and it
-integrates with FastR, a high performance R interpreter for the GraalVM.  
+and other similar solutions.
 
-GraalVM:
+**Galaaz 2.0** runs on **[JRuby](https://www.jruby.org/)** and drives **GNU R** through a **bridge**,
+so Ruby code can create and manipulate R objects and call R functions while staying idiomatic Ruby.
+An earlier prototype used Oracle’s **GraalVM** with **TruffleRuby** and **FastR**; that stack is
+historical and is **not** what current Galaaz targets.
 
 
 # Bases of Object Programming
@@ -70,7 +72,7 @@ type information is also not a "compile" time type, since R is not compiled.  Th
 checked at runtime.  The same checking can be done in Ruby and we will do it later in this 
 document.
 
-In the example bellow, we create 
+In the example below, we create 
 class Trajectories with two instance variables, 'times' and 'matrix'.  We will not go over 
 the details of instance variables in Ruby, but here we created those variables with the 
 keyword 'attr_reader' and a colom before the variables name:
@@ -85,7 +87,7 @@ end
 
 
 In order to create a new instance of object Trajectories we call method new on the class and
-we can store the result in a varible (not an instance variable) as bellow:
+we can store the result in a variable (not an instance variable) as below:
 
 ```{ruby traj_variable}
 @traj = Trajectories.new
@@ -109,7 +111,7 @@ puts @traj.times
 Since there is no content stored in 'times' nor 'matrix', nil is returned.  In order to add
 a value in the variables, we need to add a constructor to the class Trajectories.  In R, a 
 constructor is build by default, in Ruby, this has to be created by adding a method called
-'initialize'.  In the example bellow, we will create the initializer that accepts two values,
+'initialize'.  In the example below, we will create the initializer that accepts two values,
 a 'times' value and a 'matrix' value and they are used to initialize the value of the 
 instance variables:
 
@@ -144,7 +146,7 @@ i.e., R functions are all defined in Galaaz in the R namespace.
 Since Galaaz is Ruby and not R, some syntax adjustments are sometimes necessary.  For instance,
 in R, a range is represented as '(1:4)', in Ruby, the same range is represented as '(1..4)'. 
 When passing arguments to an R function in R one uses the '=' sign after the slot name; in R,
-one uses the ':' operator after parameter's name as we can see bellow:
+one uses the ':' operator after parameter's name as we can see below:
 
 ```{ruby initializing_trajectories}
 # Create a Trajectories passing a times vector, but no matrix parameter
@@ -245,7 +247,7 @@ recommend its use, there are many cases in which default values are useful and m
 We have already seen default values in this document, with the default being 'nil'.  This was
 necessary in order to be able to create our constructor and passing it the proper values.
 
-In the example bellow, a class TrajectoriesBis is created with default value 1 for times and a 
+In the example below, a class TrajectoriesBis is created with default value 1 for times and a 
 matrix with no elements in matrix.
 
 ```{ruby}
@@ -339,7 +341,7 @@ Trajectories to add methods to it.  In SS4, a method 'plot' is added to Trajecto
 point, Renjin and Galaaz do not yet have plotting capabilities, so we will have to skip this 
 method and go directly to the implementation of the 'print' method.
 
-Bellow is the R code for method print:
+Below is the R code for method print:
 
 ```
 > setMethod ("print","Trajectories",
@@ -434,25 +436,24 @@ features of Galaaz, some we have already seen, others will be described now:
   function look like a method of the object.  For instance, R.nrow(@matrix), can be called by
   doing @matrix.nrow;
 
-* In R, every number is converted to a vector and this can be done with method R.i.  Converting
-  a vector with only one number back to a number can be done with method '.gz'.  So if @num is
-  an R vector that holds a number, then @num.gz is a number that can be used normally with Ruby
-  methods;
+* In R, every number is a length-1 vector.  In Galaaz 2.0, unwrap a length-1 R vector
+  to a Ruby number with `>> 0` (or `unboxed_get(0)`).  Older Galaaz docs used `.gz` /
+  `<< 0` for the same idea; `<<` still works as a compatibility alias for `>>`;
 
-* R functions and Ruby methods can be used freely in Galaaz.  We show bellow two different ways
+* R functions and Ruby methods can be used freely in Galaaz.  We show below two different ways
   of getting the minimum of a number, either by calling R.min or by getting the minimum of an 
   array, with the min method;
 
 * Galaaz allows for method 'chaining'. Method chaining, also known as named parameter idiom, is 
   a common syntax for invoking multiple method calls in object-oriented programming languages. 
   Each method returns an object, allowing the calls to be chained together in a single statement 
-  without requiring variables to store the intermediate results.  For instance @matrix.nrow.gz, 
-  which returns the number of rows of the matrix as a number;
+  without requiring variables to store the intermediate results.  For instance `@matrix.nrow >> 0`, 
+  which returns the number of rows of the matrix as a Ruby number;
 
 * Ranges in Ruby are represented by (x..y), where x is the beginning of the range and y its end.
   An R matrix can be indexed by range, object@traj[1:nrowShow,1:ncolShow], the same result is 
   obtained in Galaaz by indexing @matrix[(1..nrow_show), (1..ncol_show)].  Observe that this
-  statement is then chained with the format function and with the pp method to print the matrix.
+  statement is then chained with the format function and printed with `puts`.
 
 
 ```{ruby}
@@ -466,8 +467,8 @@ class Trajectories
     puts("*** Class Trajectories, method Show *** ")
     Kernel.print("times = ")
     puts @times
-    nrow_show = [10, @matrix.nrow << 0].min
-    ncol_show = R.min(10, @matrix.ncol) << 0
+    nrow_show = [10, @matrix.nrow >> 0].min
+    ncol_show = R.min(10, @matrix.ncol) >> 0
     puts("* Traj (limited to a matrix 10x10) = ")
     puts @matrix[(1..nrow_show), (1..ncol_show)].format(digits: 2, nsmall: 2)
     puts("******* End Show (trajectories) ******* ")
@@ -487,7 +488,1215 @@ we try to 'show' it, it will generate an error.  Let's see it:
 @empty_traj = Trajectories.new
 ```
 
-```{ruby eval_error, warning = FALSE}
+```{ruby eval_error_1, warning = FALSE}
 @empty_traj.show
 ```
 
+In this example, `@matrix` is `nil`, so calling `@matrix.nrow` raises
+`undefined method 'nrow' for nil`.  To fix this, we can either prevent an empty
+trajectories class from being created, or make sure that method `show` will not
+choke on the empty object.  We will take the second alternative, to follow SS4,
+and will check if either `@times` or `@matrix` is empty.  If either one of them
+is `nil`, then we will print a message saying so.
+
+Although the first alternative, i.e., not allow for empty objects is a possibility in Ruby,
+it seems that this is not the case for S4.
+
+```{ruby}
+class Trajectories
+
+  def show
+    if (@times.nil? || @matrix.nil?)
+      puts("*** Class Trajectories is empty!! *** ")
+      return
+    end
+    puts("*** Class Trajectories, method Show *** ")
+    Kernel.print("times = ")
+    puts @times
+    nrow_show = [10, @matrix.nrow >> 0].min
+    ncol_show = R.min(10, @matrix.ncol) >> 0
+    puts("* Traj (limited to a matrix 10x10) = ")
+    puts @matrix[(1..nrow_show), (1..ncol_show)].format(digits: 2, nsmall: 2)
+    puts("******* End Show (trajectories) ******* ")
+  end
+
+end
+```
+
+```{ruby}
+@empty_traj.show
+```
+
+
+# To Remove an Object
+
+As far as I know, there isn't a good way of removing a defined class, but there might be
+one and the interested user is directed to google it!  In principle, there should not be
+any real need to remove a defined class.  Both in R and Galaaz, large programs are usually
+written in a file and the file loaded.  If one writes a wrong class, the better solution is
+to correct it and then load it again.  If the class is written directly on the console,
+then leaving it there will not have any serious impact.
+
+# Method count_missing
+
+In R, methods 'print' and 'show' are methods that already exist.  SS4 wants to add a method
+called 'countMissing' which does not exist in R, and thus requires some special preparation. In
+Ruby, every method we've created is a new method that exists inside the class.  The fact that
+'print' happens to be also a method for class Kernel and 'show' is not, is not of special interest.
+Actually we've seen that in order to call method print from the Kernel class we had to call
+Kernel.print.
+
+To create method 'count_missing' we just need to reopen the Trajectories class and add the
+method the same way we've done with method 'show'. Again, let's first look at R's 'countMissing'
+and then at Ruby's:
+
+
+```
+> setMethod(
++ f= "countMissing",
++ signature= "Trajectories",
++ definition=function(object){
++ return(sum(is.na(object@traj)))
++ }
++ )
+```
+
+Here we introduce another particular case of Galaaz.  R has many methods that have a '.' in
+their names, such as 'is.na'.  In Ruby, the dot '.' has a special meaning as it is the way
+we call a method on an object.  Doing 'R.is.na' will not work.  So, in Galaaz, R functions that
+have a dot in them will have the dot substituted by '__'.  So, method is.na in Galaaz, becomes
+R.is__na.  In method count_missing we use method chaining and convert the final count to a
+Ruby number with `>> 0` (unbox).
+
+```{ruby}
+class Trajectories
+
+  def count_missing
+    return @matrix.is__na.sum >> 0
+  end
+
+end
+```
+
+```{ruby}
+puts @trajCochin.count_missing
+```
+
+# To See the Methods
+
+In order to see the methods we have defined so far, we call on class Trajectories the method
+'instance_methods' passing it one argument, 'false', as follows:
+
+```{ruby}
+puts Trajectories.instance_methods(false)
+```
+
+It is interesting to observe that we see our three methods 'count_missing', 'print' and 'show', but
+we also see two other methods 'times' and 'matrix', but those last two as far as we know are
+just instance variables and not methods, right? More on that when we talk about Accessors.
+
+Galaaz and Ruby do not by default provide a way to see a method's code.  However, if the user uses
+a Ruby console such as Pry, then seeing methods and debugging is possible.  Pry is beyond the
+scope of this document.
+
+# Construction
+
+Every class in Ruby has a constructor, if not explicitly defined, at least implicitly.  Method
+initialize is the constructor method and the one that coordinates the whole construction process.
+
+# Inspector
+
+There is no default 'inspector' in Ruby as in R, although there is nothing that prevents the
+developer from inspecting and validating the input. For example, in the object Trajectories, one may
+want to check that the number of elements in 'times' is equal to the number of columns in 'matrix'
+and if they are not, issue an error.  In order to understand why this restriction exists, the user is
+again directed to SS4.
+
+Here we show the R code for this validation:
+
+```
+> setClass(
++ Class="Trajectories",
++ representation(times="numeric",traj="matrix"),
++ validity=function(object){
++ cat("~~~ Trajectories: inspector ~~~ \\n")
++ if(length(object@times)!=ncol(object@traj)){
++ stop ("[Trajectories: validation] the number of temporal measurements does not correspond
++ }else{}
++ return(TRUE)
++ }
++ )
+```
+
+In order to implement this validation we will coordinate it in the initialize method.
+
+```{ruby}
+class Trajectories
+
+  def initialize(times: nil, matrix: nil)
+    @times = times
+    @matrix = matrix
+
+    # validate the input, to make sure that size of @times and the number of columns in
+    # @matrix are the same
+    puts ("~~~ Trajectories: inspector ~~~ ")
+    raise "[Trajectories: validation] the number of temporal measurements does not correspond with the number of columns in the matrix" if ((@times.length >> 0) != (@matrix.ncol >> 0))
+
+    # show the object just created
+    show
+
+  end
+
+end
+```
+
+Let's first create a Trajectories that validates fine, i.e., the number of elements in @times is
+equal to the number of columns of the matrix.  In this case, we will show a message saying that
+validation was done and then print the object.
+
+```{ruby}
+ok = Trajectories.new(times: R.c(1..2), matrix: R.matrix((1..2), ncol: 2))
+```
+
+Now, if we try to create a Trajectories that does not pass the validation criteria, our code
+will raise an exception.  Exceptions are a standard way to deal with errors in Ruby code and
+many other object oriented languages.  The interested reader should look for further documentation
+on exceptions on the web.
+
+
+```{ruby eval_error_2, warning = FALSE}
+error = Trajectories.new(times: R.c(1..3), matrix: R.matrix((1..2), ncol: 2))
+```
+
+The validation above does not consider the case when an empty object is created.  Here we will
+check to see if either times or matrix are nil; if either one of them is nil, then we will raise
+an exception and interrupt the creation of the object.  We also create a method validate that is
+called from our initialize method.
+
+Method validate has some interesting features about the integration of Galaaz and R.  We compare
+lengths after unboxing with `>> 0`, so the comparison is ordinary Ruby arithmetic on numbers.
+(A length-1 R logical can likewise be treated as a Ruby boolean via `>> 0`.)
+
+
+```{ruby}
+class Trajectories
+
+  def initialize(times: nil, matrix: nil)
+    @times = times
+    @matrix = matrix
+
+    # call method validate to validate our input
+    validate
+
+    # show the object just created
+    show
+
+  end
+
+  def validate
+
+    # Let's first check that we do not have an empty object
+    raise "Neither times nor matrix can be an empty object" if (@times.nil? || @matrix.nil?)
+
+    # validate the input, to make sure that size of @times and the number of columns in
+    # @matrix are the same
+    puts ("~~~ Trajectories: inspector ~~~ ")
+    raise "[Trajectories: validation] the number of temporal measurements does not correspond with the number of columns in the matrix" if ((@times.length >> 0) != (@matrix.ncol >> 0))
+
+  end
+
+end
+```
+
+**Note:** with this stricter `validate`, `Trajectories.new` no longer accepts empty objects.
+The earlier `@empty_traj = Trajectories.new` / `@empty_traj.show` pattern from part 1 no longer
+applies for *new* constructions; existing instances created before this reopen still exist in
+memory, but calling `new` with missing `times` or `matrix` will raise.
+
+Let's try then creating an empty object:
+
+
+```{ruby eval_error_3, warning = FALSE}
+error = Trajectories.new
+```
+
+Another example:
+
+```{ruby eval_error_4, warning = FALSE}
+error = Trajectories.new(times: 1)
+```
+
+Let's see now that the implementation is correct and that it does not raise an error on valid
+input:
+
+```{ruby}
+ok = Trajectories.new(times: R.c(1, 2), matrix: R.matrix((1..2), ncol: 2))
+```
+
+The 'initialize' method is called ONLY during the initial creation of the object. If any instance
+variable is later modified, no control is done. At this moment though, there is no way to change
+the value of any of our instance variables.
+
+```
+error.times = R.c(1, 2, 3)
+```
+
+The Trajectories class works for R objects and expects as input R objects.  Passing R objects in
+all examples has been the obligation of the programmer.  Galaaz, however, can also accept many
+Ruby values (ranges, arrays of numbers, and so on) if we convert them at the boundary.  There is
+no `R.convert` in Galaaz 2.0; a small helper is enough: leave `nil` alone, keep objects that are
+already `R::Object`, and otherwise wrap with `R.c` (which accepts ranges as well as scalars and
+vectors).  Matrices that are already R objects are kept as-is.
+
+```{ruby}
+class Trajectories
+
+  def as_r(x)
+    return nil if x.nil?
+    return x if x.is_a?(R::Object)
+    R.c(x)
+  end
+
+  def initialize(times: nil, matrix: nil)
+    @times = as_r(times)
+    @matrix = as_r(matrix)
+
+    # call method validate to validate our input
+    validate
+
+    # show the object just created
+    show
+
+  end
+
+  def validate
+
+    # Let's first check that we do not have an empty object
+    raise "Neither times nor matrix can be an empty object" if (@times.nil? || @matrix.nil?)
+
+    # validate the input, to make sure that size of @times and the number of columns in
+    # @matrix are the same
+    puts ("~~~ Trajectories: inspector ~~~ ")
+    tl = @times.length >> 0; mc = @matrix.ncol >> 0
+    raise "[Trajectories: validation] the number of temporal measurements #{tl} does not correspond with the number of columns in the matrix #{mc}" if (tl != mc)
+
+  end
+
+end
+```
+
+And now let's create a new Trajectories, but we will now pass a Ruby range for times:
+
+```{ruby}
+ok = Trajectories.new(times: (1..2), matrix: R.matrix((1..2), ncol: 2))
+```
+
+Perfect! This works fine.
+
+*(Historical note: an earlier Galaaz prototype on Renjin also demonstrated sharing storage with
+the MDArray gem. Those shared-store demos are not part of Galaaz 2.0 / the GNU R bridge, and are
+omitted here.)*
+
+# The Initializator
+
+As we have seen, method 'initialize' is the main object creator orchestrator.  This method can be
+as complex as needed.  So, let's get on with some improvements to our Trajectories class.
+
+It would be rather pleasant that the columns of the matrix of the trajectories have names, the
+names of measurements times. In the same way, the lines could be subscripted by a number of
+individual.
+
+To do this in R, one also uses method initialize:
+
+
+```
+> setMethod(
++ f="initialize",
++ signature="Trajectories",
++ definition=function(.Object,times,traj){
++ cat("~~~ Trajectories: initializator ~~~ \\n")
++ colnames(traj) <- paste("T",times,sep="")
++ rownames(traj) <- paste("I",1:nrow(traj),sep= "")
++ .Object@traj <- traj # Assignment of the slots
++ .Object@times <- times
++ return(.Object) # return of the object
++ }
++ )
+```
+
+In R, it is possible to assign a value to the result of a function, for example
+`colnames(x) <- c("v1", "v2", "v3")`.  In Galaaz 2.0 the same idea is expressed with ordinary
+Ruby setters on the R object: `@matrix.colnames = ...` and `@matrix.rownames = ...`.
+
+```{ruby}
+class Trajectories
+
+  def as_r(x)
+    return nil if x.nil?
+    return x if x.is_a?(R::Object)
+    R.c(x)
+  end
+
+  def initialize(times: nil, matrix: nil)
+    @times = as_r(times)
+    @matrix = as_r(matrix)
+
+    # call method validate to validate our input
+    validate
+
+    # Add row and column names
+    puts ("~~~ Trajectories: initializator ~~~ ")
+    @matrix.colnames = R.paste("T", @times, sep: "")
+    @matrix.rownames = R.paste("I", (1..(@matrix.nrow >> 0)), sep: "")
+
+    # show the object just created
+    show
+
+  end
+
+end
+```
+
+```{ruby}
+@traj = Trajectories.new(times: R.c(1,2,4,8), matrix: R.matrix((1..8), nrow: 2))
+```
+
+Note that we still call our 'validate' method and it is still an error to create an empty
+Trajectories or one in which the sizes are wrong:
+
+```{ruby eval_error_5, warning = FALSE}
+error = Trajectories.new(times: R.c(1, 2, 48), matrix: R.matrix((1..8), nrow: 2))
+```
+
+A constructor does not necessarily take the instance variable of the object as argument. For
+example, if we know (that is not the case in reality, but let us imagine so) that the
+BMI increases by 0.1 every week, we could build trajectories by providing the number
+of weeks and the initial weights.
+
+First the code in R, we skip the definition of class TrajectoriesBis:
+
+
+```
+> setMethod ("initialize",
++ "TrajectoriesBis",
++ function(.Object,nbWeek,BMIinit){
++ traj <- outer(BMIinit,1:nbWeek,function(init,week){return(init+0.1*week)})
++ colnames(traj) <- paste("T",1:nbWeek,sep="")
++ rownames(traj) <- paste("I",1:nrow(traj),sep="")
++ .Object@times <- 1:nbWeek
++ .Object@traj <- traj
++ return(.Object)
++ }
++ )
+```
+
+Now, let's make a TrajectoriesBis in Galaaz.  Here again, we should point out some characteristics
+of our code:
+
+* We made initialize with two positional arguments, instead of named arguments, i.e.,
+  the first argument is the number of weeks and the second bmi_init.  In this case,
+  when making a new object the position of the arguments is important and there is no
+  way to pass the argument by name;
+
+* R function outer was called as if a method from bmi_init using dot notation, although
+  one could use R.outer without problem;
+
+* Function 'outer' expects an R function as its 3rd argument.  In order to build an R
+  function from Galaaz, we need to pass the function definition as a string to R.eval.
+
+```{ruby}
+class TrajectoriesBis
+
+  attr_reader :times
+  attr_reader :matrix
+
+  def initialize(number_weeks, bmi_init)
+    @matrix = bmi_init.outer((1..number_weeks),
+                             R.eval("function(init, week) {return(init + 0.1 * week)}"))
+    @times = R.c((1..number_weeks))
+  end
+
+end
+
+@traj_bis = TrajectoriesBis.new(4, R.c(16,17,15.6))
+```
+
+```{ruby}
+puts @traj_bis.matrix
+```
+
+It is always possible to pass a Ruby variable into a string by interpolating it.  Put the
+variable inside `#{...}`.  As an example, let's also require the BMI increase as a parameter.
+(A common mistake is to escape the interpolation — writing `\#{increment}` — which leaves the
+characters literally in the R source and does not substitute the Ruby value.  Use real
+interpolation:)
+
+```{ruby}
+class TrajectoriesBis
+
+  def initialize(number_weeks, bmi_init, increment)
+    @matrix = bmi_init.outer((1..number_weeks),
+                             R.eval("function(init, week) {return(init + #{increment} * week)}"))
+    @times = R.c((1..number_weeks))
+  end
+
+end
+
+@traj_bis = TrajectoriesBis.new(4, R.c(16,17,15.6), 0.3)
+```
+
+```{ruby}
+puts @traj_bis.matrix
+```
+
+# Constructors for Users
+
+Many times, it is interesting to have different ways of constructing an object depending on
+what information our users have or want to provide to the constructor.  Although we have only one
+initialize method, we can create multiple methods, that do some preprocessing and then call the
+initialize method to carry out the object building.
+
+In order to do that, we use what are called class methods, instead of instance methods.  All the
+methods we've created so far are instance methods; class methods are defined by prepending the
+self keyword to the method's name.  Still using the assumption that the BMI will grow by 0.1 per
+week, let's define a regular trajectory without having to define a TrajectoriesBis as above:
+
+
+```
+> regularTrajectories <- function(nbWeek,BMIinit) {
++ traj <- outer(BMIinit,1:nbWeek,function(init,week){return(init+0.1*week)})
++ times <- 1: nbWeek
++ return(new(Class="Trajectories",times=times,traj=traj))
++ }
+> regularTrajectories(nbWeek=3,BMIinit=c(14,15,16))
+```
+
+Notice how method 'regular' is defined as 'self.regular', making it a class method.  The last
+statement of the method definition is actually a call to the Trajectories constructor 'new' passing
+the calculated values for times and matrix.
+
+Notice also how method regular is called, similar to the way new is called by adding it after class
+Trajectories name: 'Trajectories.regular'.
+
+```{ruby}
+class Trajectories
+
+  def self.regular(number_weeks: nil, bmi_init: nil)
+    matrix = bmi_init.outer((1..number_weeks),
+                            R.eval("function(init, week) {return(init + 0.1 * week)}"))
+    times = R.c((1..number_weeks))
+    Trajectories.new(times: times, matrix: matrix)
+  end
+
+end
+```
+
+```{ruby}
+@regular = Trajectories.regular(bmi_init: R.c(14, 15, 16), number_weeks: 3)
+```
+
+We have already seen that constructors can be as complex as needed, calling other methods and doing
+calculations on the received parameters.  On this last example, we will check if the times
+variable was provided. If it is not provided, then we will use matrix columns to define the times:
+
+```{ruby}
+class Trajectories
+
+  def self.init(times: nil, matrix: nil)
+    times = R.c((1..(matrix.ncol >> 0))) if times.nil?
+    Trajectories.new(times: times, matrix: matrix)
+  end
+
+end
+```
+
+```{ruby}
+@traj = Trajectories.init(matrix: R.matrix((1..8), ncol: 4))
+```
+
+# Accessors
+
+Accessors are methods for getting and setting the value of instance variables.
+
+# Get
+
+Getters are methods for getting the value of an instance variable.  We have been using getters
+since the beginning of this document, without explicitly saying so.  When defining attr_reader
+:times and attr_reader :matrix, we have actually defined two getter methods for reading the values
+of variables times and matrix respectively.  We can however define getters explicitly:
+
+```{ruby}
+class TrajectoriesBis
+
+  def initialize(times: nil, matrix: nil)
+    @times = times
+    @matrix = matrix
+  end
+
+  def times
+    @times
+  end
+
+  def matrix
+    @matrix
+  end
+
+end
+
+@traj = TrajectoriesBis.new(times: 1, matrix: 2)
+```
+
+```{ruby}
+puts @traj.times
+```
+
+```{ruby}
+puts @traj.matrix
+```
+
+It is also possible to define more sophisticated getters. For example one can
+regularly need the BMI at inclusion.  In R, one would index a matrix as matrix[,1].  In Ruby,
+it is a syntax error to have a ',' just after the '['.  In this case we need to add 'nil' as
+in matrix[nil, 1]:
+
+```{ruby}
+class Trajectories
+
+  def get_traj_inclusion
+    @matrix[nil, 1]
+  end
+
+end
+```
+
+```{ruby}
+puts @trajCochin.get_traj_inclusion
+```
+
+# Set
+
+A setter is a method that assigns a value to a variable.  As with getters, Ruby also provides an
+easy way to write setters and allow you to also write them explicitly.  Let's first use the
+simple way:
+
+```{ruby}
+class TrajectoriesBis
+
+  attr_writer :times
+  attr_writer :matrix
+
+  def initialize(times: nil, matrix: nil)
+    @times = times
+    @matrix = matrix
+  end
+
+end
+
+@traj = TrajectoriesBis.new
+@traj.times = R.c(1, 2)
+@traj.matrix = R.matrix((1..2), ncol: 2)
+```
+
+```{ruby}
+puts @traj.matrix
+```
+
+Note that now we can use '=' to assign a value to both variables times and matrix. Without
+setters, changing the value of variables times and matrix was not possible.  Our class, up
+to this point was protected from any changes to those variables.  If we need to allow changes
+to those variables, then setters are needed.  In this case, the simple setter as shown above is
+not ideal, since it would allow changes that break the restriction that variable times has to
+have the same length as the number of columns of matrix.  In order to do the verification we
+need to implement a more sophisticated setter.  In the example below, we add the 'times=' setter
+that receives as input one argument.  First we convert the given argument to an R object, then
+check to see that the length of times is the same as the number of columns and if everything is
+fine, then we set the value of instance variable times:
+
+```{ruby}
+class Trajectories
+
+  def as_r(x)
+    return nil if x.nil?
+    return x if x.is_a?(R::Object)
+    R.c(x)
+  end
+
+  def times=(times)
+    times = as_r(times)
+    tl = times.length >> 0; mc = @matrix.ncol >> 0
+    raise "[Trajectories: validation] the number of temporal measurements #{tl} does not correspond with the number of columns in the matrix #{mc}" if (tl != mc)
+    @times = times
+  end
+
+end
+```
+
+```{ruby eval_error_6, warning = FALSE}
+@trajCochin.times = (1..5)
+```
+
+We now set the value appropriately and will not get any errors:
+
+```{ruby}
+@trajCochin.times = R.c(1, 5, 6, 8)
+```
+
+# The Operator '['
+
+It is also possible to define getters by using the operator '['.  This operator is not usually
+used for returning instance variables and it is preferable to use the methods we've used above;
+however, for completeness with SS4 we are showing how to define this here.  Operator '[' is
+better left to be used for array/matrix indices.
+
+```{ruby}
+class Trajectories
+
+  def [](var_name)
+
+    case var_name
+    when "times"
+      @times
+    when "matrix"
+      @matrix
+    else
+      raise "Unknown instance variable"
+    end
+
+  end
+
+end
+```
+
+```{ruby}
+puts @trajCochin["times"]
+```
+
+Similarly, we could use operator '[]=' to assign a value to times and matrix.  We will not do this
+here as we think that the other options are better and the interested user can easily find help,
+if needed to implement such method.
+
+# To Go Further
+
+This section will introduce advanced features of Object Oriented programming such as Inheritance
+and Modules and will also show some aspects of S4 that do not apply to Ruby.
+
+# Methods Using Several Arguments
+
+In Ruby, methods can have as many arguments as needed and those methods are defined the way we
+have already seen in many of the examples above.  The example in SS4 presents a method that prints
+different output if its input is numeric, character or both.  Let's write a class in Ruby that
+does the same for Numeric and String.  In Ruby we do not define global functions, we always define
+methods inside classes or modules (as we will see later).  Also, Ruby is not typed, so methods are
+not called depending on their types as in SS4 examples.  Below, method test will be called with
+one parameter.  At the time of calling we do not know the type of the argument; the method can
+then check if the received argument is a Numeric or a String and at this time, decide what should
+be printed.
+
+```{ruby}
+class Test
+
+  def test(input)
+
+    case input
+    when Numeric
+      puts "The input is numeric: #{input}"
+    when String
+      puts "The input is a string: #{input}"
+    else
+      puts "The input is neither a number nor a string"
+    end
+
+  end
+
+end
+
+@t = Test.new
+```
+
+```{ruby}
+@t.test(5)
+```
+
+```{ruby}
+@t.test("Hello")
+```
+
+Ruby has ways of dealing with multiple arguments, missing arguments, undefined number of arguments,
+named arguments, unnamed arguments, etc.  This is beyond the scope of this document and we
+suggest the interested reader to go to the many resources about Ruby that can easily be found
+on the web.
+
+We will now create a new class 'Partition' that we will use later in this document.  This class will
+have only the basic methods needed for the examples to work.
+
+```{ruby}
+class Partition
+
+  attr_reader :nb_groups
+  attr_reader :part
+
+  def initialize(nb_groups, part)
+    @nb_groups = nb_groups
+    @part = part
+  end
+
+end
+
+@partCochin = Partition.new(2, R.c("A","B","A","B").factor)
+@partStAnne = Partition.new(2, R.c("A","B").rep(R.c(50,30)).factor)
+```
+
+```{ruby}
+puts @partCochin.part
+```
+
+```{ruby}
+puts @partStAnne.part
+```
+
+We will suppose that part is always composed of capital letters going from A to
+LETTERS[nb_groups].
+
+# Inheritance
+
+Ruby being a powerful Object Oriented language has the concept of Inheritance, but it does not
+allow for multiple inheritance.  Multiple inheritance has many drawbacks and Ruby just does not
+support it.  However, Ruby has other concepts that make up for the lack of multiple inheritance as
+we will see in the following examples.
+
+So, let's go back to SS4 examples.  We want now to define a class called TrajPartitioned that
+inherits from class Trajectories.  When a class has a parent, all methods available for the
+parent are also available to the child.
+
+
+```{ruby}
+class TrajPartitioned < Trajectories
+
+  attr_reader :list_partitions
+
+end
+```
+
+That's all there is to it!  We've just created a class TrajPartitioned that inherits all methods
+from class Trajectories and at this point does nothing different from Trajectories, but adds a
+new instance variable: list_partitions.
+
+Creating TrajPartitioned without arguments will generate an error, since a Trajectories requires
+both times and matrix to be non null.
+
+
+```{ruby eval_error_7, warning = FALSE}
+@tdPitie = TrajPartitioned.new
+```
+
+Let's try to create a TrajPartitioned, but passing to it two partitions.  For that, let's first
+create a new Partition:
+
+```{ruby}
+@partCochin2 = Partition.new(3, R.c("A", "C", "C", "B").factor)
+```
+
+And now let's create the TrajPartitioned:
+
+```{ruby eval_error_8, warning = FALSE}
+@tdCochin = TrajPartitioned.new(times: R.c(1,3,4,5), matrix: @trajCochin.matrix,
+                               list_partitions: R.list(@partCochin, @partCochin2))
+```
+
+This didn't work: R function 'list' expects R objects, and in this case, @partCochin and
+@partCochin2 are Ruby classes, so trying to apply function list to them does not work.  Clearly,
+we will have to work in the realm of Ruby to keep the list of partitions.  This is not a problem
+as Ruby has data structures to maintain a list of objects, the Array.  Let's then try another
+solution:
+
+```{ruby eval_error_9, warning = FALSE}
+@tdCochin = TrajPartitioned.new(times: R.c(1,3,4,5), matrix: @trajCochin.matrix,
+                               list_partitions: [@partCochin, @partCochin2])
+```
+
+We now get a second error: 'unknown keyword: list_partitions'.  Class TrajPartitioned inherits
+from class Trajectories and class Trajectories has an initialize function that requires two
+parameters, times and matrix; list_partitions is not a parameter for initialize and is thus
+unknown.  In order to fix this problem we need to create an initialize method for class
+TrajPartitioned.
+
+
+# The 'super' Keyword
+
+R has a method called 'callNextMethod' for control flow between inherited classes.  In Ruby, we
+have a model that is a bit different.  When a method is called on a subclass, if this method is
+not found it will be searched in the parent class and it will go up the hierarchy of classes until
+it is found or an error is issued.  If we want the parent method to be called we can call 'super':
+
+
+```{ruby}
+class TrajPartitioned
+
+  def initialize(times: nil, matrix: nil, list_partitions: nil)
+    super(times: times, matrix: matrix)
+    @list_partitions = list_partitions
+  end
+
+end
+```
+
+Let's try our example again:
+
+```{ruby}
+@tdCochin = TrajPartitioned.new(times: R.c(1,3,4,5), matrix: @trajCochin.matrix,
+                               list_partitions: [@partCochin, @partCochin2])
+```
+
+Now @tdCochin is created correctly; however, the 'show' method only shows information about
+times and matrix, there is nothing about our new list_partitions variable.  This is so, since
+there is no method 'show' in TrajPartitioned, so method 'show' from Trajectories is executed.
+
+So, let's start by writing a 'print' method, that will print all the information we have in
+TrajPartitioned.  The flow of control for this method is: Ruby sees a call to 'print', so it checks
+to see if 'print' is a method for TrajPartitioned.  Since we have just defined this method, Ruby
+finds it and executes it.  The first command in print is a call to 'super', which will call the
+parent 'print' method, that prints information for 'times' and 'matrix'.  When the parent 'print'
+finishes control continues after the 'super' call, printing the number of available partitions.
+
+```{ruby}
+class TrajPartitioned
+
+  def print
+    super
+    puts ("the object also contains #{@list_partitions.length} partition")
+    puts ("***** Fine of print (TrajPartitioned) *****")
+  end
+
+end
+```
+
+```{ruby}
+@tdCochin.print
+```
+
+Notice that this model is much cleaner than 'callNextMethod' and is not subject to any of the
+difficulties presented in SS4 and there is no need for the keywords “is”, “as” and “as<-”, although
+Ruby provides methods to check the class of an object, its hierarchy, etc. when needed.
+
+In Ruby there is no similar method as "setIs" and it is not possible to convert one class into
+another, but there are other ways of getting the necessary results.  Let's then implement a
+method that returns the partition with the least number of groups.  First, as usual, the R code
+with 'setIs':
+
+```
+> setIs(
++ class1="TrajPartitioned",
++ class2="Partition",
++ coerce=function(from,to){
++ numberGroups <- sapply(tdCochin@listPartitions,getNbGroups)
++ Smallest <- which.min(-numberGroups)
++ to<-new("Partition")
++ to@nbGroups <- getNbGroups(from@listPartitions[[Smallest]])
++ to@part <- getPart(from@listPartitions[[Smallest]])
++ return(to)
++ }
++ )
+```
+
+And now the Ruby code.  Here we are getting deeper into Ruby and it is becoming harder for a
+pure R developer to understand the code.  We will describe it in more detail:
+
+* We define a method called 'to_part' that has one argument 'which'.  By default 'which'
+  is ':min', the name of the minimum method.  This means that if no argument is given to
+  to_part it will assume which = :min;
+
+* @list_partitions is a Ruby array.  Method map is similar to method sapply in R, it
+  applies a 'block' to every element of the array, returning an array.  Describing
+  blocks is beyond the scope of this document, but we can think of it as if it were a
+  function.  The block is in '{}' and has one argument named 'part'.  Thus, map goes
+  through all elements of the array, and gets the nb_groups of the element and returns
+  them into the number_groups array.
+
+* number_groups is an array and doing number_groups.min returns the minimum value in
+  number_groups and number_groups.max the maximum.  We can call a method on an object
+  by 'sending' the method name to the object, so, number_groups.send(:min) is equivalent to
+  number_groups.min;
+
+* Method 'index' for array, returns the index of a given element. So, number_groups.index(3)
+  would return the index of the element '3'.  Then number_groups.index(number_groups.min)
+  returns the index of the minimum element in the array.  This is the equivalent of R
+  which.min(number_groups);
+
+* Finally, number_groups.index(number_groups.send(which)), will return the index of the
+  element we ask for, be it :min or :max.  Note that if we pass another value, this would
+  be an error.
+
+```{ruby}
+class TrajPartitioned
+
+  def to_part(which = :min)
+    number_groups = @list_partitions.map { |part| part.nb_groups }
+    selected = number_groups.index(number_groups.send(which))
+    return @list_partitions[selected]
+  end
+
+end
+```
+
+To get the partition with the minimum number of elements:
+
+```{ruby}
+puts @tdCochin.to_part.part
+```
+
+To get the partition with the maximum number of elements:
+
+```{ruby}
+puts @tdCochin.to_part(:max).part
+```
+
+In this example we did not follow exactly the R code from SS4.  The reason for that is that
+'list_partitions' is a list of Ruby classes and we cannot run sapply on this list.  If we
+try to call a 'getNbGroups' or in the Ruby case nb_groups via R's sapply, the code will crash.
+
+# Virtual Classes
+
+In Ruby there are no "Virtual Classes", but it is possible to implement derived classes from
+a parent class with methods that behave properly according to the object's class.  Following
+SS4 we will implement two classes: PartitionSimple and PartitionEval which are subclasses
+of class PartitionFather.  PartitionFather will just be a regular class.  Methods defined in
+PartitionFather will be available to be used in the subclasses
+
+Here is the R code of those classes and the implementation of a method in PartitionFather
+that multiplies the number of groups by 2:
+
+
+```
+> setClass(
++ Class="PartitionFather",
++ representation=representation(nbGroups="numeric","VIRTUAL")
++ )
+
+> setClass(
++ Class="PartitionSimple",
++ representation=representation(part="factor"),
++ contains="PartitionFather"
++ )
+
+> setClass(
++ Class="PartitionEval",
++ representation=representation(part="ordered"),
++ contains="PartitionFather"
++ )
+
+> setGeneric("nbMultTwo",function(object){standardGeneric("nbMultTwo")})
+
+> setMethod("nbMultTwo","PartitionFather",
++ function(object){
++ object@nbGroups <- object@nbGroups*2
++ return (object)
++ }
++ )
+```
+
+Since Ruby has no type definition, there is no really need for a parent class and subclasses.
+However, we will implement those classes in order to show Ruby's inheritance:
+
+```{ruby}
+# Parent class.  Differently from SS4, both 'nb_groups' and 'part' are defined in the
+# parent class.
+class PartitionFather
+
+  attr_reader :nb_groups
+  attr_reader :part
+
+  # initialize class PartitionFather with the number of groups and parts.  Note that we
+  # use R.c for nb_groups in order to convert the number of groups into an R vector.
+  def initialize(nb_groups: 0, part: nil)
+    @nb_groups = R.c(nb_groups)
+    @part = part
+  end
+
+  # method nb_mult_two can be called from all subclasses
+  def nb_mult_two
+    @nb_groups * 2
+  end
+
+  # method 'to_s' is called whenever we try to print a Ruby object.  This method emulates
+  # R 'print' method that prints all the slots.
+  def to_s
+    puts ("Variable 'nb_groups':")
+    puts @nb_groups
+    puts
+    puts ("Variable 'part':")
+    puts @part
+    puts
+  end
+
+end
+
+# Class PartitionSimple is a subclass of PartitionFather.  To make a subclass of a
+# class we use the operator '<'.  Since the whole logic is in the parent class
+# PartitionSimple is just an empty class
+class PartitionSimple < PartitionFather
+
+end
+
+# PartitionEval is also only an empty class
+class PartitionEval < PartitionFather
+
+end
+```
+
+```{ruby}
+@a = PartitionSimple.new(nb_groups: 3, part: ((~R[:LETTERS])[R.c(1, 2, 3, 2, 2, 1)].factor))
+puts @a
+```
+
+```{ruby}
+puts @a.nb_mult_two
+```
+
+```{ruby}
+@b = PartitionEval.new(nb_groups: 5, part: (~R[:LETTERS])[R.c(1, 5, 3, 4, 2, 4)].ordered)
+puts @b
+```
+
+```{ruby}
+puts @b.nb_mult_two
+```
+
+The example above, although it replicates SS4 is not actually very useful from the point of
+view of class hierarchy in Ruby.  We will then write a new function to_s in class
+PartitionSimple that will print the name of the class:
+
+```{ruby}
+class PartitionSimple
+
+  def to_s
+    puts("Class PartitionSimple")
+    super
+  end
+
+end
+```
+
+```{ruby}
+puts @a
+```
+
+As can be seen, 'puts @a' now calls method 'to_s' defined in class PartitionSimple.  This
+method prints 'Class PartitionSimple' and then calls the super method, i.e., method 'to_s'
+from class PartitionFather.
+
+Note though that 'puts @b' still prints the same output, since it has no particular 'to_s'
+method.
+
+```{ruby}
+puts @b
+```
+
+# Internal Modification of an Object
+
+
+## Method to Modify a Field
+
+Let us return to our trajectories example and define a third method that imputes data for
+missing values. To simplify, we will impute by replacing by the mean values.  This is the R
+code to do this:
+
+```
+> meanWithoutNa <- function (x){mean(x,na.rm=TRUE)}
+> setGeneric("impute",function (.Object){standardGeneric("impute")})
+> setMethod(
++ f="impute",
++ signature="Trajectories",
++ def=function(.Object){
++ average <- apply(.Object@traj,2,meanWithoutNa)
++ for (iCol in 1:ncol(.Object@traj)){
++ .Object@traj[is.na(.Object@traj[,iCol]),iCol] <- average[iCol]
++ }
++ return(.Object)
++ }
++ )
+```
+
+The code above, as explained in SS4 creates a new object and does not change the original one.
+So, calling impute(trajCochin) will work correctly by creating a new object but will not
+change trajCochin.  This works fine, but can be memory expensive if the matrix is a large
+one.
+
+Let's now implement the same method in Galaaz 2.0.  We stay on the R side of the bridge:
+for each column, compute the mean with `na.rm = true`, then replace NA entries with that mean
+(via `R.ifelse` / `is__na`), and rebuild the matrix with `R.cbind`.  No MDArray iteration is
+required.
+
+```{ruby}
+class Trajectories
+
+  def impute
+    ncols = @matrix.ncol >> 0
+    imputed = (1..ncols).map do |j|
+      col = @matrix[nil, j]
+      avg = col.mean(na__rm: true)
+      R.ifelse(col.is__na, avg, col)
+    end
+    col_names = @matrix.colnames
+    row_names = @matrix.rownames
+    @matrix = R.cbind(*imputed)
+    @matrix.colnames = col_names unless col_names.nil?
+    @matrix.rownames = row_names unless row_names.nil?
+    self
+  end
+
+end
+```
+
+```{ruby}
+@trajCochin.impute
+puts @trajCochin.matrix
+```
+
+It works, and `@trajCochin.matrix` was updated.  Under GNU R, assignment follows R's usual
+copy-on-write semantics: replacing `@matrix` (or assigning into an R object through the bridge)
+binds a new vector/matrix rather than mutating a shared MDArray store.  That is a deliberate
+difference from the Renjin/MDArray mutation experiments in the older paper; those demos are not
+part of Galaaz 2.0.
+
+# Conclusions I
+
+This ends the SS4 paper material for classes and inheritance.  We believe we have shown that R S4
+can be substituted by Galaaz and Ruby classes and that Galaaz makes an easy transition from R
+developers to Ruby.  Ruby is a very flexible and powerful language and has many interesting
+libraries, where Rails is maybe one of the best known, but there are thousands of others.  For
+those interested in getting deeper into Ruby's libraries, we suggest they look at:
+
+* https://github.com/markets/awesome-ruby
+* http://bestgems.org/
+
+For those interested in Ruby and science, we recommend:
+
+* http://sciruby.com/
+
+**Galaaz 2.0** runs on **JRuby** and talks to **GNU R** through the bridge described in this
+series — the same integration model used throughout the examples above.
+
+# Callbacks and R calling into Ruby
+
+On this paper we have focused on accessing R functions from Ruby and have shown how to
+integrate Ruby with R from the point of view of a Ruby developer.  The complementary direction —
+R calling back into Ruby — is also supported in Galaaz 2.0.
+
+Galaaz 2.0 uses the **bridge callback** mechanism: Ruby procs (and related callables) can be
+passed where R expects functions, so algorithms written in R (for example optimizers or higher-order
+`*apply` helpers) can invoke Ruby logic without leaving the bridge session.  Details, options such
+as callback timeouts, and further examples are in the project manual and on the documentation site:
+[https://rbotafogo.github.io/galaaz/](https://rbotafogo.github.io/galaaz/).
+
+We do not reproduce here the older Renjin-era material on packing Ruby objects as R external
+pointers, constructing Ruby classes from R via JVM APIs, or calling Java collections from R
+scripts.  Those sections belonged to a different runtime; the callback bridge is the supported
+path in Galaaz 2.0.
+
+# Conclusions II
+
+**JRuby + GNU R + Galaaz** gives a practical polyglot stack: idiomatic Ruby for structure and
+libraries, GNU R for statistics and the CRAN/Bioconductor ecosystem, and Galaaz as the bridge
+between them.  As always, choose the right tools for the job at hand — and when the job sits
+between an R-only workflow and a broader polyglot application, Galaaz is designed to connect those
+worlds.