galaaz 0.4.6 → 0.5.0

data/blogs/galaaz_ggplot/galaaz_ggplot.md

@@ -151,10 +151,6 @@ 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 <- read.csv("http://goo.gl/G1K41K")  # bkup data source
-
-# R.awt  # run the awt device if the plot should show on the screen
-R.svg    # run the svg device if an image should be generated
 
 # Scatterplot
 gg = midwest.ggplot(E.aes(x: :area, y: :poptotal)) + 
@@ -168,19 +164,12 @@ gg = midwest.ggplot(E.aes(x: :area, y: :poptotal)) +
             title: "Scatterplot", 
             caption: "Source: midwest")
 
-R.png('midwest.png')     # this line is not necessary with the awt device
 puts gg
-
-R.dev__off               # R.dev__off turns off the device.  If using awt, the plot
-                         # window will be closed
 ```
 
-```
-## This is the fake output
-```
 
+![](galaaz_ggplot_files/figure-html/midwest_rb.png)<!-- -->
 
-![Midwest Plot](midwest.png){width=70%}
 
 In R, the code to generate this plot is the following
 
@@ -279,10 +268,6 @@ module CorpTheme
 end
 ```
 
-```
-## This is the fake output
-```
-
 We now define a ScatterPlot class:
 
 
@@ -358,9 +343,7 @@ class ScatterPlot
   # Plots the scatterplot
   #---------------------------------------------------------------------------------
 
-  def plot(device = 'awt')
-    device == 'awt' ? R.awt : R.svg
-   
+  def plot
     gg = @data.ggplot(E.aes(x: @x, y: @y)) +
       points + 
       R.geom_smooth(method: @method, se: @confidence) +
@@ -373,19 +356,13 @@ class ScatterPlot
                    caption: @caption) +
       CorpTheme.global_theme
 
-    R.png('scatter_plot.png') if !(device == 'awt')
     puts gg
-    R.dev__off
     
   end
   
 end
 ```
 
-```
-## This is the fake output
-```
-
 And this is the final code for making the scatter plot with the midwest data
 
 
@@ -402,15 +379,11 @@ sp.y_label = "Population"
 sp.group_by(color: :state, size: :popdensity)    # try sp.group_by(color: :state)
 # available methods: "lm", "glm", "loess", "gam"
 sp.add_smoothing_line(method: "glm") 
-# sp.plot('svg')
-puts sp
+sp.plot
 ```
 
-```
-## This is the fake output
-```
 
-![Midwest Plot with 'glm' function and modified theme](scatter_plot.png){width=70%}
+![](galaaz_ggplot_files/figure-html/scatter_plot_rb.png)<!-- -->
 
 # Conclusion
 

data/blogs/galaaz_ggplot/midwest.Rmd

@@ -4,7 +4,7 @@ screen, bellow, we generate an 'svg' image and then include it in this document.
 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 midwest_rb, warning=FALSE}
+```{ruby midwest_rb, warning=FALSE, fig.width = 9.1, fig.height = 9.1}
 require 'galaaz'
 require 'ggplot'
 
@@ -13,10 +13,6 @@ 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 <- read.csv("http://goo.gl/G1K41K")  # bkup data source
-
-# R.awt  # run the awt device if the plot should show on the screen
-R.svg    # run the svg device if an image should be generated
 
 # Scatterplot
 gg = midwest.ggplot(E.aes(x: :area, y: :poptotal)) + 
@@ -30,10 +26,6 @@ gg = midwest.ggplot(E.aes(x: :area, y: :poptotal)) +
             title: "Scatterplot", 
             caption: "Source: midwest")
 
-R.png('midwest.png')     # this line is not necessary with the awt device
 puts gg
-
-R.dev__off               # R.dev__off turns off the device.  If using awt, the plot
-                         # window will be closed
 ```
 

data/blogs/gknit/gknit.Rmd

@@ -4,7 +4,8 @@ author:
     - "Rodrigo Botafogo"
     - "Daniel Mossé - University of Pittsburgh"
 tags: [Tech, Data Science, Ruby, R, GraalVM]
-date: "20/02/2019"
+date: "29/04/2019"
+bibliography: stats.bib
 output:
   pdf_document:
     includes:
@@ -13,6 +14,7 @@ output:
   html_document:
     self_contained: true
     keep_md: true
+biblio-style: apsr
 ---
 
 ```{r setup, echo=FALSE}
@@ -21,7 +23,8 @@ output:
 
 # Introduction
 
-The idea of "literate programming" was first introduced by Donald Knuth in the 1980's.
+The idea of "literate programming" was first introduced by Donald Knuth in the 
+1980's [@Knuth:literate_programming].
 The main intention of this approach was to develop software interspersing macro snippets,
 traditional source code, and a natural language such as English in a document 
 that could be compiled into
@@ -37,19 +40,21 @@ single document or set of documents that when distributed to peers could be reru
 the same output and reports.
 
 The R community has put a great deal of effort in reproducible research.  In 2002, Sweave was
-introduced and it allowed mixing R code with Latex generating high quality PDF documents.  Those
-documents could include the code, the result of executing the code, graphics and text.  This
-contained the whole narrative to reproduce the research.  But Sweave had many problems and in
-2012, Knitr, developed by Yihui Xie from RStudio was released, solving many of the long lasting
-problems from Sweave and including in one single package many extensions and add-on packages that
+introduced and it allowed mixing R code with Latex generating high quality PDF documents.  A
+Sweave document could include code, the results of executing the code, graphics and text 
+such that it contained the whole narrative to reproduce the research.  In
+2012, Knitr, developed by Yihui Xie from RStudio was released to replace Sweave and to
+consolidate in one single package the many extensions and add-on packages that
 were necessary for Sweave.
 
-With Knitr, R markdown was also developed, an extension to the
-Markdown format.  With R markdown and Knitr it is possible to generate reports in a multitude
-of formats such as HTML, markdown, Latex, PDF, dvi, etc.  R markdown also allows the use of
-multiple programming languages in the same document.  In R markdown text is interspersed with
+With Knitr, __R markdown__ was also developed, an extension to the
+Markdown format.  With __R markdown__ and Knitr it is possible to generate reports in a multitude
+of formats such as HTML, markdown, Latex, PDF, dvi, etc.  __R markdown__ also allows the use of
+multiple programming languages such as R, Ruby, Python, etc. in the same document.  
+
+In __R markdown__, text is interspersed with
 code chunks that can be executed and both the code and its results can become
-part of the final report.  Although R markdown allows multiple programming languages in the
+part of the final report.  Although __R markdown__ allows multiple programming languages in the
 same document, only R and Python (with
 the reticulate package) can persist variables between chunks.  For other languages, such as
 Ruby, every chunk will start a new process and thus all data is lost between chunks, unless it
@@ -57,46 +62,76 @@ is somehow stored in a data file that is read by the next chunk.
 
 Being able to persist data
 between chunks is critical for literate programming otherwise the flow of the narrative is lost
-by all the effort of having to save data and then reload it. Probably, because of 
-this impossibility,
-it is very rare to see any R markdown document in the Ruby community.  Also, the use of 
-R markdown for the Ruby community would also require the Ruby developer to download R and 
-have some minimal knowledge of Knitr.
+by all the effort of having to save data and then reload it. Although this might, at first, seem like
+a small nuisance, not being able to persist data between chunks is a major issue. For example, let's
+take a look at the following simple example in which we want to show how to create a list and the
+use it.  Let's first assume that data cannot be persisted between chunks.  In the next chunk we
+create a list, then we would need to save it to file, but to save it, we need somehow to marshal the
+data into a binary format:
+
+```{ruby no_persistence}
+lst = R.list(a: 1, b: 2, c: 3)
+lst.saveRDS("lst.rds")
+```
+then, on the next chunk, where variable 'lst' is used, we need to read back it's value
+
+```{ruby load_persisted_data}
+lst = R.readRDS("lst.rds")
+puts lst
+```
+
+Now, any single code has dozens of variables that we might want to use and reuse between chunks.
+Clearly, such an approach becomes quickly unmanageable. Probably, because of 
+this problem, it is very rare to see any __R markdown__ document in the Ruby community.
+
+When variables can be used accross chunks, then no overhead is needed:
+
+```{ruby persistence}
+lst = R.list(a: 1, b: 2, c: 3)
+# any other code can be added here
+```
+
+```{ruby use_var}
+puts lst
+```
 
 In the Python community, the same effort to have code and text in an integrated environment
 started around the first decade of 2000. In 2006 iPython 0.7.2 was released.  In 2014,
 Fernando Pérez, spun off project Jupyter from iPython creating a web-based interactive
 computation environment.  Jupyter can now be used with many languages, including Ruby with the
-iruby gem (https://github.com/SciRuby/iruby).  I am not sure if multiple languages can be used
-in a Jupyter notebook and if variables can persist between chunks.
+iruby gem (https://github.com/SciRuby/iruby).  In order to have multiple languages in a Jupyter
+notebook the SoS kernel was developed (https://vatlab.github.io/sos-docs/).
 
 # gKnitting a Document
 
-This document describes gKnit.  gKnit uses Knitr and R markdown to knit a document in Ruby or R
-and output it in any of the available formats for R markdown.  
+This document describes gKnit.  gKnit is based on knitr and __R markdown__ and can knit a document 
+written both in Ruby and/or R and output it in any of the available formats of __R markdown__.  gKnit
+allows ruby developers to do literate programming and reproducible research by allowing them to
+have in a single document, text and code.
+
 gKnit runs atop of GraalVM, and Galaaz (an integration 
-library between Ruby and R).  In gKnit, Ruby variables are persisted between chunks, making 
-it an ideal solution for literate programming in this language.  Also, since it is based on 
-Galaaz, Ruby chunks can have access to R variables and Polyglot Programming with Ruby and R
-is quite natural.
+library between Ruby and R - see bellow).  In gKnit, Ruby variables are persisted between 
+chunks, making  it an ideal solution for literate programming in this language.  Also, 
+since it is based on  Galaaz, Ruby chunks can have access to R variables and Polyglot Programming 
+with Ruby and R is quite natural.
 
-Galaaz has been describe already in the following posts:
+Galaaz has already been describe in the following posts:
 
 * https://towardsdatascience.com/ruby-plotting-with-galaaz-an-example-of-tightly-coupling-ruby-and-r-in-graalvm-520b69e21021.  
 * https://medium.freecodecamp.org/how-to-make-beautiful-ruby-plots-with-galaaz-320848058857
 
-This is not a blog post on R markdown, and the interested user is directed to the following links
+This is not a blog post on __R markdown__, and the interested user is directed to the following links
 for detailed information on its capabilities and use.
 
 * https://rmarkdown.rstudio.com/ or
 * https://bookdown.org/yihui/rmarkdown/ 
 
-Here, we will describe quickly the main aspects of R markdown, so the user can start gKnitting
-Ruby and R documents quickly.
+In this post, we will describe just the main aspects of __R markdown__, so the user can start 
+gKnitting Ruby and R documents quickly.
 
 ## The Yaml header
 
-An R markdown document should start with a Yaml header and be stored in a file with 
+An __R markdown__ document should start with a Yaml header and be stored in a file with 
 '.Rmd' extension. This document has the following header for gKitting an HTML document.
 
 ```
@@ -120,7 +155,7 @@ output:
 
 For more information on the options in the Yaml header, check https://bookdown.org/yihui/rmarkdown/html-document.html.
 
-## R Markdown formatting
+## __R Markdown__ formatting
 
 Document formatting can be done with simple markups such as:
 
@@ -156,7 +191,7 @@ Ordered Lists
     + Item 3b
 ```
 
-Please, go to https://rmarkdown.rstudio.com/authoring_basics.html, for more R markdown formatting.
+For more R markdown formatting go to https://rmarkdown.rstudio.com/authoring_basics.html.
 
 ### R chunks
 
@@ -172,8 +207,7 @@ any optional chunk_label and options, as shown bellow:
 ````
 
 for instance, let's add an R chunk to the document labeled 'first_r_chunk'.  This is
-a very simple code just to create a variable and print it out.  The code block should
-be defined as follows:
+a very simple code just to create a variable and print it out, as follows:
 
 ````
 ```{r first_r_chunk}`r ''`
@@ -182,7 +216,7 @@ print(vec)
 ```
 ````
 
-If this block is added to an R markdown document and gKnitted the result will be:
+If this block is added to an __R markdown__ document and gKnitted the result will be:
 
 ```{r first_r_chunk}
 vec <- c(1, 2, 3)
@@ -208,9 +242,9 @@ vec3 <- vec * vec2
 print(vec3)     
 ```
 
-A description of the available chunk options can be found in the documentation cited above.
+A description of the available chunk options can be found in https://yihui.name/knitr/.
 
-Let's add another R chunkd with a function definition.  In this example, a vector 
+Let's add another R chunk with a function definition.  In this example, a vector 
 'r_vec' is created and
 a new function 'reduce_sum' is defined.  The chunk specification is
 
@@ -224,8 +258,8 @@ reduce_sum <- function(...) {
 ```
 ````
 
-and this is how it will look like once executed.  From now on, we will not 
-show the chunk definition any longer.
+and this is how it will look like once executed.  From now on, to be concise in the
+presentation we will not show chunk definitions any longer.
 
 
 ```{r data_creation}
@@ -249,6 +283,24 @@ this document.  Note that there is no directive in the code to include the image
 occurs automatically.  The 'mpg' dataframe is natively available to R and to Galaaz as
 well.
 
+For the reader not knowledgeable of ggplot, ggplot is a graphics library based on "the
+grammar of graphics" [@Wilkinson:grammar_of_graphics]. The idea of the grammar of graphics
+is to build a graphics by adding layers to the plot.  More information can be found in
+https://towardsdatascience.com/a-comprehensive-guide-to-the-grammar-of-graphics-for-effective-visualization-of-multi-dimensional-1f92b4ed4149.
+
+In the plot bellow the 'mpg' dataset from base R is used. "The data concerns city-cycle fuel 
+consumption in miles per gallon, to be predicted in terms of 3 multivalued discrete and 5 
+continuous attributes." (Quinlan, 1993)
+
+First, the 'mpg' dataset if filtered to extract only cars from the following manumactures: Audi, Ford,
+Honda, and Hyundai and stored in the 'mpg_select' variable.  Then, the selected dataframe is passed
+to the ggplot function specifying in the aesthetic method (aes) that 'displacement' (disp) should
+be plotted in the 'x' axis and 'city mileage' should be on the 'y' axis.  In the 'labs' layer we
+pass the 'title' and 'subtitle' for the plot.  To the basic plot 'g', geom\_jitter is added, that
+plots cars from the same manufactures with the same color (col=manufactures) and the size of the
+car point equal its high way consumption (size = hwy).  Finally, a last layer is plotter containing
+a linear regression line (method = "lm") for every manufacturer.
+
 ```{r bubble, dev='png'}
 # load package and data
 library(ggplot2)
@@ -262,9 +314,8 @@ g <- ggplot(mpg_select, aes(displ, cty)) +
   labs(subtitle="mpg: Displacement vs City Mileage",
        title="Bubble chart")
 
-g <- g + geom_jitter(aes(col=manufacturer, size=hwy)) + 
-     geom_smooth(aes(col=manufacturer), method="lm", se=F)
-
+g + geom_jitter(aes(col=manufacturer, size=hwy)) + 
+  geom_smooth(aes(col=manufacturer), method="lm", se=F)
 ```
 
 ### Ruby chunks
@@ -282,37 +333,37 @@ available to R chunks.  Future versions will add those options.
 
 In this example, the ruby chunk is called 'first_ruby_chunk'.  One important 
 aspect of chunk labels is that they cannot be duplicated.  If a chunk label is 
-duplicated, gKnitting will stop with an error.
+duplicated, gKnit will stop with an error.
+
+In the following chunk, variable 'a', 'b' and 'c' are standard Ruby variables 
+and 'vec' and 'vec2' are two vectors created  by calling the 'c' method on the 
+R module.
 
-Another relevant point with Ruby chunks is that they are evaluated in the scope
-of a class called RubyChunk.  To make sure that variables are
-available between chunks, they should be made as instance variables of the 
-RubyChunk class.  In the following chunk, variable '\@a', '\@b' and '\@c' 
-are standard Ruby variables and '\@vec' and '\@vec2' are two vectors created 
-by calling the 'c' method on the R module.
+In Galaaz, the R module allows us to access R functions transparently.  The 'c' 
+function in R, is a function that concatenates its arguments making a vector.
 
-In Galalaaz, the R module allows us to access R functions transparently.  It 
+It 
 should be clear that there is no requirement in gknit to call or use any R 
 functions.  gKnit will knit standard Ruby code, or even general text without 
 any code.
 
 ```{ruby split_data}
-@a = [1, 2, 3]
-@b = "US$ 250.000"
-@c = "The 'outputs' function"
+a = [1, 2, 3]
+b = "US$ 250.000"
+c = "The 'outputs' function"
 
-@vec = R.c(1, 2, 3)
-@vec2 = R.c(10, 20, 30)
+vec = R.c(1, 2, 3)
+vec2 = R.c(10, 20, 30)
 ```
 
-In this next block, variables '\@a', '\@vec' and '\@vec2' are used and printed.
+In the next block, variables 'a', 'vec' and 'vec2' are used and printed.
 
 ```{ruby split2}
-puts @a
-puts @vec * @vec2
+puts a
+puts vec * vec2
 ```
 
-Note that @a is a standard Ruby Array and @vec and @vec2 are vectors that behave accordingly,
+Note that 'a' is a standard Ruby Array and 'vec' and 'vec2' are vectors that behave accordingly,
 where multiplication works as expected.
 
 
@@ -338,18 +389,57 @@ puts R.reduce_sum(~:r_vec)
 ### Ruby Plotting
 
 We have seen an example of plotting with R.  Plotting with Ruby does not require
-anything different from plotting with R:
+anything different from plotting with R.  In the following example, we plot a 
+diverging bar graph using the 'mtcars' dataframe from R.  This data was extracted 
+from the 1974 Motor Trend US magazine, and comprises fuel consumption and 10 aspects 
+of automobile design and performance for 32 automobiles (1973–74 models).  The 
+ten aspects are:
+
+* mpg:	Miles/(US) gallon
+* cyl:	Number of cylinders
+* disp:	Displacement (cu.in.)
+* hp:	Gross horsepower
+* drat:	Rear axle ratio
+* wt:	Weight (1000 lbs)
+* qsec:	1/4 mile time
+* vs:	Engine (0 = V-shaped, 1 = straight)
+* am:	Transmission (0 = automatic, 1 = manual)
+* gear:	Number of forward gears
+* carb:	Number of carburetors
+
+
+```{ruby diverging_plot_pre}
+# copy the R variable :mtcars to the Ruby mtcars variable
+mtcars = ~:mtcars
 
-```{ruby diverging_bar, fig.width = 9.1, fig.height = 6.5}
-require 'ggplot'
+# create a new column 'car_name' to store the car names so that it can be
+# used for plotting. The 'rownames' of the data frame cannot be used as
+# data for plotting
+mtcars.car_name = R.rownames(:mtcars)
 
-mtcars = ~:mtcars
+# compute normalized mpg and add it to a new column called mpg_z
+# Note that the mean value for mpg can be obtained by calling the 'mean'
+# function on the vector 'mtcars.mpg'.  The same with the standard
+# deviation 'sd'.  The vector is then rounded to two digits with 'round 2'
+mtcars.mpg_z = ((mtcars.mpg - mtcars.mpg.mean)/mtcars.mpg.sd).round 2
+
+# create a new column 'mpg_type'. Function 'ifelse' is a vectorized function
+# that looks at every element of the mpg_z vector and if the value is below
+# 0, returns 'below', otherwise returns 'above'
+mtcars.mpg_type = (mtcars.mpg_z < 0).ifelse("below", "above")
 
-mtcars.car_name = mtcars.rownames  # create new column for car names
-mtcars.mpg_z = ((mtcars.mpg - mtcars.mpg.mean) / mtcars.mpg.sd).round 2
-mtcars.mpg_type = (mtcars.mpg_z < 0).ifelse('below', 'above')
+# order the mtcar data set by the mpg_z vector from smaler to larger values
 mtcars = mtcars[mtcars.mpg_z.order, :all]
-mtcars.car_name = R.factor(mtcars.car_name, levels: mtcars.car_name)
+
+# convert the car_name column to a factor to retain sorted order in plot
+mtcars.car_name = mtcars.car_name.factor levels: mtcars.car_name
+
+# let's look at the first records of the final data frame
+puts mtcars.head
+```
+
+```{ruby diverging_bar, fig.width = 9.1, fig.height = 6.5}
+require 'ggplot'
 
 puts mtcars.ggplot(E.aes(x: :car_name, y: :mpg_z, label: :mpg_z)) +
      R.geom_bar(E.aes(fill: :mpg_type), stat: 'identity', width: 0.5) +
@@ -363,69 +453,70 @@ puts mtcars.ggplot(E.aes(x: :car_name, y: :mpg_z, label: :mpg_z)) +
 
 ### Inline Ruby code
 
-When using a Ruby chunk, the code and the output are formated in blocks as seen above.
-This formatting is not always desired.  Sometimes, one wants to have the result of the
-Ruby evalutaion included in the middle of a phrase. gKnit allows adding inline Ruby code 
-with the 'rb' engine.  The following text will 
+When using a Ruby chunk, the code and the output are formatted in blocks as seen above.
+This formatting is not always desired.  Sometimes, we want to have the results of the
+Ruby evaluation included in the middle of a phrase. gKnit allows adding inline Ruby code 
+with the 'rb' engine.  The following chunk specification will 
 create and inline Ruby text:
 
 ````
-This is some text with inline Ruby accessing variable \@b which has value:
-```{rb puts "```{rb puts @b}\n```"}
+This is some text with inline Ruby accessing variable 'b' which has value:
+```{rb puts "```{rb puts b}\n```"}
 ```
 and is followed by some other text!
 ````
 
-Note that it is important not to add any new line before of after the code
-block if we want everything to be in only one line, resulting in the following sentence 
-with inline Ruby code
-
 <div style="margin-bottom:30px;">
 </div>
 
-This is some text with inline Ruby accessing variable \@b which has value:
-```{rb puts @b}
+This is some text with inline Ruby accessing variable 'b' which has value:
+```{rb puts b}
 ```
 and is followed by some other text!
 
 <div style="margin-bottom:30px;">
 </div>
 
+Note that it is important not to add any new line before of after the code
+block if we want everything to be in only one line, resulting in the following sentence 
+with inline Ruby code.
+
 
 ```{ruby heading, echo = FALSE}
-outputs "### #{@c}"
+outputs "### #{c}"
 ```
 
-He have previously used the standard 'puts' method in Ruby chunks in order to get some
-output.  As can be seen, the result of a 'puts' is formatted inside a white box that 
+He have previously used the standard 'puts' method in Ruby chunks in order produce
+output.  The result of a 'puts', as seen in all previous chunks that use it,  is formatted 
+inside a white box that 
 follows the code block. Many times however, we would like to do some processing in the 
 Ruby chunk and have the result of this processing generate and output that is 
-'included' in the document as if we had typed it in R markdown.  
+"included" in the document as if we had typed it in __R markdown__ document.
 
-For example, suppose we want to create a new 'heading' in our document, but the heading 
+For example, suppose we want to create a new heading in our document, but the heading 
 phrase is the result of some code processing: maybe it's the first line of a file we are
-going to read.  Method 'outputs' adds its output as if typed in the R markdown document. 
+going to read.  Method 'outputs' adds its output as if typed in the __R markdown__ document. 
 
-Take now a look at variable '@c' (it was defined in a previous block above) as 
-'@c = "The 'outputs' function".  "The 'outputs' function" is actually the name of this
+Take now a look at variable 'c' (it was defined in a previous block above) as 
+'c = "The 'outputs' function".  "The 'outputs' function" is actually the name of this
 section and it was created using the 'outputs' function inside a Ruby chunk.
 
 The ruby chunk to generate this heading is:
 
 ````
 ```{ruby heading}`r ''`
-outputs "### #{@c}"
+outputs "### #{c}"
 ```
 ````
 
-The three '###' are the way we add a Heading 3 in R markdown.
+The three '###' is the way we add a Heading 3 in __R markdown__.
 
 
 ### HTML Output from Ruby Chunks
 
-We've just seen the use of method 'outputs' to add text to the the R markdown 
-document.  This technique can also be used to add HTML code to the document. In R 
-markdown any html code typed directly in the document will be properly rendered.  
+We've just seen the use of method 'outputs' to add text to the the __R markdown__ 
+document.  This technique can also be used to add HTML code to the document. In 
+__R markdown__, any html code typed directly in the document will be properly rendered.  
 Here, for instance, is a table definition in HTML and its output in the document:
 
 ```
@@ -471,51 +562,52 @@ Here, for instance, is a table definition in HTML and its output in the document
 <div style="margin-bottom:30px;">
 </div>
 
-But manually creating HTML output is not always easy or desirable. The above 
-table certainly looks ugly.  The 'kableExtra' library is a great library for 
+But manually creating HTML output is not always easy or desirable, specially
+if we intend the document to be rendered in other formats, for example, as Latex.
+Also, The above 
+table looks ugly.  The 'kableExtra' library is a great library for 
 creating beautiful tables. Take a look at https://cran.r-project.org/web/packages/kableExtra/vignettes/awesome_table_in_html.html
 
 In the next chunk, we output the 'mtcars' dataframe from R in a nicely formatted 
 table.  Note that we retrieve the mtcars dataframe by using '~:mtcars'.
 
 ```{ruby nice_table}
-R.library('kableExtra')
+R.install_and_loads('kableExtra')
 outputs (~:mtcars).kable.kable_styling
 ```
 
-### Including Ruby files
+### Including Ruby files in a chunk
 
 R is a language that was created to be easy and fast for statisticians to use.  As far
-as I know (and please correct me if you think otherwise), tt was not a
+as I know, it was not a
 language to be used for developing large systems.  Of course, there are large systems and
 libraries in R, but the focus of the language is for developing statistical models and
 distribute that to peers.
 
 Ruby on the other hand, is a language for large software development.  Systems written in
-Ruby will have dozens, hundreds or even thousands of files.  In order to document a 
-large system with
-literate programming we cannot expect the developer to add all the files in a single '.Rmd'
-file.  gKnit provides the 'include' chunk engine to include a Ruby file as if it had being
-typed in the '.Rmd' file.
+Ruby will have dozens, hundreds or even thousands of files.  To document a 
+large system with literate programming, we cannot expect the developer to add all the 
+files in a single '.Rmd' file.  gKnit provides the 'include' chunk engine to include 
+a Ruby file as if it had being typed in the '.Rmd' file.
 
 To include a file, the following chunk should be created, where <filename> is the name of
-the file to be include and where the extension, if it is '.rb', does not need to be added.
+the file to be included and where the extension, if it is '.rb', does not need to be added.
 If the 'relative' option is not included, then it is treated as TRUE.  When 'relative' is
-true, 'require_relative' semantics is used to load the file, when false, Ruby's \$LOAD_PATH
-is searched to find the file and it is 'require'd.
+true, ruby's 'require\_relative' semantics is used to load the file, when false, Ruby's 
+\$LOAD_PATH is searched to find the file and it is 'require'd.
 
 ````
 ```{include <filename>, relative = <TRUE/FALSE>}`r ''`
 ```
 ````
 
-Here we include file 'model.rb' which is in the same directory of this blog.  
+Bellow we include file 'model.rb', which is in the same directory of this blog.  
 This code uses R 'caret' package to split a dataset in a train and test sets.
 The 'caret' package is a very important a useful package for doing Data Analysis,
 it has hundreds of functions for all steps of the Data Analysis workflow.  To
-just split a dataset it is using the proverbial cannon to kill the fly.  We use
-it here only to show that integrating Ruby and R and using even a very comples
-package as 'caret' is trivial with Galaaz.
+use 'caret' just to split a dataset is like using the proverbial cannon to 
+kill the fly.  We use it here only to show that integrating Ruby and R and 
+using even a very complex package as 'caret' is trivial with Galaaz.
 
 A word of advice: the 'caret' package has lots of dependencies and installing
 it in a Linux system is a time consuming operation.  Method 'R.install_and_loads'
@@ -540,10 +632,11 @@ puts model.test.head
 ### Documenting Gems
 
 gKnit also allows developers to document and load files that are not in the same directory
-of the '.Rmd' file.  When using 'relative = FALSE' in a chunk header, gKnit will look for the
-file in Ruby's \$LOAD_PATH and load it if found.
+of the '.Rmd' file.
 
-Here is an example of loading the 'find.rb' file from TruffleRuby.
+Here is an example of loading the 'find.rb' file from TruffleRuby. In this example, relative
+is set to FALSE, so Ruby will look for the file in its $LOAD\_PATH, and the user does not
+need to no it's directory.
 
 ````
 ```{include find, relative = FALSE}`r ''`
@@ -556,7 +649,7 @@ Here is an example of loading the 'find.rb' file from TruffleRuby.
 ## Converting to PDF
 
 One of the beauties of knitr is that the same input can be converted to many different outputs.
-One very useful format, is, of course, PDF.  In order to converted an R markdown file to PDF
+One very useful format, is, of course, PDF.  In order to converted an __R markdown__ file to PDF
 it is necessary to have LaTeX installed on the system.  We will not explain here how to
 install LaTeX as there are plenty of documents on the web showing how to proceed.
 
@@ -570,27 +663,39 @@ author: "Rodrigo Botafogo"
 tags: [Galaaz, Ruby, R, TruffleRuby, FastR, GraalVM, knitr, gknit]
 date: "29 October 2018"
 output:
-  pdf_document:
+  pdf\_document:
     includes:
-      in_header: ["../../sty/galaaz.sty"]
-    number_sections: yes
+      in\_header: ["../../sty/galaaz.sty"]
+    number\_sections: yes
 ---
 ```
 
+
 # Conclusion
 
-One of the promises of GraalVM is that users/developers will be able to use the best tool
-for their task at hand, independently of the programming language the tool was written.  Galaaz
-and gKnit are not trivial implementations atop the GraalVM and Truffle interop messages;
-however, the time and effort it took to wrap Ruby over R - Galaaz - (not finished yet) or to
-wrap Knitr with gKnit is a fraction of a fraction of a fraction of the time require to
+In order to do reproducible research, one of the main basic tools needed is a systhem that
+allows "literate programming" where text, code and possibly a set of files can be compiled
+onto a report that can be easily distributed to peers. Peers should be able to use this
+same set of files to rerun the compilation by their own obtaining the exact same original
+report.  gKnit is such a system for Ruby and R.  It uses __R Markdown__ to integrate
+text and code chunks, where code chunks can either be part of the __R Markdwon__ file or
+be imported from files in the system.  Ideally, in reproducible research, all the files
+needed to rebuild a report should be easilly packed together (in the same zipped directory)
+and distributed to peers for reexecution.
+
+One of the promises of Oracle's GraalVM is that users/developers will be able to use the best tool
+for their task at hand, independently of the programming language the tool was written on.
+We developed and implemented Galaaz atop the GraalVM and Truffle interop messages and
+the time and effort to wrap Ruby over R - Galaaz - or to
+wrap Knitr with gKnit was a fraction of a fraction of a fraction (one man effort for a couple
+of hours a day, for approximately six months) of the time require to
 implement the original tools.  Trying to reimplement all R packages in Ruby would require the
-same effort it is taking Python to implement NumPy, Panda and all supporting libraries and it
+same effort it is taking Python to implement NumPy, Pandas and all supporting libraries and it
 is unlikely that this effort would ever be done.  GraalVM has allowed Ruby to profit "almost
 for free" from this huge set of libraries and tools that make R one of the most used
 languages for data analysis and machine learning.
 
-More interesting though than being able to wrap the R libraries with Ruby, is that Ruby adds
+More interesting than wrapping the R libraries with Ruby, is that Ruby adds
 value to R, by allowing developers to use powerful and modern constructs for code reuse that
 are not the strong points of R.  As shown in this blog, R and Ruby can easily communicate
 and R can be structured in classes and modules in a way that greatly expands its power and
@@ -621,3 +726,7 @@ the gnu compiler and tools should be enough.  I am not sure what is needed on th
 ## Usage
 
 * gknit \<filename\>
+
+
+# References
+