galaaz 0.4.10 → 2.0.0

data/blogs/ruby_plot/ruby_plot.md

@@ -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
@@ -41,42 +41,17 @@ 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.
+
+**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 usual way of bringing features from one language into another.
 To improve performance, Python often wraps more efficient C libraries. For the
@@ -105,7 +80,7 @@ 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
 
@@ -137,14 +112,14 @@ 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
 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
+``` ruby
 # 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
 ```
@@ -165,7 +140,7 @@ with a dot ('.') and the name of the column. Also use dot notation to chain meth
 in usual Ruby style.
 
 
-```ruby
+``` ruby
 # Access the tooth_growth 'len' column and print the first few
 # elements of this column with the 'head' method.
 puts tooth_growth.len.head
@@ -183,7 +158,7 @@ function from Galaaz the dot ('.') in the function name is substituted by '__' (
 The function 'as.factor' becomes 'R.as__factor' or just 'as__factor' when chaining.
 
 
-```ruby
+``` ruby
 # convert the dose to a factor
 tooth_growth.dose = tooth_growth.dose.as__factor
 ```
@@ -192,7 +167,7 @@ Let's explore some more details of this dataset.  In particular, let's look at i
 structure and summary statistics.
 
 
-```ruby
+``` ruby
 puts tooth_growth.dim
 ```
 
@@ -207,23 +182,16 @@ functions does not return anything and prints the structure of the dataset
 as a side effect.
 
 
-```ruby
+``` ruby
 tooth_growth.str
 ```
-
-```
-## 'data.frame':	60 obs. of  3 variables:
-##  $ len : num  4.2 11.5 7.3 5.8 6.4 10 11.2 11.2 5.2 7 ...
-##  $ supp: Factor w/ 2 levels "OJ","VC": 2 2 2 2 2 2 2 2 2 2 ...
-##  $ dose: Factor w/ 3 levels "0.5","1","2": 1 1 1 1 1 1 1 1 1 1 ...
-```
 Observe that both variables 'supp' and 'dose' are factors.  The system made variable 'supp'
 a factor automatically, since it contais two strings OJ and VC.
 
 Finally, using the summary method, we get the statistical summary for the dataset
 
 
-```ruby
+``` ruby
 puts tooth_growth.summary
 ```
 
@@ -264,14 +232,14 @@ the $y$ axis: 'E.aes(x: :dose, y: :len)'.  To specify the type of plot add a geo
 the plot.  For a boxplot, the geom is R.geom_boxplot.
 
 
-```ruby
+``` ruby
 require 'ggplot'
 
 e = tooth_growth.ggplot(E.aes(x: :dose, y: :len))
 print e + R.geom_boxplot
 ```
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/dose_len.png)<!-- -->
+![](ruby_plot_files/figure-html/dose_len.png)
 
 Great! We've just managed to create and save our first plot in Ruby with only
 four lines of code. We can now easily see with this plot a clear trend: as the
@@ -293,31 +261,30 @@ 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
 
+``` ruby
 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
 ```
 
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/facet_by_delivery.png)<!-- -->
+![](ruby_plot_files/figure-html/facet_by_delivery.png)
 
 It now becomes clear that although both methods of delivery have a direct
 impact on tooth growth, method (OJ) is non-linear having a higher impact with smaller
@@ -334,13 +301,13 @@ enough to add ```fill: :dose``` to the aesthetic of boxplot.  With this command
 factor gets its own color.
 
 
-```ruby
+``` ruby
 bp = bp + R.geom_boxplot(E.aes(fill: :dose))
 puts bp
 ```
 
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/facets_by_delivery_color.png)<!-- -->
+![](ruby_plot_files/figure-html/facets_by_delivery_color.png)
 
 Facetting helps us compare the general trends for each delivery method.
 Adding color allow us to compare specifically how each dosage impacts the tooth growth.
@@ -372,7 +339,7 @@ each of the 60 pigs in the experiment.  For that, add the function 'R.geom_point
 plot.
 
 
-```ruby
+``` ruby
 # Split in vertical direction
 bp = bp + R.geom_point
 
@@ -380,7 +347,7 @@ puts bp
 ```
 
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/facets_with_points.png)<!-- -->
+![](ruby_plot_files/figure-html/facets_with_points.png)
 
 Now we can see the actual distribution of all the 60 subjects.  Actually, this is not
 totally true.  We have a hard time seing all 60 subjects. It seems that some points
@@ -394,13 +361,13 @@ prevents data hiding.  We also add
 color and change the shape of the points, making them even easier to see.
 
 
-```ruby
+``` ruby
 # Split in vertical direction
 puts bp + R.geom_jitter(shape: 23, color: "cyan3", size: 1)
 ```
 
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/facets_with_jitter.png)<!-- -->
+![](ruby_plot_files/figure-html/facets_with_jitter.png)
 
 Now we can see all 60 points in the graph. We have here a much higher information density
 and we can see outliers and subjects distribution.
@@ -436,7 +403,7 @@ This ordering seems more natural and
 matches with the actual order of the colors in the plot.
 
 
-```ruby
+``` ruby
 bp = bp +
      R.scale_fill_manual(values: R.c("cyan", "deepskyblue", "deepskyblue4"),
                           breaks: R.c("2","1","0.5"))
@@ -445,7 +412,7 @@ puts bp
 ```
 
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/facets_by_delivery_color2.png)<!-- -->
+![](ruby_plot_files/figure-html/facets_by_delivery_color2.png)
 
 ## Violin Plot and Jitter
 
@@ -465,9 +432,9 @@ a boxplot known as a _violin plot_ with jittered data.
 > The central dot represents the median average value. 
 
 
-```ruby
+``` ruby
 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"))
@@ -476,7 +443,7 @@ puts violin
 ```
 
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/violin_with_jitter.png)<!-- -->
+![](ruby_plot_files/figure-html/violin_with_jitter.png)
 
 This plot is an alternative to the original boxplot.  For the final presentation, it is
 important to think which graphics will be best understood by our audience. A violin plot
@@ -497,7 +464,7 @@ for information about the plot (for clarity, we defined a caption variable using
 Here Doc style).
 
 
-```ruby
+``` ruby
 caption = <<-EOT
 Length of odontoblasts in 60 guinea pigs. 
 Each animal received one of three dose levels of vitamin C.
@@ -513,7 +480,7 @@ puts bp + decorations
 ```
 
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/facets_with_decorations.png)<!-- -->
+![](ruby_plot_files/figure-html/facets_with_decorations.png)
 
 ## The Corp Theme
 
@@ -531,7 +498,7 @@ a shade o blue (color: '#00080').  Axis labels are moved near the end of the axi
 written in 'bold'.
 
 
-```ruby
+``` ruby
 module CorpTheme
 
   R.install_and_loads 'RColorBrewer'
@@ -595,23 +562,23 @@ the decorations ('decorations'), plus the corporate theme.
 Here is our final boxplot, without jitter.
 
 
-```ruby
+``` ruby
 puts bp + decorations + CorpTheme.global_theme(faceted: true)
 ```
 
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/final_box_plot.png)<!-- -->
+![](ruby_plot_files/figure-html/final_box_plot.png)
 
 And here is the final violin plot, with jitter and the same look and feel of the corporate
 boxplot.
 
 
-```ruby
+``` ruby
 puts violin + decorations + CorpTheme.global_theme(faceted: true)
 ```
 
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/final_violin_plot.png)<!-- -->
+![](ruby_plot_files/figure-html/final_violin_plot.png)
 
 ## Another View
 
@@ -620,14 +587,14 @@ dose and not by supplement.  This shows how easy it is to create new plots by ju
 changing small statement on the _grammar of graphics_.
 
 
-```ruby
+``` ruby
 caption = <<-EOT
 Length of odontoblasts in 60 guinea pigs. 
 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",
@@ -639,7 +606,7 @@ puts bp
 ```
 
 
-![](/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/facet_by_dose.png)<!-- -->
+![](ruby_plot_files/figure-html/facet_by_dose.png)
 
 # Conclusion
 
@@ -651,18 +618,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
@@ -676,11 +642,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:
@@ -689,14 +655,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.