galaaz 0.4.6 → 0.5.0

data/blogs/ruby_plot/ruby_plot.md

@@ -121,10 +121,7 @@ Ruby and dozens of other languages.  Yet, while R and Python chunks can share da
 languages, chunks are independent.  This means that a variable defined in one chunk
 cannot be used in another chunk.
 
-With _gKnit_ Ruby code chunks can share data.  In gKnit each
-Ruby chunk executes in its own scope and thus, local variable defined in a chunk are
-not accessible by other chunks.  Yet, All chunks execute in the scope of a 'chunk'
-class and instance variables ('@'), are available in all chunks.
+With _gKnit_ Ruby code chunks can share data.
 
 # Exploring the Dataset
 
@@ -139,10 +136,28 @@ 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
-following chunk that 'ToothGrowth' is the R  variable and Ruby's '@tooth_growth' is
+following chunk that 'ToothGrowth' is the R  variable and Ruby's 'tooth_growth' is
 assigned the value of '~:ToothGrowth'.
 
 
+```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
+# print the first few elements of the dataset
+puts tooth_growth.head
+```
+
+```
+##    len supp dose
+## 1  4.2   VC  0.5
+## 2 11.5   VC  0.5
+## 3  7.3   VC  0.5
+## 4  5.8   VC  0.5
+## 5  6.4   VC  0.5
+## 6 10.0   VC  0.5
+```
 
 Great! We've managed to read the ToothGrowth dataset and take a look at its elements.
 We see here the first 6 rows of the dataset. To access a column, follow the dataset name
@@ -150,6 +165,15 @@ with a dot ('.') and the name of the column. Also use dot notation to chain meth
 in usual Ruby style.
 
 
+```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
+```
+
+```
+## [1]  4.2 11.5  7.3  5.8  6.4 10.0
+```
  
 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
@@ -159,11 +183,22 @@ 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
+# convert the dose to a factor
+tooth_growth.dose = tooth_growth.dose.as__factor
+```
 
 Let's explore some more details of this dataset.  In particular, let's look at its dimensions,
 structure and summary statistics.
 
 
+```ruby
+puts tooth_growth.dim
+```
+
+```
+## [1] 60  3
+```
 
 This dataset has 60 rows, one for each subject and 3 columns, as we have already seen.
 
@@ -172,12 +207,35 @@ functions does not return anything and prints the structure of the dataset
 as a side effect.
 
 
+```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
+puts tooth_growth.summary
+```
+
+```
+##       len        supp     dose   
+##  Min.   : 4.20   OJ:30   0.5:20  
+##  1st Qu.:13.07   VC:30   1  :20  
+##  Median :19.25           2  :20  
+##  Mean   :18.81                   
+##  3rd Qu.:25.27                   
+##  Max.   :33.90
+```
 
 # Doing the Data Analysis
 
@@ -198,27 +256,22 @@ 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 s
-pecification bellow, we use the second notation
-that looks more like Ruby.  ggplot uses the ‘aes’ method to specify
+either ```R.ggplot(<dataset>, ...)``` or ```<dataset>.ggplot(...)```.  In the graph 
+specification bellow, 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
 the plot.  For a boxplot, the geom is R.geom_boxplot.
 
-Note also that we have a call to 'R.png' before plotting and 'R.dev__off' after the print
-statement.  'R.png' opens a 'png device' for outputting the plot.  If we do no pass a
-name to the 'png' function, the
-image gets a default name of 'Rplot\<nnn\>' where \<nnn\> is the number of the plot.
-'R.dev__off'
-closes the device and creates the 'png' file. We can
-then include the generated 'png' file in the document by adding an rmarkdown directive.
 
-<img src="/home/rbotafogo/desenv/galaaz/blogs/ruby_plot/ruby_plot_files/figure-html/dose_len.svg" width="50%" />
+```ruby
+require 'ggplot'
 
-[//]: # (Including the 'png' file generated above.  In future releases)
-[//]: # (of gKnit, the figures should be automatically saved and the name)
-[//]: # (taken from the chunk 'label' and possibly chunk parameters)
+e = tooth_growth.ggplot(E.aes(x: :dose, y: :len))
+print e + R.geom_boxplot
+```
 
+![](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
@@ -239,24 +292,32 @@ automatically creates the facets based on the delivery method factors.  The para
 the 'facet_grid' method is a [_formula_](https://thomasleeper.com/Rcourse/Tutorials/formulae.html).
 
 In Galaaz we give programmers the flexibility to use two different ways to write formulas.
-In the first way, the following changes from writing formulas (for example 'x ~ y')
-in R are necessary:
+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 symbols are represented by the same Ruby symbol prefixed with the '+' method. The
-  symbol ```x``` in R becomes ```+:x``` in Ruby;
-* The '~' operator in R becomes '=~' in Ruby.  The formula ```x ~ y``` in R is written as
-  ```+:x =~ +:y``` in Ruby;
-* The '.' symbol in R becomes '+:all'
 
 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 =~ +:supp``` indicates to the 'facet_grid' function that it needs to
+The formula ```: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 =~ +:all``` would split the plot horizontally.
+the formula to ```:supp.til :all``` would split the plot horizontally.
+
 
+```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)
+      
+puts bp
+```
+
+
+![](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
@@ -273,6 +334,13 @@ enough to add ```fill: :dose``` to the aesthetic of boxplot.  With this command
 factor gets its own color.
 
 
+```ruby
+bp = bp + R.geom_boxplot(E.aes(fill: :dose))
+puts bp
+```
+
+
+![](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.
@@ -304,6 +372,15 @@ each of the 60 pigs in the experiment.  For that, add the function 'R.geom_point
 plot.
 
 
+```ruby
+# Split in vertical direction
+bp = bp + R.geom_point
+
+puts bp
+```
+
+
+![](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
@@ -317,6 +394,13 @@ prevents data hiding.  We also add
 color and change the shape of the points, making them even easier to see.
 
 
+```ruby
+# Split in vertical direction
+puts bp + R.geom_jitter(shape: 23, color: "cyan3", size: 1)
+```
+
+
+![](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.
@@ -352,6 +436,16 @@ This ordering seems more natural and
 matches with the actual order of the colors in the plot.
 
 
+```ruby
+bp = bp +
+     R.scale_fill_manual(values: R.c("cyan", "deepskyblue", "deepskyblue4"),
+                          breaks: R.c("2","1","0.5"))
+
+puts bp
+```
+
+
+![](ruby_plot_files/figure-html/facets_by_delivery_color2.png)<!-- -->
 
 ## Violin Plot and Jitter
 
@@ -371,6 +465,18 @@ a boxplot known as a _violin plot_ with jittered data.
 > The central dot represents the median average value. 
 
 
+```ruby
+violin = base_tooth + R.geom_violin(E.aes(fill: :dose)) + 
+   R.facet_grid(: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"))
+
+puts violin
+```
+
+
+![](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
@@ -391,6 +497,23 @@ for information about the plot (for clarity, we defined a caption variable using
 Here Doc style).
 
 
+```ruby
+caption = <<-EOT
+Length of odontoblasts in 60 guinea pigs. 
+Each animal received one of three dose levels of vitamin C.
+EOT
+
+decorations =
+  R.labs(title: "Tooth Growth:  Length vs Vitamin C Dose",
+         subtitle: "Faceted by delivery method, OJ or VC",
+         x: "Dose (mg)", y: "Teeth length",
+         caption: caption)
+
+puts bp + decorations
+```
+
+
+![](ruby_plot_files/figure-html/facets_with_decorations.png)<!-- -->
 
 ## The Corp Theme
 
@@ -408,6 +531,57 @@ a shade o blue (color: '#00080').  Axis labels are moved near the end of the axi
 written in 'bold'.
 
 
+```ruby
+module CorpTheme
+
+  R.install_and_loads 'RColorBrewer'
+  
+  #---------------------------------------------------------------------------------
+  # face can be  (1=plain, 2=bold, 3=italic, 4=bold-italic)
+  #---------------------------------------------------------------------------------
+  
+  def self.text_element(size, face: "plain", hjust: nil)
+    E.element_text(color: "#000080", 
+                   face: face,
+                   size: size,
+		   hjust: hjust)
+  end
+  
+  #---------------------------------------------------------------------------------
+  # Defines the plot theme (visualization).  In this theme we remove major and minor
+  # grids, borders and background.  We also turn-off scientific notation.
+  #---------------------------------------------------------------------------------
+  
+  def self.global_theme(faceted = false)
+    
+    R.options(scipen: 999)  # turn-off scientific notation like 1e+48
+    #    R.theme_set(R.theme_bw)
+    
+    # remove major grids
+    gb = R.theme(panel__grid__major: E.element_blank())
+    # remove minor grids
+    gb = gb + R.theme(panel__grid__minor: E.element_blank)
+    # gb = R.theme(panel__grid__minor: E.element_blank)
+    # remove border
+    gb = gb + R.theme(panel__border: E.element_blank)
+    # remove background. When working with faceted graphs, the background makes
+    # it easier to see each facet, so leave it
+    gb = gb + R.theme(panel__background: E.element_blank) if !faceted
+    # Change axis font
+    gb = gb + R.theme(axis__text: text_element(8))
+    # change axis title font
+    gb = gb + R.theme(axis__title: text_element(10, face: "bold", hjust: 1))
+    # change font of title
+    gb = gb + R.theme(title: text_element(12, face: "bold"))
+    # change font of subtitle
+    gb = gb + R.theme(plot__subtitle: text_element(9))
+    # change font of captions
+    gb = gb + R.theme(plot__caption: text_element(8))
+
+  end
+   
+end
+```
 
 ## Final Box Plot
 
@@ -415,17 +589,29 @@ We can now easily make our final boxplot and violin plot.  All the layers for th
 added in order to expose our understanding of the data and the need to present the result
 to our audience.
 
-The final specification is just the addition of all layers build up to this point (@bp), plus
-the decorations (@decorations), plus the corporate theme.
+The final specification is just the addition of all layers build up to this point ('bp'), plus
+the decorations ('decorations'), plus the corporate theme.
 
 Here is our final boxplot, without jitter.
 
 
+```ruby
+puts bp + decorations + CorpTheme.global_theme(faceted: true)
+```
+
+
+![](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
+puts violin + decorations + CorpTheme.global_theme(faceted: true)
+```
+
+
+![](ruby_plot_files/figure-html/final_violin_plot.png)<!-- -->
 
 ## Another View
 
@@ -434,6 +620,26 @@ 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
+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.scale_fill_manual(values: R.c("cyan", "deepskyblue4")) +
+     R.labs(title: "Tooth Growth:  Length by Dose",
+            subtitle: "Faceted by dose",
+            x: "Delivery method", y: "Teeth length",
+            caption: caption) +
+     CorpTheme.global_theme(faceted: true)
+
+puts bp
+```
+
+
+![](ruby_plot_files/figure-html/facet_by_dose.png)<!-- -->
 
 # Conclusion
 
@@ -449,10 +655,9 @@ Trying to bring to Ruby the power of R starting from scratch is an enourmous end
 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.
+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 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)

data/examples/Bibliography/master.bib

@@ -0,0 +1,50 @@
+% This file was created with JabRef 2.10.
+% Encoding: UTF-8
+
+@Book{vasquez2009twp,
+  Title                    = {The War Puzzle Revisited},
+  Author                   = {Vasquez, John A},
+  Publisher                = {New York, NY: Cambridge University Press},
+  Year                     = {2009}
+}
+
+@Book{wagner2007ws,
+  Title                    = {War and the State: The Theory of International Politics},
+  Author                   = {R. Harrison Wagner},
+  Publisher                = {Ann Arbor, MI: The University of Michigan Press},
+  Year                     = {2007},
+  Owner                    = {steve},
+  Timestamp                = {2016.02.12}
+}
+
+@Book{xie2013ddrk,
+  title = {Dynamic Documents with {R} and knitr},
+  author = {Yihui Xie},
+  publisher = {Chapman and Hall/CRC},
+  address = {Boca Raton, Florida},
+  year = {2015},
+  edition = {2nd},
+  note = {ISBN 978-1498716963},
+  url = {https://yihui.name/knitr/},
+}
+
+@article{miller2013tdpi,
+   author = {Miller, Steven V.},
+   year = 2013,
+   title = {Territorial Disputes and the Politics of Individual Well-Being.},
+   journal = {Journal of Peace Research.},
+   volume = 50,
+   number = 6,
+   pages = {677-690}
+}
+
+@article{miller2016ieea,
+   author = {Gibler, Douglas M. and Steven V. Miller and Erin K. Little},
+   year = 2016,
+   title = {An Analysis of the Militarized Interstate Dispute (MID) Dataset, 1816-2001},
+   journal = {International Studies Quarterly.},
+   volume = 60,
+   number = 4,
+   pages = {719-730}
+}
+