galaaz 2.1.7 → 2.1.8

data/blogs/gknit/gknit.tex

@@ -0,0 +1,1368 @@
+% Options for packages loaded elsewhere
+\PassOptionsToPackage{unicode}{hyperref}
+\PassOptionsToPackage{hyphens}{url}
+\documentclass[
+]{article}
+\usepackage{xcolor}
+\usepackage[margin=1in]{geometry}
+\usepackage{amsmath,amssymb}
+\setcounter{secnumdepth}{5}
+\usepackage{iftex}
+\ifPDFTeX
+  \usepackage[T1]{fontenc}
+  \usepackage[utf8]{inputenc}
+  \usepackage{textcomp} % provide euro and other symbols
+\else % if luatex or xetex
+  \usepackage{unicode-math} % this also loads fontspec
+  \defaultfontfeatures{Scale=MatchLowercase}
+  \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
+\fi
+\usepackage{lmodern}
+\ifPDFTeX\else
+  % xetex/luatex font selection
+\fi
+% Use upquote if available, for straight quotes in verbatim environments
+\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
+\IfFileExists{microtype.sty}{% use microtype if available
+  \usepackage[]{microtype}
+  \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
+}{}
+\makeatletter
+\@ifundefined{KOMAClassName}{% if non-KOMA class
+  \IfFileExists{parskip.sty}{%
+    \usepackage{parskip}
+  }{% else
+    \setlength{\parindent}{0pt}
+    \setlength{\parskip}{6pt plus 2pt minus 1pt}}
+}{% if KOMA class
+  \KOMAoptions{parskip=half}}
+\makeatother
+\usepackage{color}
+\usepackage{fancyvrb}
+\newcommand{\VerbBar}{|}
+\newcommand{\VERB}{\Verb[commandchars=\\\{\}]}
+\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}
+% Add ',fontsize=\small' for more characters per line
+\usepackage{framed}
+\definecolor{shadecolor}{RGB}{248,248,248}
+\newenvironment{Shaded}{\begin{snugshade}}{\end{snugshade}}
+\newcommand{\AlertTok}[1]{\textcolor[rgb]{0.94,0.16,0.16}{#1}}
+\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
+\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
+\newcommand{\BuiltInTok}[1]{#1}
+\newcommand{\CharTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
+\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
+\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
+\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
+\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
+\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\ErrorTok}[1]{\textcolor[rgb]{0.64,0.00,0.00}{\textbf{#1}}}
+\newcommand{\ExtensionTok}[1]{#1}
+\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
+\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
+\newcommand{\ImportTok}[1]{#1}
+\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
+\newcommand{\NormalTok}[1]{#1}
+\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
+\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
+\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
+\newcommand{\RegionMarkerTok}[1]{#1}
+\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
+\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\StringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
+\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
+\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
+\usepackage{graphicx}
+\makeatletter
+\newsavebox\pandoc@box
+\newcommand*\pandocbounded[1]{% scales image to fit in text height/width
+  \sbox\pandoc@box{#1}%
+  \Gscale@div\@tempa{\textheight}{\dimexpr\ht\pandoc@box+\dp\pandoc@box\relax}%
+  \Gscale@div\@tempb{\linewidth}{\wd\pandoc@box}%
+  \ifdim\@tempb\p@<\@tempa\p@\let\@tempa\@tempb\fi% select the smaller of both
+  \ifdim\@tempa\p@<\p@\scalebox{\@tempa}{\usebox\pandoc@box}%
+  \else\usebox{\pandoc@box}%
+  \fi%
+}
+% Set default figure placement to htbp
+\def\fps@figure{htbp}
+\makeatother
+% definitions for citeproc citations
+\NewDocumentCommand\citeproctext{}{}
+\NewDocumentCommand\citeproc{mm}{%
+  \begingroup\def\citeproctext{#2}\cite{#1}\endgroup}
+\makeatletter
+ % allow citations to break across lines
+ \let\@cite@ofmt\@firstofone
+ % avoid brackets around text for \cite:
+ \def\@biblabel#1{}
+ \def\@cite#1#2{{#1\if@tempswa , #2\fi}}
+\makeatother
+\newlength{\cslhangindent}
+\setlength{\cslhangindent}{1.5em}
+\newlength{\csllabelwidth}
+\setlength{\csllabelwidth}{3em}
+\newenvironment{CSLReferences}[2] % #1 hanging-indent, #2 entry-spacing
+ {\begin{list}{}{%
+  \setlength{\itemindent}{0pt}
+  \setlength{\leftmargin}{0pt}
+  \setlength{\parsep}{0pt}
+  % turn on hanging indent if param 1 is 1
+  \ifodd #1
+   \setlength{\leftmargin}{\cslhangindent}
+   \setlength{\itemindent}{-1\cslhangindent}
+  \fi
+  % set entry spacing
+  \setlength{\itemsep}{#2\baselineskip}}}
+ {\end{list}}
+\usepackage{calc}
+\newcommand{\CSLBlock}[1]{\hfill\break\parbox[t]{\linewidth}{\strut\ignorespaces#1\strut}}
+\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{\strut#1\strut}}
+\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{\strut#1\strut}}
+\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1}
+\setlength{\emergencystretch}{3em} % prevent overfull lines
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+% usar portugues do Brasil
+% \usepackage[brazilian]{babel}
+\usepackage[utf8]{inputenc}
+
+\usepackage{geometry}
+\geometry{a4paper, top=1in}
+
+% needed for kableExtra
+\usepackage{longtable}
+\usepackage{multirow}
+\usepackage[table]{xcolor}
+\usepackage{wrapfig}
+\usepackage{float}
+\usepackage{colortbl}
+\usepackage{pdflscape}
+\usepackage{tabu}
+\usepackage{threeparttable}
+\usepackage[normalem]{ulem}
+
+\usepackage{bbm}
+\usepackage{booktabs}
+\usepackage{expex}
+
+\usepackage{graphicx}
+
+\usepackage{fancyhdr}
+% set the header and foot style
+% style 'fancy' adds the section name on the header
+% and the page number on the footer
+\pagestyle{fancy}
+
+% style 'fancyhf' leaves header and footer empty
+%\fancyhf{}
+
+% sets the left head element to \rightmark, which contains the
+% current section (\leftmark is the current chapter)
+%\fancyhead[L]{\rightmark} .
+
+% sets the right head element to the page number.
+% \fancyhead[R]{\thepage}
+
+% lets the head rule disappear.
+% \renewcommand{\headrulewidth}{0pt}
+% Possible selectors for the optional argument of \fancyhead/\fancyfoot
+% are L (left), C (center) or R (right) for the position of the element
+% and E (even) or O (odd) to distinguish even and odd pages. If you omit
+% E/O the element is set for all pages.
+
+% \usepackage{lipsum}
+
+% make available command lastpage
+\usepackage{lastpage}
+
+% default fontsize 11pt better to add
+% fontsize on the yaml header
+% \usepackage[fontsize=11pt]{scrextend}
+
+% comandos para formatar uma tabela
+\usepackage{array}
+\newcolumntype{L}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+\newcolumntype{C}[1]{>{\centering\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+\newcolumntype{R}[1]{>{\raggedleft\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+
+% necessário if we need to import other latex documents
+\usepackage{import}
+
+% Command to import an R variable to latex
+\newcommand{\RtoLatex}[2]{\newcommand{#1}{#2}}
+
+% Soft-wrap Pandoc highlighted code/output boxes (Shaded + Highlighting).
+% This runs after Pandoc's default \DefineVerbatimEnvironment{Highlighting}
+% (header includes come later in the generated .tex). Prefer manual line
+% breaks in Rmd sources; breaklines is a safety net for leftovers/output.
+% Requires TinyTeX/TeX Live package: tlmgr install fvextra
+\IfFileExists{fvextra.sty}{%
+  \usepackage{fvextra}%
+  \DefineVerbatimEnvironment{Highlighting}{Verbatim}{%
+    breaklines=true,
+    breakanywhere=true,
+    breakindent=1.5em,
+    fontsize=\small,
+    commandchars=\\\{\}%
+  }%
+}{%
+  % fancyvrb is already loaded by Pandoc; shrink code so more fits per line.
+  \DefineVerbatimEnvironment{Highlighting}{Verbatim}{%
+    fontsize=\small,
+    commandchars=\\\{\}%
+  }%
+}
+
+% 
+%\newcommand{\atraso}[1]{\color{red} \textbf {Tempo desde a Assinatura do Contrato: #1 dias}}
+\usepackage{booktabs}
+\usepackage{longtable}
+\usepackage{array}
+\usepackage{multirow}
+\usepackage{wrapfig}
+\usepackage{float}
+\usepackage{colortbl}
+\usepackage{pdflscape}
+\usepackage{tabu}
+\usepackage{threeparttable}
+\usepackage{threeparttablex}
+\usepackage[normalem]{ulem}
+\usepackage{makecell}
+\usepackage{xcolor}
+\usepackage{bookmark}
+\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
+\urlstyle{same}
+\hypersetup{
+  pdftitle={How to do reproducible research in Ruby with gKnit},
+  pdfauthor={Rodrigo Botafogo; Daniel Mossé - University of Pittsburgh},
+  hidelinks,
+  pdfcreator={LaTeX via pandoc}}
+
+\title{How to do reproducible research in Ruby with gKnit}
+\author{Rodrigo Botafogo \and Daniel Mossé - University of Pittsburgh}
+\date{29/04/2019 (narrative updated for Galaaz 2.0, 2026)}
+
+\begin{document}
+\maketitle
+
+\section{Introduction}\label{introduction}
+
+The idea of ``literate programming'' was first introduced by Donald
+Knuth in the 1980's (Knuth 1984). 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 executable code and at the same time easily read by a
+human developer. According to Knuth ``The practitioner of literate
+programming can be regarded as an essayist, whose main concern is with
+exposition and excellence of style.''
+
+The idea of literate programming evolved into the idea of reproducible
+research, in which all the data, software code, documentation, graphics
+etc. needed to reproduce the research and its reports could be included
+in a single document or set of documents that when distributed to peers
+could be rerun generating 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. 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, \textbf{R markdown} was also developed, an extension to the
+Markdown format. With \textbf{R markdown} and Knitr it is possible to
+generate reports in a multitude of formats such as HTML, Markdown,
+LaTeX, PDF, DVI, etc. \textbf{R markdown} also allows the use of
+multiple programming languages such as R, Ruby, Python, etc. in the same
+document.
+
+In \textbf{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 \textbf{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 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. 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:
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{lst }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.list}\NormalTok{(}\WarningTok{a:} \DecValTok{1}\NormalTok{, }\WarningTok{b:} \DecValTok{2}\NormalTok{, }\WarningTok{c:} \DecValTok{3}\NormalTok{)}
+\NormalTok{lst}\AttributeTok{.saveRDS}\NormalTok{(}\StringTok{"lst.rds"}\NormalTok{)}
+\end{Highlighting}
+\end{Shaded}
+
+then, on the next chunk, where variable `lst' is used, we need to read
+back it's value
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{lst }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.readRDS}\NormalTok{(}\StringTok{"lst.rds"}\NormalTok{)}
+\FunctionTok{puts}\NormalTok{ lst}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## $a
+## [1] 1
+## 
+## $b
+## [1] 2
+## 
+## $c
+## [1] 3
+\end{verbatim}
+
+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 \textbf{R markdown} document in the Ruby community.
+
+When variables can be used accross chunks, then no overhead is needed:
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{lst }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.list}\NormalTok{(}\WarningTok{a:} \DecValTok{1}\NormalTok{, }\WarningTok{b:} \DecValTok{2}\NormalTok{, }\WarningTok{c:} \DecValTok{3}\NormalTok{)}
+\CommentTok{\# any other code can be added here}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\FunctionTok{puts}\NormalTok{ lst}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## $a
+## [1] 1
+## 
+## $b
+## [1] 2
+## 
+## $c
+## [1] 3
+\end{verbatim}
+
+In the Python community, the same effort to have code and text in an
+integrated environment started around the first decade of the 2000s. In
+2006 IPython 0.7.2 was released. In 2014, Fernando Pérez spun off the
+Jupyter project from IPython, creating a web-based interactive
+computation environment. Jupyter can now be used with many languages,
+including Ruby with the iruby gem
+(\url{https://github.com/SciRuby/iruby}). In order to have multiple
+languages in a Jupyter notebook the SoS kernel was developed
+(\url{https://vatlab.github.io/sos-docs/}).
+
+\section{gKnitting a Document}\label{gknitting-a-document}
+
+This document describes gKnit. gKnit is based on knitr and \textbf{R
+markdown} and can knit a document written both in Ruby and/or R and
+output it in any of the available formats of \textbf{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 with \textbf{JRuby or CRuby}, \textbf{GNU R}, and
+\textbf{Galaaz} (the integration layer between Ruby and R---see below).
+Knitr and \textbf{R Markdown} orchestrate the document; Galaaz's engine
+keeps \textbf{Ruby state across chunks} and talks to R through the
+\textbf{bridge}. Ruby chunks can read and update R variables
+(\texttt{\textasciitilde{}R{[}:name{]}}, \texttt{R.*}) without
+GraalVM-style polyglot interop.
+
+Galaaz has already been describe in the following posts:
+
+\begin{itemize}
+\tightlist
+\item
+  \url{https://towardsdatascience.com/ruby-plotting-with-galaaz-an-example-of-tightly-coupling-ruby-and-r-in-graalvm-520b69e21021}
+  (older GraalVM-era article; plotting ideas still apply).
+\item
+  \url{https://medium.freecodecamp.org/how-to-make-beautiful-ruby-plots-with-galaaz-320848058857}
+\end{itemize}
+
+This is not a blog post on \textbf{R markdown}, and the interested user
+is directed to the following links for detailed information on its
+capabilities and use.
+
+\begin{itemize}
+\tightlist
+\item
+  \url{https://rmarkdown.rstudio.com/} or
+\item
+  \url{https://bookdown.org/yihui/rmarkdown/}
+\end{itemize}
+
+In this post, we will describe just the main aspects of \textbf{R
+markdown}, so the user can start gKnitting Ruby and R documents quickly.
+
+\subsection{The Yaml header}\label{the-yaml-header}
+
+An \textbf{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 gKnitting an HTML document.
+
+\begin{verbatim}
+---
+title: "How to do reproducible research in Ruby with gKnit"
+author: 
+    - "Rodrigo Botafogo"
+    - "Daniel Mossé - University of Pittsburgh"
+tags: [Tech, Data Science, Ruby, R, JRuby, CRuby, "GNU R", Galaaz]
+date: "20/02/2019"
+output:
+  html_document:
+    self_contained: true
+    keep_md: true
+  pdf_document:
+    includes:
+      in_header: ["../../sty/galaaz.sty"]
+    number_sections: yes
+---
+\end{verbatim}
+
+For more information on the options in the Yaml header, check
+\url{https://bookdown.org/yihui/rmarkdown/html-document.html}.
+
+\subsection{\texorpdfstring{\textbf{R Markdown}
+formatting}{R Markdown formatting}}\label{r-markdown-formatting}
+
+Document formatting can be done with simple markups such as:
+
+\subsubsection{Headers}\label{headers}
+
+\begin{verbatim}
+# Header 1
+
+## Header 2
+
+### Header 3
+\end{verbatim}
+
+\subsubsection{Lists}\label{lists}
+
+\begin{verbatim}
+Unordered lists:
+
+* Item 1
+* Item 2
+    + Item 2a
+    + Item 2b
+\end{verbatim}
+
+\begin{verbatim}
+Ordered Lists
+
+1. Item 1
+2. Item 2
+3. Item 3
+    + Item 3a
+    + Item 3b
+\end{verbatim}
+
+For more R markdown formatting go to
+\url{https://rmarkdown.rstudio.com/authoring_basics.html}.
+
+\subsubsection{R chunks}\label{r-chunks}
+
+Running and executing Ruby and R code is actually what really interests
+us is this blog.\\
+Inserting a code chunk is done by adding code in a block delimited by
+three back ticks followed by an open curly brace (`\{') followed with
+the engine name (r, ruby, rb, include, \ldots), an any optional
+chunk\_label and options, as shown below:
+
+\begin{verbatim}
+```{engine_name [chunk_label], [chunk_options]}
+```
+\end{verbatim}
+
+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, as follows:
+
+\begin{verbatim}
+```{r first_r_chunk}
+vec <- c(1, 2, 3)
+print(vec)
+```
+\end{verbatim}
+
+If this block is added to an \textbf{R markdown} document and gKnitted
+the result will be:
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{vec }\OtherTok{\textless{}{-}} \FunctionTok{c}\NormalTok{(}\DecValTok{1}\NormalTok{, }\DecValTok{2}\NormalTok{, }\DecValTok{3}\NormalTok{)}
+\FunctionTok{print}\NormalTok{(vec)}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## [1] 1 2 3
+\end{verbatim}
+
+Now let's say that we want to do some analysis in the code, but just
+print the result and not the code itself. For this, we need to add the
+option `echo = FALSE'.
+
+\begin{verbatim}
+```{r second_r_chunk, echo = FALSE}
+vec2 <- c(10, 20, 30)
+vec3 <- vec * vec2
+print(vec3)     
+```
+\end{verbatim}
+
+Here is how this block will show up in the document. Observe that the
+code is not shown and we only see the execution result in a white box
+
+\begin{verbatim}
+## [1] 10 40 90
+\end{verbatim}
+
+A description of the available chunk options can be found in
+\url{https://yihui.name/knitr/}.
+
+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
+
+\begin{verbatim}
+```{r data_creation}
+r_vec <- c(1, 2, 3, 4, 5)
+
+reduce_sum <- function(...) {
+  Reduce(sum, as.list(...))
+}
+```
+\end{verbatim}
+
+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.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{r\_vec }\OtherTok{\textless{}{-}} \FunctionTok{c}\NormalTok{(}\DecValTok{1}\NormalTok{, }\DecValTok{2}\NormalTok{, }\DecValTok{3}\NormalTok{, }\DecValTok{4}\NormalTok{, }\DecValTok{5}\NormalTok{)}
+
+\NormalTok{reduce\_sum }\OtherTok{\textless{}{-}} \ControlFlowTok{function}\NormalTok{(...) \{}
+  \FunctionTok{Reduce}\NormalTok{(sum, }\FunctionTok{as.list}\NormalTok{(...))}
+\NormalTok{\}}
+\end{Highlighting}
+\end{Shaded}
+
+We can, possibly in another chunk, access the vector and call the
+function as follows:
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\FunctionTok{print}\NormalTok{(r\_vec)}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## [1] 1 2 3 4 5
+\end{verbatim}
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\FunctionTok{print}\NormalTok{(}\FunctionTok{reduce\_sum}\NormalTok{(r\_vec))}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## [1] 15
+\end{verbatim}
+
+\subsubsection{R Graphics with ggplot}\label{r-graphics-with-ggplot}
+
+In the following chunk, we create a bubble chart in R using ggplot and
+include it in this document. Note that there is no directive in the code
+to include the image, this 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 2005). The idea of the
+grammar of graphics is to build a graphics by adding layers to the plot.
+More information can be found in
+\url{https://towardsdatascience.com/a-comprehensive-guide-to-the-grammar-of-graphics-for-effective-visualization-of-multi-dimensional-1f92b4ed4149}.
+
+In the plot below 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.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\CommentTok{\# load package and data}
+\FunctionTok{library}\NormalTok{(ggplot2)}
+\FunctionTok{data}\NormalTok{(mpg, }\AttributeTok{package=}\StringTok{"ggplot2"}\NormalTok{)}
+
+\NormalTok{mpg\_select }\OtherTok{\textless{}{-}}\NormalTok{ mpg[}
+\NormalTok{  mpg}\SpecialCharTok{$}\NormalTok{manufacturer }\SpecialCharTok{\%in\%} \FunctionTok{c}\NormalTok{(}\StringTok{"audi"}\NormalTok{, }\StringTok{"ford"}\NormalTok{, }\StringTok{"honda"}\NormalTok{, }\StringTok{"hyundai"}\NormalTok{),}
+\NormalTok{]}
+
+\CommentTok{\# Scatterplot}
+\FunctionTok{theme\_set}\NormalTok{(}\FunctionTok{theme\_bw}\NormalTok{())  }\CommentTok{\# pre{-}set the bw theme.}
+\NormalTok{g }\OtherTok{\textless{}{-}} \FunctionTok{ggplot}\NormalTok{(mpg\_select, }\FunctionTok{aes}\NormalTok{(displ, cty)) }\SpecialCharTok{+}
+  \FunctionTok{labs}\NormalTok{(}\AttributeTok{subtitle=}\StringTok{"mpg: Displacement vs City Mileage"}\NormalTok{,}
+       \AttributeTok{title=}\StringTok{"Bubble chart"}\NormalTok{)}
+
+\NormalTok{g }\SpecialCharTok{+} \FunctionTok{geom\_jitter}\NormalTok{(}\FunctionTok{aes}\NormalTok{(}\AttributeTok{col=}\NormalTok{manufacturer, }\AttributeTok{size=}\NormalTok{hwy)) }\SpecialCharTok{+}
+  \FunctionTok{geom\_smooth}\NormalTok{(}\FunctionTok{aes}\NormalTok{(}\AttributeTok{col=}\NormalTok{manufacturer), }\AttributeTok{method=}\StringTok{"lm"}\NormalTok{, }\AttributeTok{se=}\NormalTok{F)}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## `geom_smooth()` using formula = 'y ~ x'
+\end{verbatim}
+
+\pandocbounded{\includegraphics[keepaspectratio]{gknit_files/gknit_files/figure-latex/bubble-1.png}}
+
+\subsubsection{Ruby chunks}\label{ruby-chunks}
+
+Including a Ruby chunk is just as easy as including an R chunk in the
+document: just change the name of the engine to `ruby'. It is also
+possible to pass chunk options to the Ruby engine; however, this version
+does not accept all the options that are available to R chunks. Future
+versions will add those options.
+
+\begin{verbatim}
+```{ruby first_ruby_chunk}
+```
+\end{verbatim}
+
+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, 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.
+
+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.
+
+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.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{a }\OperatorTok{=} \KeywordTok{[}\DecValTok{1}\NormalTok{, }\DecValTok{2}\NormalTok{, }\DecValTok{3}\KeywordTok{]}
+\NormalTok{b }\OperatorTok{=} \StringTok{"US$ 250.000"}
+\NormalTok{c }\OperatorTok{=} \StringTok{"The \textquotesingle{}outputs\textquotesingle{} function"}
+
+\NormalTok{vec }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.c}\NormalTok{(}\DecValTok{1}\NormalTok{, }\DecValTok{2}\NormalTok{, }\DecValTok{3}\NormalTok{)}
+\NormalTok{vec2 }\OperatorTok{=} \ConstantTok{R}\AttributeTok{.c}\NormalTok{(}\DecValTok{10}\NormalTok{, }\DecValTok{20}\NormalTok{, }\DecValTok{30}\NormalTok{)}
+\end{Highlighting}
+\end{Shaded}
+
+In the next block, variables `a', `vec' and `vec2' are used and printed.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\FunctionTok{puts}\NormalTok{ a}
+\FunctionTok{puts}\NormalTok{ vec }\OperatorTok{*}\NormalTok{ vec2}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## 1
+## 2
+## 3
+## [1] 10 40 90
+\end{verbatim}
+
+Note that `a' is a standard Ruby Array and `vec' and `vec2' are vectors
+that behave accordingly, where multiplication works as expected.
+
+\subsubsection{Accessing R from Ruby}\label{accessing-r-from-ruby}
+
+One of the nice aspects of Galaaz 2.0 is that variables and functions
+defined in R can be easily accessed from Ruby. This next chunk, reads
+data from R and uses the `reduce\_sum' function defined previously. To
+access an R variable from Ruby the `\textasciitilde{}' function should
+be applied to the Ruby symbol representing the R variable. Since the R
+variable is called `r\_vec', in Ruby, the symbol to acess it is
+`:r\_vec' and thus `\textasciitilde R{[}:r\_vec{]}' retrieves the value
+of the variable.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\FunctionTok{puts} \OperatorTok{\textasciitilde{}}\ConstantTok{R}\KeywordTok{[}\WarningTok{:r\_vec}\KeywordTok{]}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## [1] 1 2 3 4 5
+\end{verbatim}
+
+In order to call an R function, the `R.' module is used as follows
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\FunctionTok{puts} \ConstantTok{R}\AttributeTok{.reduce\_sum}\NormalTok{(}\OperatorTok{\textasciitilde{}}\ConstantTok{R}\KeywordTok{[}\WarningTok{:r\_vec}\KeywordTok{]}\NormalTok{)}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+## [1] 15
+\end{verbatim}
+
+\subsubsection{Ruby Plotting}\label{ruby-plotting}
+
+We have seen an example of plotting with R. Plotting with Ruby does not
+require 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:
+
+\begin{itemize}
+\tightlist
+\item
+  mpg: Miles/(US) gallon
+\item
+  cyl: Number of cylinders
+\item
+  disp: Displacement (cu.in.)
+\item
+  hp: Gross horsepower
+\item
+  drat: Rear axle ratio
+\item
+  wt: Weight (1000 lbs)
+\item
+  qsec: 1/4 mile time
+\item
+  vs: Engine (0 = V-shaped, 1 = straight)
+\item
+  am: Transmission (0 = automatic, 1 = manual)
+\item
+  gear: Number of forward gears
+\item
+  carb: Number of carburetors
+\end{itemize}
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\CommentTok{\# copy the R variable :mtcars to the Ruby mtcars variable}
+\NormalTok{mtcars }\OperatorTok{=} \OperatorTok{\textasciitilde{}}\ConstantTok{R}\KeywordTok{[}\WarningTok{:mtcars}\KeywordTok{]}
+
+\CommentTok{\# New column \textquotesingle{}car\_name\textquotesingle{} for plotting (rownames alone are not}
+\CommentTok{\# usable as plot data).}
+\NormalTok{mtcars}\AttributeTok{.car\_name} \OperatorTok{=} \ConstantTok{R}\AttributeTok{.rownames}\NormalTok{(}\WarningTok{:mtcars}\NormalTok{)}
+
+\CommentTok{\# Normalized mpg in column mpg\_z: (mpg {-} mean) / sd, rounded.}
+\NormalTok{mtcars}\AttributeTok{.mpg\_z} \OperatorTok{=}
+\NormalTok{  ((mtcars}\AttributeTok{.mpg} \OperatorTok{{-}}\NormalTok{ mtcars}\AttributeTok{.mpg.mean}\NormalTok{) }\OperatorTok{/}\NormalTok{ mtcars}\AttributeTok{.mpg.sd}\NormalTok{)}\AttributeTok{.round} \DecValTok{2}
+
+\CommentTok{\# mpg\_type: \textquotesingle{}below\textquotesingle{} if mpg\_z \textless{} 0, else \textquotesingle{}above\textquotesingle{} (vectorized ifelse).}
+\NormalTok{mtcars}\AttributeTok{.mpg\_type} \OperatorTok{=}
+\NormalTok{  (mtcars}\AttributeTok{.mpg\_z} \OperatorTok{\textless{}} \DecValTok{0}\NormalTok{)}\AttributeTok{.ifelse}\NormalTok{(}\StringTok{"below"}\NormalTok{, }\StringTok{"above"}\NormalTok{)}
+
+\CommentTok{\# Order rows by mpg\_z ascending.}
+\NormalTok{mtcars }\OperatorTok{=}\NormalTok{ mtcars}\KeywordTok{[}\NormalTok{mtcars}\AttributeTok{.mpg\_z.order}\NormalTok{, }\WarningTok{:all}\KeywordTok{]}
+
+\CommentTok{\# Factor car\_name so plot keeps sorted order.}
+\NormalTok{mtcars}\AttributeTok{.car\_name} \OperatorTok{=}
+\NormalTok{  mtcars}\AttributeTok{.car\_name.factor} \WarningTok{levels:}\NormalTok{ mtcars}\AttributeTok{.car\_name}
+
+\CommentTok{\# First records of the final data frame}
+\FunctionTok{puts}\NormalTok{ mtcars}\AttributeTok{.head}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+##                      mpg cyl disp  hp drat    wt  qsec vs am gear
+## Cadillac Fleetwood  10.4   8  472 205 2.93 5.250 17.98  0  0    3
+## Lincoln Continental 10.4   8  460 215 3.00 5.424 17.82  0  0    3
+## Camaro Z28          13.3   8  350 245 3.73 3.840 15.41  0  0    3
+## Duster 360          14.3   8  360 245 3.21 3.570 15.84  0  0    3
+## Chrysler Imperial   14.7   8  440 230 3.23 5.345 17.42  0  0    3
+## Maserati Bora       15.0   8  301 335 3.54 3.570 14.60  0  1    5
+##                     carb            car_name mpg_z mpg_type
+## Cadillac Fleetwood     4  Cadillac Fleetwood -1.61    below
+## Lincoln Continental    4 Lincoln Continental -1.61    below
+## Camaro Z28             4          Camaro Z28 -1.13    below
+## Duster 360             4          Duster 360 -0.96    below
+## Chrysler Imperial      4   Chrysler Imperial -0.89    below
+## Maserati Bora          8       Maserati Bora -0.84    below
+\end{verbatim}
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\FunctionTok{require} \VerbatimStringTok{\textquotesingle{}ggplot\textquotesingle{}}
+
+\FunctionTok{puts}\NormalTok{ mtcars}\AttributeTok{.ggplot}\NormalTok{(}
+       \ConstantTok{E}\AttributeTok{.aes}\NormalTok{(}\WarningTok{x:} \WarningTok{:car\_name}\NormalTok{, }\WarningTok{y:} \WarningTok{:mpg\_z}\NormalTok{, }\WarningTok{label:} \WarningTok{:mpg\_z}\NormalTok{)) }\OperatorTok{+}
+     \ConstantTok{R}\AttributeTok{.geom\_bar}\NormalTok{(}\ConstantTok{E}\AttributeTok{.aes}\NormalTok{(}\WarningTok{fill:} \WarningTok{:mpg\_type}\NormalTok{),}
+                \WarningTok{stat:} \VerbatimStringTok{\textquotesingle{}identity\textquotesingle{}}\NormalTok{, }\WarningTok{width:} \FloatTok{0.5}\NormalTok{) }\OperatorTok{+}
+     \ConstantTok{R}\AttributeTok{.scale\_fill\_manual}\NormalTok{(}
+       \WarningTok{name:} \VerbatimStringTok{\textquotesingle{}Mileage\textquotesingle{}}\NormalTok{,}
+       \WarningTok{labels:} \ConstantTok{R}\AttributeTok{.c}\NormalTok{(}\VerbatimStringTok{\textquotesingle{}Above Average\textquotesingle{}}\NormalTok{, }\VerbatimStringTok{\textquotesingle{}Below Average\textquotesingle{}}\NormalTok{),}
+       \WarningTok{values:} \ConstantTok{R}\AttributeTok{.c}\NormalTok{(}\VerbatimStringTok{\textquotesingle{}above\textquotesingle{}}\WarningTok{:} \VerbatimStringTok{\textquotesingle{}\#00ba38\textquotesingle{}}\NormalTok{,}
+                   \VerbatimStringTok{\textquotesingle{}below\textquotesingle{}}\WarningTok{:} \VerbatimStringTok{\textquotesingle{}\#f8766d\textquotesingle{}}\NormalTok{)) }\OperatorTok{+}
+     \ConstantTok{R}\AttributeTok{.labs}\NormalTok{(}\WarningTok{subtitle:} \StringTok{"Normalised mileage from \textquotesingle{}mtcars\textquotesingle{}"}\NormalTok{,}
+            \WarningTok{title:} \StringTok{"Diverging Bars"}\NormalTok{) }\OperatorTok{+}
+     \ConstantTok{R}\AttributeTok{.coord\_flip}
+\end{Highlighting}
+\end{Shaded}
+
+\pandocbounded{\includegraphics[keepaspectratio]{gknit_files/gknit_files/figure-latex/diverging_bar.pdf}}
+
+\subsubsection{Inline Ruby code}\label{inline-ruby-code}
+
+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:
+
+\begin{verbatim}
+This is some text with inline Ruby accessing
+variable 'b' which has value:
+```{rb puts b}
+```
+and is followed by some other text!
+\end{verbatim}
+
+This is some text with inline Ruby accessing variable `b' which has
+value: US\$ 250.000 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.
+
+\subsubsection{The `outputs' function}\label{the-outputs-function}
+
+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
+\textbf{R markdown} document.
+
+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 \textbf{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 section and it was created using the 'outputs'
+function inside a Ruby chunk.
+
+The ruby chunk to generate this heading is:
+
+\begin{verbatim}
+```{ruby heading}
+outputs "### #{c}"
+```
+\end{verbatim}
+
+The three `\#\#\#' is the way we add a Heading 3 in \textbf{R markdown}.
+
+\subsubsection{HTML Output from Ruby
+Chunks}\label{html-output-from-ruby-chunks}
+
+We've just seen the use of method `outputs' to add text to the the
+\textbf{R markdown} document. This technique can also be used to add
+HTML code to the document. In \textbf{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:
+
+\begin{verbatim}
+<table style="width:100%">
+  <tr>
+    <th>Firstname</th>
+    <th>Lastname</th> 
+    <th>Age</th>
+  </tr>
+  <tr>
+    <td>Jill</td>
+    <td>Smith</td> 
+    <td>50</td>
+  </tr>
+  <tr>
+    <td>Eve</td>
+    <td>Jackson</td> 
+    <td>94</td>
+  </tr>
+</table>
+\end{verbatim}
+
+Firstname
+
+Lastname
+
+Age
+
+Jill
+
+Smith
+
+50
+
+Eve
+
+Jackson
+
+94
+
+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
+\url{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
+`\textasciitilde R{[}:mtcars{]}'.
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\ConstantTok{R}\AttributeTok{.install\_and\_loads}\NormalTok{(}\VerbatimStringTok{\textquotesingle{}kableExtra\textquotesingle{}}\NormalTok{)}
+\NormalTok{outputs (}\OperatorTok{\textasciitilde{}}\ConstantTok{R}\KeywordTok{[}\WarningTok{:mtcars}\KeywordTok{]}\NormalTok{)}\AttributeTok{.kable.kable\_styling}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{longtable}[t]{lrrrrrrrrrrr}
+\toprule
+ & mpg & cyl & disp & hp & drat & wt & qsec & vs & am & gear & carb\\
+\midrule
+Mazda RX4 & 21.0 & 6 & 160.0 & 110 & 3.90 & 2.620 & 16.46 & 0 & 1 & 4 & 4\\
+Mazda RX4 Wag & 21.0 & 6 & 160.0 & 110 & 3.90 & 2.875 & 17.02 & 0 & 1 & 4 & 4\\
+Datsun 710 & 22.8 & 4 & 108.0 & 93 & 3.85 & 2.320 & 18.61 & 1 & 1 & 4 & 1\\
+Hornet 4 Drive & 21.4 & 6 & 258.0 & 110 & 3.08 & 3.215 & 19.44 & 1 & 0 & 3 & 1\\
+Hornet Sportabout & 18.7 & 8 & 360.0 & 175 & 3.15 & 3.440 & 17.02 & 0 & 0 & 3 & 2\\
+\addlinespace
+Valiant & 18.1 & 6 & 225.0 & 105 & 2.76 & 3.460 & 20.22 & 1 & 0 & 3 & 1\\
+Duster 360 & 14.3 & 8 & 360.0 & 245 & 3.21 & 3.570 & 15.84 & 0 & 0 & 3 & 4\\
+Merc 240D & 24.4 & 4 & 146.7 & 62 & 3.69 & 3.190 & 20.00 & 1 & 0 & 4 & 2\\
+Merc 230 & 22.8 & 4 & 140.8 & 95 & 3.92 & 3.150 & 22.90 & 1 & 0 & 4 & 2\\
+Merc 280 & 19.2 & 6 & 167.6 & 123 & 3.92 & 3.440 & 18.30 & 1 & 0 & 4 & 4\\
+\addlinespace
+Merc 280C & 17.8 & 6 & 167.6 & 123 & 3.92 & 3.440 & 18.90 & 1 & 0 & 4 & 4\\
+Merc 450SE & 16.4 & 8 & 275.8 & 180 & 3.07 & 4.070 & 17.40 & 0 & 0 & 3 & 3\\
+Merc 450SL & 17.3 & 8 & 275.8 & 180 & 3.07 & 3.730 & 17.60 & 0 & 0 & 3 & 3\\
+Merc 450SLC & 15.2 & 8 & 275.8 & 180 & 3.07 & 3.780 & 18.00 & 0 & 0 & 3 & 3\\
+Cadillac Fleetwood & 10.4 & 8 & 472.0 & 205 & 2.93 & 5.250 & 17.98 & 0 & 0 & 3 & 4\\
+\addlinespace
+Lincoln Continental & 10.4 & 8 & 460.0 & 215 & 3.00 & 5.424 & 17.82 & 0 & 0 & 3 & 4\\
+Chrysler Imperial & 14.7 & 8 & 440.0 & 230 & 3.23 & 5.345 & 17.42 & 0 & 0 & 3 & 4\\
+Fiat 128 & 32.4 & 4 & 78.7 & 66 & 4.08 & 2.200 & 19.47 & 1 & 1 & 4 & 1\\
+Honda Civic & 30.4 & 4 & 75.7 & 52 & 4.93 & 1.615 & 18.52 & 1 & 1 & 4 & 2\\
+Toyota Corolla & 33.9 & 4 & 71.1 & 65 & 4.22 & 1.835 & 19.90 & 1 & 1 & 4 & 1\\
+\addlinespace
+Toyota Corona & 21.5 & 4 & 120.1 & 97 & 3.70 & 2.465 & 20.01 & 1 & 0 & 3 & 1\\
+Dodge Challenger & 15.5 & 8 & 318.0 & 150 & 2.76 & 3.520 & 16.87 & 0 & 0 & 3 & 2\\
+AMC Javelin & 15.2 & 8 & 304.0 & 150 & 3.15 & 3.435 & 17.30 & 0 & 0 & 3 & 2\\
+Camaro Z28 & 13.3 & 8 & 350.0 & 245 & 3.73 & 3.840 & 15.41 & 0 & 0 & 3 & 4\\
+Pontiac Firebird & 19.2 & 8 & 400.0 & 175 & 3.08 & 3.845 & 17.05 & 0 & 0 & 3 & 2\\
+\addlinespace
+Fiat X1-9 & 27.3 & 4 & 79.0 & 66 & 4.08 & 1.935 & 18.90 & 1 & 1 & 4 & 1\\
+Porsche 914-2 & 26.0 & 4 & 120.3 & 91 & 4.43 & 2.140 & 16.70 & 0 & 1 & 5 & 2\\
+Lotus Europa & 30.4 & 4 & 95.1 & 113 & 3.77 & 1.513 & 16.90 & 1 & 1 & 5 & 2\\
+Ford Pantera L & 15.8 & 8 & 351.0 & 264 & 4.22 & 3.170 & 14.50 & 0 & 1 & 5 & 4\\
+Ferrari Dino & 19.7 & 6 & 145.0 & 175 & 3.62 & 2.770 & 15.50 & 0 & 1 & 5 & 6\\
+\addlinespace
+Maserati Bora & 15.0 & 8 & 301.0 & 335 & 3.54 & 3.570 & 14.60 & 0 & 1 & 5 & 8\\
+Volvo 142E & 21.4 & 4 & 121.0 & 109 & 4.11 & 2.780 & 18.60 & 1 & 1 & 4 & 2\\
+\bottomrule
+\end{longtable}
+
+\subsubsection{Including Ruby files in a
+chunk}\label{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, 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. 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 is the
+name of 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, 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.
+
+\begin{verbatim}
+```{include <filename>, relative = <TRUE/FALSE>}
+```
+\end{verbatim}
+
+Below 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 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' will install the package if it is not already
+installed (via \textbf{\texttt{R::Job}}: a child \texttt{Rscript}, so
+the bridge stays free) and can take a while.
+
+\begin{verbatim}
+```{include model}
+```
+\end{verbatim}
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{require \textquotesingle{}galaaz\textquotesingle{}}
+
+\NormalTok{\# Loads the R \textquotesingle{}caret\textquotesingle{} package.  If not present, installs it }
+\NormalTok{R.install\_and\_loads \textquotesingle{}caret\textquotesingle{}}
+
+\NormalTok{class Model}
+  
+\NormalTok{  attr\_reader :data}
+\NormalTok{  attr\_reader :test}
+\NormalTok{  attr\_reader :train}
+
+\NormalTok{  \#==========================================================}
+\NormalTok{  \#}
+\NormalTok{  \#==========================================================}
+  
+\NormalTok{  def initialize(data, percent\_train:, seed: 123)}
+
+\NormalTok{    R.set\_\_seed(seed)}
+\NormalTok{    @data = data}
+\NormalTok{    @percent\_train = percent\_train}
+\NormalTok{    @seed = seed}
+    
+\NormalTok{  end}
+
+\NormalTok{  \#==========================================================}
+\NormalTok{  \#}
+\NormalTok{  \#==========================================================}
+
+\NormalTok{  def partition(field)}
+
+\NormalTok{    train\_index =}
+\NormalTok{      R.createDataPartition(@data.send(field), p: @percent\_train,}
+\NormalTok{                            list: false, times: 1)}
+\NormalTok{    @train = @data[train\_index, :all]}
+\NormalTok{    @test = @data[{-}train\_index, :all]}
+    
+\NormalTok{  end}
+  
+\NormalTok{end}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{mtcars }\OperatorTok{=} \OperatorTok{\textasciitilde{}}\ConstantTok{R}\KeywordTok{[}\WarningTok{:mtcars}\KeywordTok{]}
+\NormalTok{model }\OperatorTok{=} \DataTypeTok{Model}\AttributeTok{.new}\NormalTok{(mtcars, }\WarningTok{percent\_train:} \FloatTok{0.8}\NormalTok{)}
+\NormalTok{model}\AttributeTok{.partition}\NormalTok{(}\WarningTok{:mpg}\NormalTok{)}
+\FunctionTok{puts}\NormalTok{ model}\AttributeTok{.train.head}
+\FunctionTok{puts}\NormalTok{ model}\AttributeTok{.test.head}
+\end{Highlighting}
+\end{Shaded}
+
+\begin{verbatim}
+##                    mpg cyl  disp  hp drat    wt  qsec vs am gear carb
+## Mazda RX4         21.0   6 160.0 110 3.90 2.620 16.46  0  1    4    4
+## Datsun 710        22.8   4 108.0  93 3.85 2.320 18.61  1  1    4    1
+## Hornet 4 Drive    21.4   6 258.0 110 3.08 3.215 19.44  1  0    3    1
+## Hornet Sportabout 18.7   8 360.0 175 3.15 3.440 17.02  0  0    3    2
+## Valiant           18.1   6 225.0 105 2.76 3.460 20.22  1  0    3    1
+## Merc 240D         24.4   4 146.7  62 3.69 3.190 20.00  1  0    4    2
+##                 mpg cyl  disp  hp drat    wt  qsec vs am gear carb
+## Mazda RX4 Wag  21.0   6 160.0 110 3.90 2.875 17.02  0  1    4    4
+## Duster 360     14.3   8 360.0 245 3.21 3.570 15.84  0  0    3    4
+## Toyota Corolla 33.9   4  71.1  65 4.22 1.835 19.90  1  1    4    1
+## Ford Pantera L 15.8   8 351.0 264 4.22 3.170 14.50  0  1    5    4
+\end{verbatim}
+
+\subsubsection{Documenting Gems}\label{documenting-gems}
+
+gKnit also allows developers to document and load files that are not in
+the same directory of the `.Rmd' file.
+
+Here is an example of loading the `find.rb' file from Ruby (via
+\texttt{\$LOAD\_PATH}). 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 know its directory.
+
+\begin{verbatim}
+```{include find, relative = FALSE}
+```
+\end{verbatim}
+
+\begin{Shaded}
+\begin{Highlighting}[]
+\NormalTok{\# frozen\_string\_literal: true}
+\NormalTok{\#}
+\NormalTok{\# find.rb: the Find module for processing all files under a given directory.}
+\NormalTok{\#}
+
+\NormalTok{\#}
+\NormalTok{\# The +Find+ module supports the top{-}down traversal of a set of file paths.}
+\NormalTok{\#}
+\NormalTok{\# For example, to total the size of all files under your home directory,}
+\NormalTok{\# ignoring anything in a "dot" directory (e.g. $HOME/.ssh):}
+\NormalTok{\#}
+\NormalTok{\#   require \textquotesingle{}find\textquotesingle{}}
+\NormalTok{\#}
+\NormalTok{\#   total\_size = 0}
+\NormalTok{\#}
+\NormalTok{\#   Find.find(ENV["HOME"]) do |path|}
+\NormalTok{\#     if FileTest.directory?(path)}
+\NormalTok{\#       if File.basename(path).start\_with?(\textquotesingle{}.\textquotesingle{})}
+\NormalTok{\#         Find.prune       \# Don\textquotesingle{}t look any further into this directory.}
+\NormalTok{\#       else}
+\NormalTok{\#         next}
+\NormalTok{\#       end}
+\NormalTok{\#     else}
+\NormalTok{\#       total\_size += FileTest.size(path)}
+\NormalTok{\#     end}
+\NormalTok{\#   end}
+\NormalTok{\#}
+\NormalTok{module Find}
+
+\NormalTok{  VERSION = "0.2.0"}
+
+\NormalTok{  \#}
+\NormalTok{  \# Calls the associated block with the name of every file and directory listed}
+\NormalTok{  \# as arguments, then recursively on their subdirectories, and so on.}
+\NormalTok{  \#}
+\NormalTok{  \# Returns an enumerator if no block is given.}
+\NormalTok{  \#}
+\NormalTok{  \# See the +Find+ module documentation for an example.}
+\NormalTok{  \#}
+\NormalTok{  def find(*paths, ignore\_error: true) \# :yield: path}
+\NormalTok{    block\_given? or return enum\_for(\_\_method\_\_, *paths, ignore\_error: ignore\_error)}
+
+\NormalTok{    fs\_encoding = Encoding.find("filesystem")}
+
+\NormalTok{    paths.collect!\{|d| raise Errno::ENOENT, d unless File.exist?(d); d.dup\}.each do |path|}
+\NormalTok{      path = path.to\_path if path.respond\_to? :to\_path}
+\NormalTok{      enc = path.encoding == Encoding::US\_ASCII ? fs\_encoding : path.encoding}
+\NormalTok{      ps = [path]}
+\NormalTok{      while file = ps.shift}
+\NormalTok{        catch(:prune) do}
+\NormalTok{          yield file.dup}
+\NormalTok{          begin}
+\NormalTok{            s = File.lstat(file)}
+\NormalTok{          rescue Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP, Errno::ENAMETOOLONG, Errno::EINVAL}
+\NormalTok{            raise unless ignore\_error}
+\NormalTok{            next}
+\NormalTok{          end}
+\NormalTok{          if s.directory? then}
+\NormalTok{            begin}
+\NormalTok{              fs = Dir.children(file, encoding: enc)}
+\NormalTok{            rescue Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP, Errno::ENAMETOOLONG, Errno::EINVAL}
+\NormalTok{              raise unless ignore\_error}
+\NormalTok{              next}
+\NormalTok{            end}
+\NormalTok{            fs.sort!}
+\NormalTok{            fs.reverse\_each \{|f|}
+\NormalTok{              f = File.join(file, f)}
+\NormalTok{              ps.unshift f}
+\NormalTok{            \}}
+\NormalTok{          end}
+\NormalTok{        end}
+\NormalTok{      end}
+\NormalTok{    end}
+\NormalTok{    nil}
+\NormalTok{  end}
+
+\NormalTok{  \#}
+\NormalTok{  \# Skips the current file or directory, restarting the loop with the next}
+\NormalTok{  \# entry. If the current file is a directory, that directory will not be}
+\NormalTok{  \# recursively entered. Meaningful only within the block associated with}
+\NormalTok{  \# Find::find.}
+\NormalTok{  \#}
+\NormalTok{  \# See the +Find+ module documentation for an example.}
+\NormalTok{  \#}
+\NormalTok{  def prune}
+\NormalTok{    throw :prune}
+\NormalTok{  end}
+
+\NormalTok{  module\_function :find, :prune}
+\NormalTok{end}
+\end{Highlighting}
+\end{Shaded}
+
+\subsection{Converting to PDF}\label{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 \textbf{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.
+
+gKnit comes with a simple LaTeX style file for gknitting this blog as a
+PDF document. Here is the Yaml header to generate this blog in PDF
+format instead of HTML:
+
+\begin{verbatim}
+---
+title: "gKnit - Ruby and R Knitting with Galaaz"
+author: "Rodrigo Botafogo"
+tags: [Galaaz, Ruby, R, JRuby, CRuby, "GNU R", knitr, gknit]
+date: "29 October 2018"
+output:
+  pdf\_document:
+    includes:
+      in\_header: ["../../sty/galaaz.sty"]
+    number\_sections: yes
+---
+\end{verbatim}
+
+\section{Conclusion}\label{conclusion}
+
+In order to do reproducible research, one of the main basic tools needed
+is a system 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 \textbf{R
+Markdown} to integrate text and code chunks, where code chunks can
+either be part of the \textbf{R Markdown} file or be imported from files
+in the system. Ideally, in reproducible research, all the files needed
+to rebuild a report should be easily packed together (in the same zipped
+directory) and distributed to peers for reexecution.
+
+\textbf{Galaaz 2.0} pairs \textbf{JRuby or CRuby} with \textbf{GNU R}:
+you keep the full CRAN/Bioconductor world in R while writing
+orchestration, reuse, and application code in Ruby. The effort to wrap
+Ruby over R (Galaaz) and to wrap Knitr as gKnit was tiny compared to
+reimplementing R's ecosystem in Ruby---much like Python's investment in
+NumPy and Pandas, which no Ruby project is likely to duplicate.
+
+An \textbf{earlier} prototype used Oracle's \textbf{GraalVM} and Truffle
+interop; the \textbf{current} stack is deliberately \textbf{standard GNU
+R} plus the Galaaz \textbf{bridge} on JRuby or CRuby, documented in the
+project manual.
+
+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
+readability.
+
+\section{Installing gKnit}\label{installing-gknit}
+
+\subsection{Prerequisites (Galaaz 2.0)}\label{prerequisites-galaaz-2.0}
+
+\begin{itemize}
+\tightlist
+\item
+  \textbf{JRuby} and a compatible \textbf{JDK}, \emph{or} \textbf{CRuby
+  3.3+}
+\item
+  \textbf{GNU R} on your \texttt{PATH}
+\end{itemize}
+
+The following R packages will be automatically installed when necessary,
+but could be installed prior to using gKnit if desired:
+
+\begin{itemize}
+\tightlist
+\item
+  ggplot2
+\item
+  gridExtra
+\item
+  knitr
+\end{itemize}
+
+Installation of R packages requires a development environment and can be
+time consuming. On Linux, the usual build tools are typically enough. On
+macOS, Xcode command-line tools are commonly required.
+
+\subsection{Preparation}\label{preparation}
+
+\begin{itemize}
+\tightlist
+\item
+  Install the \textbf{galaaz} gem (RubyGems or a local build /
+  \texttt{path:}).
+\end{itemize}
+
+\subsection{Usage}\label{usage}
+
+\begin{itemize}
+\tightlist
+\item
+  \textbf{\texttt{bin/gknit}} \textless filename\textgreater{} (from the
+  Galaaz repo or your install layout); use
+  \textbf{\texttt{-\/-output\_format\ all}} for HTML and PDF together.
+\item
+  Run Ruby with \textbf{\texttt{bin/galaaz-ruby}} (either engine) or
+  \textbf{\texttt{bin/galaaz-jruby}} when you need JRuby JVM flags (see
+  the manual).
+\end{itemize}
+
+\section*{References}\label{references}
+\addcontentsline{toc}{section}{References}
+
+\protect\phantomsection\label{refs}
+\begin{CSLReferences}{1}{1}
+\bibitem[\citeproctext]{ref-Knuth:literate_programming}
+Knuth, Donald E. 1984. {``Literate Programming.''} \emph{Comput. J.}
+(Oxford, UK) 27 (2): 97--111.
+\url{https://doi.org/10.1093/comjnl/27.2.97}.
+
+\bibitem[\citeproctext]{ref-Wilkinson:grammar_of_graphics}
+Wilkinson, Leland. 2005. \emph{The Grammar of Graphics (Statistics and
+Computing)}. Springer-Verlag.
+
+\end{CSLReferences}
+
+\end{document}