galaaz 0.5.0 → 2.0.0

data/blogs/galaaz_ggplot/galaaz_ggplot.md

@@ -1,78 +1,36 @@
----
-title: "Ruby Plotting with Galaaz"
-subtitle: "An example of tightly coupling Ruby and R in GraalVM"
-author: "Rodrigo Botafogo"
-tags: [Galaaz, Ruby, R, TruffleRuby, FastR, GraalVM, ggplot2]
-date: "16 October 2018"
-output:
-  html_document:
-    self_contained: true
-    keep_md: true
-  pdf_document:
-    includes:
-      in_header: "../../sty/galaaz.sty"
-    keep_tex: yes
-    number_sections: yes
-    toc: true
-    toc_depth: 2
-  md_document:
-    variant: markdown_github
-fontsize: 11pt
----
-
-
-
 # Introduction
 
-Galaaz is a system for tightly coupling Ruby and R.  Ruby is a powerful language, with
-a large community, a very large set of libraries and great for web development.  However,
-it lacks libraries for data science, statistics, scientific plotting and machine learning.
-On the other hand, R is considered one of the most powerful languages for solving all of the
-above problems.  Maybe the strongest competitor to R is Python with libraries such as NumPy,
-Panda, SciPy, SciKit-Learn and a couple more.
-
-With Galaaz we do not intend to re-implement any of the scientific libraries in R, we allow
-for very tight coupling between the two languages to the point that the Ruby developer does
-not need to know that there is an R engine running.  For this to happen we use new
-technologies provided by Oracle: GraalVM, TruffleRuby and FastR:
-
-     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.
-
-Interested readers should also check out the following sites:
-
-* [GraalVM Home](https://www.graalvm.org/)
-* [TruffleRuby](https://github.com/oracle/truffleruby)
-* [FastR](https://github.com/oracle/fastr)
-* [Faster R with FastR](https://medium.com/graalvm/faster-r-with-fastr-4b8db0e0dceb)
+Galaaz is a system for tightly coupling Ruby and R. Ruby is a powerful
+language, with a large community, a very large set of libraries and
+great for web development. However, it lacks libraries for data science,
+statistics, scientific plotting and machine learning. On the other hand,
+R is considered one of the most powerful languages for solving all of
+the above problems. Maybe the strongest competitor to R is Python with
+libraries such as NumPy, Panda, SciPy, SciKit-Learn and a couple more.
+
+With Galaaz we do not intend to re-implement any of the scientific
+libraries in R; we allow for very tight coupling between the two
+languages to the point that the Ruby developer does not need to think
+about R syntax for every call. **Galaaz 2.0** does this with
+**[JRuby](https://www.jruby.org/)** and **GNU R**: a **bridge**
+evaluates R from Ruby and exchanges data between processes.
+
+An **earlier** Galaaz prototype used Oracle’s **GraalVM** with
+**TruffleRuby** and **FastR** in one JVM. That stack is **historical**;
+today’s documentation and tooling assume **JRuby + GNU R** (see the
+project manual and **`bin/galaaz-jruby`** / **`bin/gknit`**).
+
+For background on the old stack:
+
+- [GraalVM Home](https://www.graalvm.org/)
+- [TruffleRuby](https://github.com/oracle/truffleruby)
+- [FastR](https://github.com/oracle/fastr)
+- [Faster R with
+  FastR](https://medium.com/graalvm/faster-r-with-fastr-4b8db0e0dceb)
 
 ## What does Galaaz mean
 
-Galaaz is the Portuguese name for "Galahad".  From Wikipedia:
+Galaaz is the Portuguese name for “Galahad”. From Wikipedia:
 
     Sir Galahad (sometimes referred to as Galeas or Galath),
     in Arthurian legend, is a knight of King Arthur's Round Table and one
@@ -87,32 +45,33 @@ Galaaz is the Portuguese name for "Galahad".  From Wikipedia:
 
 # Galaaz Demo
 
-## Prerequisites
+## Prerequisites (Galaaz 2.0)
 
-* GraalVM (>= rc7)
-* TruffleRuby
-* FastR
+- **JRuby** and a compatible **JDK**
+- **GNU R** on your `PATH`
 
-The following R packages will be automatically installed when necessary, but could be installed prior
-to the demo if desired:
+The following R packages will be automatically installed when necessary,
+but could be installed prior to the demo if desired:
 
-* ggplot2
-* gridExtra
+- ggplot2
+- gridExtra
 
-Installation of R packages requires a development environment.  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. In Linux,
+the gnu compiler and tools should be enough. I am not sure what is
+needed on the Mac.
 
-In order to run the 'specs' the following Ruby package is necessary:
+In order to run the ‘specs’ the following Ruby package is necessary:
 
-* gem install rspec
+- gem install rspec
 
 ## Preparation
 
-* gem install galaaz
+- gem install galaaz
 
 ## Running the demo
 
-The ggplot for this demos was extracted from: http://r-statistics.co/Top50-Ggplot2-Visualizations-MasterList-R-Code.html.
+The ggplot for this demos was extracted from:
+<http://r-statistics.co/Top50-Ggplot2-Visualizations-MasterList-R-Code.html>.
 
 On the console do
 
@@ -124,25 +83,23 @@ Doing on the console
 
     > galaaz -T
 
-will show a list with all available demos.  To run any of the demos in the list,
-substitute the call to
-'rake' to 'galaaz'.  For instance, one of the examples in the list is 'rake sthda:bar'.
-In order to run
-this example just do 'galaaz sthda:bar'.  Doing 'galaaz sthda:all' will run all demos in the sthda
-cathegory.  Some of the examples require 'rspec' do be available.  To install 'rspec' just do
-'gem install rspec'.
+will show a list with all available demos. To run any of the demos in
+the list, substitute the call to ‘rake’ to ‘galaaz’. For instance, one
+of the examples in the list is ‘rake sthda:bar’. In order to run this
+example just do ‘galaaz sthda:bar’. Doing ‘galaaz sthda:all’ will run
+all demos in the sthda cathegory. Some of the examples require ‘rspec’
+do be available. To install ‘rspec’ just do ‘gem install rspec’.
 
 # The demo code
 
+The following is the Ruby code and plot for the above example. There is
+a small difference between the code in the example and the code bellow.
+If the example is ran, the plot will appear on the screen, bellow, we
+generate an ‘svg’ image and then include it in this document. In order
+to generate and image, the R.svg device is used. To generate the plot on
+the screen, use the R.awt device, as commented on the code.
 
-The following is the Ruby code and plot for the above example.  There is a small difference between
-the code in the example and the code bellow.  If the example is ran, the plot will appear on the
-screen, bellow, we generate an 'svg' image and then include it in this document.  In order to
-generate and image, the R.svg device is used.  To generate the plot on the screen, use the R.awt
-device, as commented on the code.
-
-
-```ruby
+``` ruby
 require 'galaaz'
 require 'ggplot'
 
@@ -150,7 +107,7 @@ require 'ggplot'
 R.options(scipen: 999)  # turn-off scientific notation like 1e+48
 R.theme_set(R.theme_bw)  # pre-set the bw theme.
 
-midwest = ~:midwest
+midwest = ~R[:midwest]
 
 # Scatterplot
 gg = midwest.ggplot(E.aes(x: :area, y: :poptotal)) + 
@@ -167,14 +124,11 @@ gg = midwest.ggplot(E.aes(x: :area, y: :poptotal)) +
 puts gg
 ```
 
-
-![](galaaz_ggplot_files/figure-html/midwest_rb.png)<!-- -->
-
+![](galaaz_ggplot_files/figure-markdown_github/midwest_rb.png)
 
 In R, the code to generate this plot is the following
 
-
-```r
+``` r
 # install.packages("ggplot2")
 # load package and data
 options(scipen=999)  # turn-off scientific notation like 1e+48
@@ -198,39 +152,44 @@ gg <- ggplot(midwest, aes(x=area, y=poptotal)) +
 plot(gg)
 ```
 
-Note that both codes are very similar.  The Ruby code requires the use of "R." before calling
-any functions,
-for instance R function 'geom_point' becomes 'R.geom_point' in Ruby.  R named parameters such as
-(col = state, size = popdensity), become in Ruby (col: :state, size: :popdensity).
-
-One last
-point that needs to be observed is the call to the 'aes' function.  In Ruby instead of doing
-'R.aes', we use 'E.aes'.  The explanation of why E.aes is needed is an advanced topic in R and
-depends on what is know as Non-standard Evaluation (NSE) in R.  In short, function 'aes' is lazily
-evaluated in R, i.e., in R when calling geom_point(aes(col=state, size=popdensity)), function
-geom_point receives as argument something similar to a string containing
-'aes(col=state, size=popdensity)', and the aes function will be evaluated inside the geom_point
-function.  In Ruby, there is no Lazy evaluation and doing R.aes would try to evaluate aes
-immediately.  In order to delay the evaluation of function aes we need to use E.aes.  The
-interested reader on NSE in R is directed to http://adv-r.had.co.nz/Computing-on-the-language.html.
+Note that both codes are very similar. The Ruby code requires the use of
+“R.” before calling any functions, for instance R function ‘geom_point’
+becomes ‘R.geom_point’ in Ruby. R named parameters such as (col = state,
+size = popdensity), become in Ruby (col: :state, size: :popdensity).
+
+One last point that needs to be observed is the call to the ‘aes’
+function. In Ruby instead of doing ‘R.aes’, we use ‘E.aes’. The
+explanation of why E.aes is needed is an advanced topic in R and depends
+on what is know as Non-standard Evaluation (NSE) in R. In short,
+function ‘aes’ is lazily evaluated in R, i.e., in R when calling
+geom_point(aes(col=state, size=popdensity)), function geom_point
+receives as argument something similar to a string containing
+‘aes(col=state, size=popdensity)’, and the aes function will be
+evaluated inside the geom_point function. In Ruby, there is no Lazy
+evaluation and doing R.aes would try to evaluate aes immediately. In
+order to delay the evaluation of function aes we need to use E.aes. The
+interested reader on NSE in R is directed to
+<http://adv-r.had.co.nz/Computing-on-the-language.html>.
 
 # An extension to the example
 
-If both codes are so similar, then why would one use Ruby instead of R and what good is galaaz
-after all?
-
-Ruby is a modern OO language with numerous very useful constructs such as classes, modules, blocks,
-procs, etc.  The example above focus on the coupling of both languages, and does not show the
-use of other Ruby constructs.  In the following example, we will show a more complex example using
-other Ruby constructs.  This is certainly not a very well written and robust Ruby code, but
-it give the idea of how Ruby and R are strongly coupled.
+If both codes are so similar, then why would one use Ruby instead of R
+and what good is galaaz after all?
 
-Let's imagine that we work in a corporation that has its plot themes.  So, it has defined a
-'CorpTheme' module.  Plots in this corporation should not have grids, numbers in labels should
-not use scientific notation and the preferred color is blue.
+Ruby is a modern OO language with numerous very useful constructs such
+as classes, modules, blocks, procs, etc. The example above focus on the
+coupling of both languages, and does not show the use of other Ruby
+constructs. In the following example, we will show a more complex
+example using other Ruby constructs. This is certainly not a very well
+written and robust Ruby code, but it give the idea of how Ruby and R are
+strongly coupled.
 
+Let’s imagine that we work in a corporation that has its plot themes.
+So, it has defined a ‘CorpTheme’ module. Plots in this corporation
+should not have grids, numbers in labels should not use scientific
+notation and the preferred color is blue.
 
-```ruby
+``` ruby
 # corp_theme.rb
 # defines the corporate theme for all plots
     
@@ -270,8 +229,7 @@ end
 
 We now define a ScatterPlot class:
 
-
-```ruby
+``` ruby
 # ScatterPlot.rb
 # creates a scatter plot and allow some configuration
     
@@ -363,14 +321,14 @@ class ScatterPlot
 end
 ```
 
-And this is the final code for making the scatter plot with the midwest data
-
+And this is the final code for making the scatter plot with the midwest
+data
 
-```ruby
+``` ruby
 require 'galaaz'
 require 'ggplot'
 
-sp = ScatterPlot.new(~:midwest, x: :area, y: :poptotal)
+sp = ScatterPlot.new(~R[:midwest], x: :area, y: :poptotal)
 sp.title = "Midwest Dataset - Scatterplot"
 sp.subtitle = "Area Vs Population"
 sp.caption = "Source: midwest"
@@ -382,23 +340,25 @@ sp.add_smoothing_line(method: "glm")
 sp.plot
 ```
 
-
-![](galaaz_ggplot_files/figure-html/scatter_plot_rb.png)<!-- -->
+![](galaaz_ggplot_files/figure-markdown_github/scatter_plot_rb.png)
 
 # Conclusion
 
-R is a very powerful language for statistical analysis, data analytics, machine learning, plotting
-and many other scientific applications with a very large package ecosystem.  However R is often
-considered hard to learn and lacking modern computer languages constructs such as object oriented
-classes, modules, lambdas, etc.  For this reason, many developers have started or switched from R
-to Python.
-
-With Galaaz, R programmers can almost transparently migrate from R to Ruby, since syntax is
-almost identical and they have fastR as the R engine.  FastR, by most benchmarks, can be orders of
-magnitude faster than Gnu R.  Further, by using Galaaz the R developer can start (slowly if needed)
-using all of Ruby's constructs and libraries that nicely complement R packages.
-
-For the Ruby developer, Galaaz allows the immediate use of R functions completely transparently. As
-shown in the second example above, class ScatterPlot completely hides all the details an R calls
-from the Ruby developer, furthermore Galaaz is powered by TruffleRuby that can also be orders of
-magnitude faster than MRI Ruby.
+R is a very powerful language for statistical analysis, data analytics,
+machine learning, plotting and many other scientific applications with a
+very large package ecosystem. However R is often considered hard to
+learn and lacking modern computer languages constructs such as object
+oriented classes, modules, lambdas, etc. For this reason, many
+developers have started or switched from R to Python.
+
+With Galaaz, R programmers can almost transparently migrate from R to
+Ruby, since syntax is almost identical and **GNU R** remains the engine
+for statistics and **ggplot2**. Further, by using Galaaz the R developer
+can start (slowly if needed) using Ruby’s constructs and libraries that
+nicely complement R packages.
+
+For the Ruby developer, Galaaz allows the immediate use of R functions
+with minimal ceremony. As shown in the second example above, class
+`ScatterPlot` hides most R call details from the Ruby developer.
+**JRuby** provides **real parallel threads** on the Ruby side and access
+to the JVM ecosystem when you need it.