galaaz 0.4.10 → 2.0.0

data/blogs/oh_my/old.Rmd

@@ -1,9 +1,10 @@
 ---
 title: "Extending R with classes, modules, procs, lambdas, oh my!"
+subtitle: "Archived variant (Renjin-era narrative); see `oh_my.Rmd` and the Galaaz 2.0 manual for current stack"
 author:
     - "Rodrigo Botafogo"
     - "Daniel Mossé - University of Pittsburgh"
-tags: [Tech, Data Science, Ruby, R, GraalVM]
+tags: [Archived, Tech, Data Science, Ruby, R, Renjin]
 date: "November 19th, 2018"
 output:
   html_document:
@@ -25,11 +26,11 @@ 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
+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 Java Virtual Machine and it
@@ -84,7 +85,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 column before the variables name:
@@ -101,7 +102,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:
 
 ```
 traj = Trajectories.new
@@ -125,7 +126,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 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:
 EOT
@@ -154,7 +155,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:
 EOT
 
 ```
@@ -274,7 +275,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}
@@ -377,7 +378,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",
@@ -469,7 +470,7 @@ features of Galaaz, some we have already seen, others will be described now:
   an R vector that holds a number, then @num.gz is a number that can be used normally with Ruby
   methods;
 
-* 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;
 
@@ -1191,7 +1192,7 @@ to this point was protected from any changes to those variables.  If we need to
 to those variable, 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 bellow, we add the 'times=' setter
+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:
@@ -1282,7 +1283,7 @@ have already seen in many of the examples above.  The example in SS4 presents a
 different output if its input is numeric, character has 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.  Bellow, method test will be called with
+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 is the received argument is a Numeric or a String and at this time, decide what should
 be printed. 
@@ -1774,7 +1775,7 @@ As we can now see, trajCochin and cochin_internal have different content, while
 still has the same value in index 0, i.e. 15.0, trajCochin matrix has value 1 in index 1.  This
 shows that Renjin when assigning to trajCochin.matrix[1] makes a copy of the original data.
 
-Bellow, we use method 'get' which is a synonym of method 'as__mdarray' to again get the content
+Below, we use method 'get' which is a synonym of method 'as__mdarray' to again get the content
 of trajCochin.matrix.  This variable has as first element the value 1, as set previously.
 
 ```
@@ -1942,7 +1943,7 @@ As you can see, 'ruby.array' is still the same Ruby object.
 Avatars maintain some properties of their original world.  Although the concept of method
 chaning is foreign to R, chaining can be used with imported objects from Ruby. Method
 chaining occurs when the result of a applying a method on an object returns an object (usually
-the same object) in which another method can be applied.  In the example bellow, method '<<'
+the same object) in which another method can be applied.  In the example below, method '<<'
 will be applied multiple times for ruby.array
 EOT
 

data/blogs/ruby_plot/ruby_plot.Rmd

@@ -3,8 +3,8 @@ title: "How to make Beautiful Ruby Plots with Galaaz"
 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
@@ -31,59 +31,33 @@ general-purpose programming language. It was designed and developed in the mid-1
 "Matz" Matsumoto in Japan."  It reached high popularity with the development of Ruby on Rails
 (RoR) by David Heinemeier Hansson. RoR is a web application framework first released
 around 2005. It makes extensive use of Ruby's metaprogramming features.  With RoR,
-Ruby became very popular.  According to [Ruby's Tiobe index](https://www.tiobe.com/tiobe-index/ruby/)
-it peeked in popularity around 2008, then declined until 2015 when it started picking up again.
-At the time of this writing (November 2018), the Tiobe index puts Ruby in 16th position as
-most popular language.
+Ruby became very popular.  According to [Ruby’s ranking in the TIOBE index](https://www.tiobe.com/tiobe-index/ruby/)
+it **peaked** in popularity around 2008, then declined until 2015 when it started picking up again.
+As of the original publication date (November 2018), TIOBE placed Ruby around 16th among languages.
 
-Python, a language similar to Ruby, ranks 4th in the index.  Java, C and C++ take the
-first three positions.  Ruby is often criticized for its focus on web applications.
+Python, often grouped with Ruby as a high-level scripting language, ranked higher in that same snapshot.
+Ruby is often criticized for its focus on web applications.
 But Ruby can do [much more](https://github.com/markets/awesome-ruby) than just web applications.
-Yet, for scientific computing, Ruby lags way behind Python and R.  Python has
-Django framework for web, NumPy for numerical arrays, Pandas for data analysis.
+Yet, for scientific computing, Ruby lags behind Python and R.  Python combines web frameworks such as
+Django with NumPy, pandas, SciPy, and **a very large ecosystem** of domain-specific packages.
 R is a free software environment for statistical computing and graphics with thousands
 of libraries for data analysis. 
 
 Until recently, there was no real perspective for Ruby to bridge this gap.
 Implementing a complete scientific computing infrastructure would take too long.
-Enters [Oracle's GraalVM](https://www.graalvm.org/):
-
-> GraalVM is a universal virtual machine for running applications written in
-> JavaScript, Python 3, Ruby, R, JVM-based languages like Java, Scala, Kotlin,
-> and LLVM-based languages such as C and C++.
->
-> GraalVM removes the isolation between programming languages and enables
-> interoperability in a shared runtime. It can run either standalone or in the
-> context of OpenJDK, Node.js, Oracle Database, or MySQL.
->
-> GraalVM allows you to write polyglot applications with a seamless way to pass
-> values from one language to another. With GraalVM there is no copying or
-> marshaling necessary as it is with other polyglot systems. This lets you
-> achieve high performance when language boundaries are crossed. Most of the time
-> there is no additional cost for crossing a language boundary at all.
->
-> Often developers have to make uncomfortable compromises that require them
-> to rewrite their software in other languages. For example:
->
->  * That library is not available in my language. I need to rewrite it. 
->  * That language would be the perfect fit for my problem, but we cannot
->    run it in our environment. 
->  * That problem is already solved in my language, but the language is
->    too slow.
->   
->  With GraalVM we aim to allow developers to freely choose the right language for
->  the task at hand without making compromises.
-
-As stated above, GraalVM is a _universal_ virtual machine that allows Ruby and R (and other
-languages) to run on the same environment.  GraalVM allows polyglot applications to
-_seamlessly_ interact with one another and pass values from one language to the other.
-Although a great idea, GraalVM still requires application writers to know several languages.
-To eliminate that requirement, we built Galaaz, a gem for Ruby, to tightly couple
-Ruby and R and allow those languages to interact in a way that the user will be unaware
-of such interaction. In other words, a Ruby programmer will be able to use all
-the capabilities of R without knowing the R syntax.
-
-Library wrapping is a usual way of bringing features from one language into another.
+
+**Galaaz 2.0** couples **[JRuby](https://www.jruby.org/)** (Ruby on the JVM) with **GNU R**—the
+same R distribution used for data science everywhere. A **bridge** evaluates R from Ruby and
+exchanges data between the two processes so that, from Ruby, you call R functions and work
+with R objects using familiar Ruby syntax. In other words, a Ruby programmer can use the
+capabilities of R without memorizing all of R’s syntax for day-to-day tasks.
+
+An **earlier line of work** used Oracle’s **GraalVM** with **TruffleRuby** and **FastR** so that
+Ruby and R could share one JVM runtime. That stack is **no longer** what Galaaz targets;
+today’s Galaaz is developed and tested with **JRuby + GNU R** (see the project manual for setup
+and command-line tools).
+
+Library wrapping is a common way to bring features from one language into another.
 To improve performance, Python often wraps more efficient C libraries. For the
 Python developer, the existence of such C libraries is hidden.  The problem with
 library wrapping is that for any new library, there is the need to handcraft a new
@@ -94,7 +68,7 @@ in Ruby.  Doing so, all thousands of R libraries are available immediately
 to Ruby developers without any new wrapping effort.
 
 To show the power of Galaaz, we show in this article how Ruby can use R's ggplot2
-library tranparantly bringing to Ruby the power of high quality scientific plotting.
+library **transparently**, bringing to Ruby the power of high-quality scientific plotting.
 We also show that migrating from R to Ruby with Galaaz is a matter of small
 syntactic changes. By using Ruby, the R developer can use all of Ruby's powerful
 object-oriented features. Also, with Ruby, it becomes much easier to move code
@@ -110,14 +84,14 @@ ggplot themes that will work the same as the Ruby module.  Yet, writing a new th
 requires specific knowledge on theme writing.  Ruby modules are standard to the
 language and don't need special knowledge.
 
-[Here](https://towardsdatascience.com/ruby-plotting-with-galaaz-an-example-of-tightly-coupling-ruby-and-r-in-graalvm-520b69e21021) we show a scatter plot in Ruby also with Galaaz.
+[Here](https://towardsdatascience.com/ruby-plotting-with-galaaz-an-example-of-tightly-coupling-ruby-and-r-in-graalvm-520b69e21021) is an older article (GraalVM-era Galaaz) with a scatter plot in Ruby; the **ideas** still apply under Galaaz 2.0 with JRuby and GNU R.
 
 # gKnit
 
 _Knitr_ is an application that converts text written in rmarkdown to many
 different output formats.  For instance, a writer can convert an rmarkdown  document
-to HTML, $LaTex$, docx and many other formats. Rmarkdown documents can contain
-text and _code chunks_. Knitr formats code chunks in a grayed box in the output document.
+to HTML, LaTeX, Word, and many other formats. R Markdown documents can contain
+text and _code chunks_. knitr formats code chunks in a shaded box in the output document.
 It also executes the code chunks and formats the output in a white box.  Every line of
 output from the execution code is preceded by '##'.
 
@@ -131,7 +105,7 @@ With _gKnit_ Ruby code chunks can share data.
 # Exploring the Dataset
 
 Let's start by exploring our selected dataset.  ToothGrowth is an R dataset.  A dataset
-is like a simple excel spreadsheet, in which each column has only one type of data.
+is like a simple Excel spreadsheet, in which each column has only one type of data.
 For instance one column can have float, the other integer, and a third strings.
 This dataset analyzes the length of odontoblasts (cells responsible for tooth growth)
 in 60 guinea pigs, where each animal received one of three dose levels of Vitamin C
@@ -140,15 +114,15 @@ in 60 guinea pigs, where each animal received one of three dose levels of Vitami
 
 The ToothGrowth dataset contains three columns: 'len', 'supp' and 'dose'.  Let's
 take a look at a few rows of this dataset. In Galaaz, R variables are accessed
-by using the corresponding Ruby symbol preceeded by the tilda ('~') function. Note in the
+by using the corresponding Ruby symbol with the tilde (`~`) operator. Note in the
 following chunk that 'ToothGrowth' is the R  variable and Ruby's 'tooth_growth' is
-assigned the value of '~:ToothGrowth'.
+assigned the value of '~R[:ToothGrowth]'.
 
 ```{ruby head}
 # Read the R ToothGrowth variable and assign it to the
 # Ruby instance variable tooth_growth that will be 
 # available to all Ruby chunks in this document.
-tooth_growth = ~:ToothGrowth
+tooth_growth = ~R[:ToothGrowth]
 # print the first few elements of the dataset
 puts tooth_growth.head
 ```
@@ -166,7 +140,7 @@ puts tooth_growth.len.head
  
 The 'dose' column contains a numeric value with either, 0.5, 1 or 2, although the
 first 6 rows as seen above only contain the 0.5 values.  Even though those are
-number, they are better interpreted as a [factor or cathegory](https://swcarpentry.github.io/r-novice-inflammation/12-supp-factors/).  So, let's convert our 'dose' column from numeric to 'factor'.
+number, they are better interpreted as a [factor or category](https://swcarpentry.github.io/r-novice-inflammation/12-supp-factors/).  So, let's convert our 'dose' column from numeric to 'factor'.
 In R, the function 'as.factor' is used to convert data in a vector to factors.  To use this
 function from Galaaz the dot ('.') in the function name is substituted by '__' (double underline).
 The function 'as.factor' becomes 'R.as__factor' or just 'as__factor' when chaining.
@@ -221,7 +195,7 @@ to form the final graphics.
 In order to make a plot, we use the 'ggplot' function to the dataset.  In R, this would be
 written as ```ggplot(<dataset>, ...)```. Galaaz gives you the flexibility to use
 either ```R.ggplot(<dataset>, ...)``` or ```<dataset>.ggplot(...)```.  In the graph 
-specification bellow, we use the second notation that looks more like Ruby.  
+specification below, we use the second notation that looks more like Ruby.  
 ggplot uses the ‘aes’ method to specify
 x and y axes; in this case, the 'dose' on the $x$ axis and the 'length' on
 the $y$ axis: 'E.aes(x: :dose, y: :len)'.  To specify the type of plot add a geom to
@@ -254,16 +228,16 @@ the 'facet_grid' method is a [_formula_](https://thomasleeper.com/Rcourse/Tutori
 
 In Galaaz we give programmers the flexibility to use two different ways to write formulas.
 In the first way, we use Ruby expressions and the '.til' function. The formula 'x ~ y', becomes
-':x.til :y'. More information on expressions can be found in [Galaaz Manual](https://www.rubydoc.info/gems/galaaz/).
+'R[:x].til :y'. More information on expressions can be found in [Galaaz Manual](https://www.rubydoc.info/gems/galaaz/).
 
 
 Another way of writing a formula is to use the 'formula' function with the actual formula as
 a string.  The formula ```x ~ y``` in R can be written as ```R.formula("x ~ y")```.  For more
 complex formulas, the use of the 'formula' function is preferred.
 
-The formula ```:all.til :supp``` indicates to the 'facet_grid' function that it needs to
+The formula ```R[:all].til :supp``` indicates to the 'facet_grid' function that it needs to
 facet the plot based on the ```supp``` variable and split the plot vertically.  Changing
-the formula to ```:supp.til :all``` would split the plot horizontally.
+the formula to ```R[:supp].til :all``` would split the plot horizontally.
 
 ```{ruby facet_by_delivery, dev = "png", fig.width = 540, fig.height = 560, units = "px"}
 
@@ -271,8 +245,8 @@ base_tooth = tooth_growth.ggplot(E.aes(x: :dose, y: :len, group: :dose))
 
 bp = base_tooth + R.geom_boxplot +
       # Split in vertical direction
-      R.facet_grid(:all.til :supp)
-      
+      R.facet_grid(R[:all].til :supp)
+
 puts bp
 ```
 
@@ -407,7 +381,7 @@ a boxplot known as a _violin plot_ with jittered data.
 
 ```{ruby violin_with_jitter, dev = "png", fig.width = 540, fig.height = 560, units = "px"}
 violin = base_tooth + R.geom_violin(E.aes(fill: :dose)) + 
-   R.facet_grid(:all.til :supp) +
+   R.facet_grid(R[:all].til :supp) +
    R.geom_jitter(shape: 23, color: "cyan3", size: 1) +
    R.scale_fill_manual(values: R.c("cyan", "deepskyblue", "deepskyblue4"),
                        breaks: R.c("2","1","0.5"))
@@ -550,7 +524,7 @@ Each animal received one of three dose levels of vitamin C.
 EOT
 
 bp = tooth_growth.ggplot(E.aes(x: :supp, y: :len, group: :supp)) + 
-     R.geom_boxplot(E.aes(fill: :supp)) + R.facet_grid(:all.til :dose) +
+     R.geom_boxplot(E.aes(fill: :supp)) + R.facet_grid(R[:all].til :dose) +
      R.scale_fill_manual(values: R.c("cyan", "deepskyblue4")) +
      R.labs(title: "Tooth Growth:  Length by Dose",
             subtitle: "Faceted by dose",
@@ -571,17 +545,17 @@ developer, migration to Ruby is a matter of small syntactic changes with a very
 learning curve. As the R developer becomes more proficient in Ruby, he can start using
 'classes', 'modules', 'procs', 'lambdas'.  
 
-Trying to bring to Ruby the power of R starting from scratch is an enourmous endeavour
+Trying to bring to Ruby the power of R starting from scratch is an enormous endeavour
 and would probably never be accomplished.  Today's data scientists would certainly
 stick with either Python or R.  Now, both the Ruby and R communities can benefit
-from this marriage, provided by Galaaz on top of GraalVM and Truffle's
-polyglot environment.  We presented the process to couple Ruby and R, but this 
-process can also be done to couple Ruby and JavaScript or Ruby and Python. 
-In a polyglot world a *uniglot* language might be extremely relevant.
+from this marriage: **Galaaz 2.0** uses **standard GNU R** for statistics and graphics
+and **JRuby** for application code, threading, and the JVM ecosystem.  We presented
+the process to couple Ruby and R; the coupling is implemented by the Galaaz bridge and
+**gKnit** for literate documents, not by a single GraalVM polyglot runtime.
 
-From the perspective of performance, GraalVM and Truffle promises improvements that could
-reach over 10 times, both for [FastR](https://medium.com/graalvm/faster-r-with-fastr-4b8db0e0dceb)
-and for [TruffleRuby](https://rubykaigi.org/2018/presentations/eregontp.html).
+For performance, expect **ordinary GNU R** behaviour for model fitting and plotting, while
+**JRuby** gives **real parallel threads** on the Ruby side and access to Java libraries when
+you need them.
 
 This article has shown how to improve a plot step-by-step.  Starting from a very simple
 boxplot with all default configurations, we moved slowly to our final plot.  The important
@@ -595,11 +569,11 @@ be of great help for any Rubyist trying to write articles, blogs or documentatio
 
 # Installing Galaaz
 
-## Prerequisites
+## Prerequisites (Galaaz 2.0)
 
-* GraalVM (>= rc8): https://github.com/oracle/graal/releases
-* TruffleRuby
-* FastR
+* **JRuby** — Ruby on the JVM ([jruby.org](https://www.jruby.org/))
+* A **JDK** compatible with your JRuby version
+* **GNU R** — `R` on your `PATH`, with compilers/tools available if packages must be built from source
 
 The following R packages will be automatically installed when necessary, but could be installed prior
 to using gKnit if desired:
@@ -608,14 +582,16 @@ to using gKnit if desired:
 * gridExtra
 * knitr
 
-Installation of R packages requires a development environment and can be time consuming.  In Linux,
-the gnu compiler and tools should be enough.  I am not sure what is needed on the Mac.
+Installation of R packages requires a development environment and can be time consuming.  On Linux,
+the usual build tools (e.g. a C/C++ compiler) are typically enough.  On macOS, Xcode command-line tools
+are commonly required.
 
 ## Preparation
 
-* gem install galaaz
+* Install the **galaaz** gem (from RubyGems when published, or `gem build` / `path:` from a checkout).
 
 ## Usage
 
-* gknit <filename>
-* In a scrip add: require 'galaaz'
+* From the Galaaz repository (or your installed layout), render documents with **`bin/gknit`** (see the project manual for flags such as `--output_format all`).
+* In Ruby code: `require 'galaaz'`
+* For running scripts with the correct JRuby and JVM options, use **`bin/galaaz-jruby`** as described in the manual.