--- title: "Galaaz Manual" subtitle: "Coupling Ruby (JRuby) and GNU R for data science" author: "Rodrigo Botafogo" tags: [Galaaz, Ruby, JRuby, R, "GNU R", ggplot2, knitr, dplyr, Bioconductor, Arrow] date: "2026" bibliography: "../../examples/Bibliography/stats.bib" output: html_document: self_contained: true keep_md: true toc: true toc_depth: 3 number_sections: true pdf_document: includes: in_header: "../../sty/galaaz.sty" keep_tex: yes number_sections: yes toc: true toc_depth: 3 md_document: variant: markdown_github fontsize: 11pt --- # Introduction Galaaz is a system for tightly coupling Ruby and R. Ruby is a powerful language, with a large community, a very large set of libraries and great for web development. However, it lacks libraries for data science, statistics, scientific plotting and machine learning. On the other hand, R is considered one of the most powerful languages for solving all of the above problems. **Python** is a strong competitor: NumPy, pandas, SciPy, and scikit-learn are widely used building blocks, and **PyPI** hosts many thousands of other packages for numerical work, machine learning, and beyond. With Galaaz we do not intend to re-implement any of the scientific libraries in R, we allow for very tight coupling between the two languages to the point that the Ruby developer does not need to know that there is an R engine running. According to Wikipedia "Ruby is a dynamic, interpreted, reflective, object-oriented, general-purpose programming language. It was designed and developed in the mid-1990s by Yukihiro "Matz" Matsumoto in Japan." It reached high popularity with the development of Ruby on Rails (RoR) by David Heinemeier Hansson. RoR is a web application framework first released around 2005. It makes extensive use of Ruby's metaprogramming features. With RoR, Ruby became very popular. According to [Ruby’s place in the TIOBE index](https://www.tiobe.com/tiobe-index/ruby/) it peaked in popularity around 2008, then declined until 2015 when it started picking up again. Ruby remains a significant language in web development and general-purpose scripting. Python, a language similar to Ruby, ranks 4th in the index. Java, C and C++ take the first three positions. Ruby is often criticized for its focus on web applications. But Ruby can do [much more](https://github.com/markets/awesome-ruby) than just web applications. Yet, for scientific computing, Ruby lags behind Python and R. Python offers Django and similar frameworks for the web, plus NumPy, pandas, and a deep catalog of science and ML libraries. R is a free software environment for statistical computing and graphics with thousands of libraries for data analysis. Until recently, there was no real perspective for Ruby to bridge this gap. Implementing a complete scientific computing infrastructure would take too long. **Galaaz 2.0** couples **JRuby** (Ruby on the JVM) with **GNU R**—the same R you use for CRAN and Bioconductor. Ruby and R run in **separate processes**; the **Galaaz bridge** sends requests to R and returns results to Ruby. From your point of view you still write Ruby: `R.c(...)`, `R.library('ggplot2')`, `~R[:mtcars]`, and dplyr-style chains on R objects. You do not need to learn R syntax to get a lot done, though reading R documentation for individual packages remains useful. Earlier experiments with Galaaz used Oracle’s **GraalVM** with TruffleRuby and FastR so that Ruby and R could share one runtime. That path is no longer the focus: **standard GNU R** gives full compatibility with the R package ecosystem (including compiled extensions and Bioconductor) while JRuby gives a mature Ruby with **real multithreading** for application and I/O code. The bridge handles **communication and typing** between the two worlds; large tables can also flow through **Apache Arrow** on the R side when you use the optional helpers described later in this manual. Library wrapping is a common way to bring features from one language into another. To improve performance, Python often wraps more efficient C libraries. For the Python developer, the existence of such C libraries is hidden. The problem with library wrapping is that for any new library, there is the need to handcraft a new wrapper. Galaaz, instead of wrapping a single C or R library, wraps the whole R language in Ruby. Doing so, all thousands of R libraries are available immediately to Ruby developers without any new wrapping effort. ## What does Galaaz mean Galaaz is the Portuguese name for "Galahad". From Wikipedia: Sir Galahad (sometimes referred to as Galeas or Galath), in Arthurian legend, is a knight of King Arthur's Round Table and one of the three achievers of the Holy Grail. He is the illegitimate son of Sir Lancelot and Elaine of Corbenic, and is renowned for his gallantry and purity as the most perfect of all knights. Emerging quite late in the medieval Arthurian tradition, Sir Galahad first appears in the Lancelot–Grail cycle, and his story is taken up in later works such as the Post-Vulgate Cycle and Sir Thomas Malory's Le Morte d'Arthur. His name should not be mistaken with Galehaut, a different knight from Arthurian legend. # Command-line tools (`bin/`) The Galaaz repository ships many helpers under **`bin/`**. When working from a **clone**, call them as **`bin/`** from the project root (or `./bin/`). If you install the **gem**, only a subset is guaranteed on your `PATH` (see the gemspec: **`galaaz`**, **`gstudio`**, **`gknit`**, **`grun`**, **`gknit-draft`**); for development and CI, prefer the **`bin/`** copies so JVM flags and paths stay correct. Below, **current (Galaaz 2.0 + JRuby + GNU R)** means the tool is wired to **`jruby`** and **`bin/galaaz_jruby_env.inc.sh`** (or equivalent logic in Ruby via `lib/galaaz_jruby.rb`). **Legacy** means the script still targets **GraalVM** polyglot Ruby / FastR-era invocation and is **not** expected to work on a typical JRuby-only setup. **Table layout:** names in the first column are **`bin/`** filenames (run as `bin/` from the repo root). Long options and examples sit **outside** the tables so PDF columns stay readable.
Script Role 2.0?
galaaz-bootstrap WSL2 helper: Docker checks; optional TinyTeX or poppler for gKnit PDF. Yes*
galaaz-jruby JRuby with repo lib/ on LOAD_PATH and required JVM flags (e.g. Arrow). Yes
galaaz_jruby_env.inc.sh Sourced by bash wrappers; sets GALAAZ_REQUIRED_JRUBY_J_ARGS. Yes†
install-tinytex Install TinyTeX for PDF output. Yes
\* Where WSL/Docker apply. **`galaaz-bootstrap` flags:** `--check`, `--apply`, `--runtime` (`docker` \| `local` \| `auto`), `--[no-]prompt-doc-tools`. † Not run directly. **`galaaz-jruby` examples** (from repo root): ```text bin/galaaz-jruby my_script.rb bin/galaaz-jruby -S rspec ``` ## Interactive use, examples, and Rake
Script Role 2.0?
gstudio IRB or Pry with Galaaz preloaded (JRuby + JVM flags). Yes
run_example Run one Ruby file using the same JRuby/JVM setup as tests. Yes
galaaz Forward arguments to rake (needs rake; usually JRuby). Yes
## gKnit and document drafts
Script Role 2.0?
gknit Knit .Rmd via JRuby and R Markdown render. Yes
gknit-draft Drafts from rticles-style templates; wrapper still uses legacy polyglot ruby. Legacy
gknit-draft.rb Ruby entry: GKnit.draft (use with JRuby + LOAD_PATH). JRuby
gknit_Rscript Polyglot Rscript launcher; hard-coded LOAD_PATH sample. No
**`gknit` CLI** (see `gknit -h`): `--output_format`, `--output_file`, `--output_dir`, `--bridge_timeout_sec`, `--callback_timeout_ms`. If `--output_format` is omitted, the **first** YAML `output:` target wins. Prefer **`galaaz-jruby`** for **`gknit-draft`** workflows until that wrapper matches the **`gknit`** stack. ## Tests
Script Role 2.0?
run_rspec Top-level specs/*_spec.rb with spec_helper (see docs/testing.md). Yes
run_all_rspec Compile ext/new_bridge; run specs/ and new_bridge_specs/ together. Yes
run_slow_rspec Suites under slow-specs/ (read script header for spec_helper). Yes
run_old_rspec Legacy suites under old_specs/. Yes
run_rspec_subset Numbered subset 1–18 (Documentation/Spec_Subsets.md). Yes
## Other
Script Role 2.0?
grun Graal-era launcher: polyglot ruby with --jvm. Use galaaz-jruby -S instead. No
gstudio_irb.rb / gstudio_pry.rb Loaded by gstudio; not meant to be run standalone. Yes
For day-to-day **2.0** use, rely on **`bin/galaaz-jruby`**, **`bin/gstudio`**, **`bin/gknit`**, **`bin/run_example`**, **`bin/run_rspec`** / **`bin/run_all_rspec`**, and **`bin/galaaz-bootstrap`** on WSL when using Dockerized R. Treat **`grun`**, **`gknit_Rscript`**, and the polyglot **`ruby`** invocation in **`gknit-draft`** as **legacy** until they are ported to the same JRuby path as **`gknit`**. # System Compatibility Typical development and CI targets: * **Linux** — recent Ubuntu LTS or comparable distributions (x86_64). * **macOS** — recent releases with JRuby and GNU R available. * **Windows** — use **WSL2** (same Linux stack as above); native Windows is not the primary target. The native **gatekeeper** component under `ext/new_bridge` is built with `make` and a C++ toolchain; see the project `README` if compilation fails on your platform. # Dependencies * **JRuby** — Galaaz 2.0 requires JRuby (tested with **10.1.1.0**) and a matching **JDK** (tested with **Java 21**). MRI Ruby is not supported. * **GNU R** — `R` and `Rscript` on your `PATH` (tested with **4.3.3**), plus a C++ toolchain (`g++`, `make`) and the **Rcpp** package to compile the gatekeeper. * **galaaz gem** — runtime dependency `msgpack` is pulled in by `gem install`. * Optional: **Docker** — if you run R in a container (common on WSL2); see bootstrap below. * Optional R packages for examples in this manual — e.g. `ggplot2`, `dplyr`, `knitr`, `kableExtra`, `arrow`, Bioconductor tools such as **DESeq2** (installed the usual R way). # Installation The supported install is **`gem install` + compile the gatekeeper**. You do not need a git clone. 1. Install **JRuby**, a compatible **JDK**, and **GNU R** (with `Rscript` and a C++ compiler). 2. In R, install **Rcpp**: `install.packages("Rcpp")`. 3. Install the gem: `jruby -S gem install galaaz` 4. Compile the native gatekeeper from the installed gem: ``` gem_dir="$(jruby -e "puts Gem::Specification.find_by_name('galaaz').full_gem_path")" make -C "${gem_dir}/ext/new_bridge" all ``` 5. Ensure **`R`** starts GNU R and can install packages (network access to CRAN when you first call `R.install_and_loads`). For **Apache Arrow** on Java 9+, pass `-J--add-opens=java.base/java.nio=ALL-UNNAMED` to JRuby (from a checkout, `bin/galaaz-jruby` does this). For **gKnit**, **knitr**, **rmarkdown**, and LaTeX (PDF output), install the corresponding R packages, **Pandoc**, and a TeX distribution if you need PDF; the repository includes helpers such as **`bin/install-tinytex`** where appropriate. A **table of all `bin/` scripts** (bootstrap, JRuby wrapper, gstudio, gknit, test runners, and which ones are legacy) is in the section **Command-line tools (`bin/`)** earlier in this manual. ### From a repository checkout (contributors) 1. Install **bundler** if needed, then run **`jruby -S bundle install`** in the repository root. 2. Build the bridge native code: **`make -C ext/new_bridge all`** (or **`rake compile_gatekeeper`**). 3. Run scripts with **`bin/galaaz-jruby`** (sources **`bin/galaaz_jruby_env.inc.sh`** and adds **`-I lib`**). A **gstudio** try image (JRuby + R + Galaaz already installed) is **`docker run --rm -it ghcr.io/rbotafogo/galaaz-try:gstudio`** (or **`./docker/try-gstudio/run.sh`** from a checkout). Maintainers can prove a RubyGems install on a throwaway Ubuntu machine (no repo inside the container) with **`./docker/cold-install/run.sh published-specs`**. ## Windows + WSL2 (optional: Docker / R in a container) If you run Galaaz on Windows through WSL2 and want containerized R instances, Docker Desktop is the supported setup. 1. Install Docker Desktop on Windows: - https://www.docker.com/products/docker-desktop/ 2. Open Docker Desktop and enable WSL integration: - Settings > Resources > WSL Integration - Enable integration for your target distro - Apply & Restart Docker Desktop 3. In WSL, run Galaaz bootstrap: > ruby bin/galaaz-bootstrap --apply > ruby bin/galaaz-bootstrap --check Expected result: - docker CLI available - docker compose available - docker daemon reachable (`docker info` works) If bootstrap reports daemon is unreachable, check Docker Desktop is running and WSL integration is enabled for the distro where Galaaz is installed. # Usage * Interactive shell: use 'gstudio' on the command line > gstudio ``` ruby vec = R.c(1, 2, 3, 4) puts vec ``` ``` ## [1] 1 2 3 4 ``` * Run all specs > galaaz specs:all * Run graphics slideshow (80+ graphics) > galaaz sthda:all * Run labs from Introduction to Statistical Learning with R > galaaz islr:all * See all available examples > galaaz -T Shows a list with all available executable tasks. To execute a task, substitute the 'rake' word in the list with 'galaaz'. For instance, the following line shows up after 'galaaz -T' rake master_list:scatter_plot # scatter_plot from:.... execute > galaaz master_list:scatter_plot # JRuby, multithreading, and the R bridge Galaaz 2.0 runs Ruby on **JRuby**, so your application can use **real parallel threads** for I/O-bound work (HTTP clients, database connections, message consumers, and so on). R itself is still executed in a **single GNU R process** behind the Galaaz bridge. When several Ruby threads call into R at the same time, the bridge **serializes** those calls: each request is matched to a reply using an internal per-call **queue**, so you do not need to add your own mutex around every `R.foo` from application threads. (You should still use normal Ruby synchronization when **Ruby** data structures are shared between threads—for example, when appending rows from each thread into a shared array before sending them to R.) A practical pattern is: 1. Use threads (or a connection pool) to read from **multiple databases or shards** in parallel. 2. Merge the rows in Ruby under a `Mutex` if you collect into one structure. 3. Hand the merged table to R **once** (for example with `R::Arrow.from_ruby_batches` and dplyr, or by building a data frame) so heavy statistics run in R with fewer bridge round-trips. A runnable sketch lives in `examples/multithread_shards_to_r/shards_to_r.rb` (simulated shard queries; swap in your DB driver). For concurrency tests on the bridge itself, see `specs/bridge_concurrent_spec.rb` and `specs/arrow_from_ruby_batches_spec.rb`. ## Long-running R calls and a completion block For R work that can take a long time, the bridge can avoid a Ruby-side **wait timeout** by scheduling the call and resuming in a **block** when the `RET` arrives. - **`R.eval_r_async(code, timeout: nil) { |result| ... }`** — string eval; on success, `result.value` is the same formatted string as **`R.eval_r`** (use `timeout: nil` for no Ruby-side limit). - **`R::Async.(...) { |result| ... }`** — same dispatch as **`R.(...)`**, but async; on success, `result.value` is an **`R::Object`** (or unboxed Ruby value / Symbol), like synchronous **`R.`**. Optional keyword **`timeout:`** applies a Ruby-side wait limit (completion receives **`NewBridge::SessionClient::TimeoutError`** if R is too slow). **Important:** **`R.foo(...) { |x| }`** is already used for dplyr-style scopes (`R::Support.new_scope`), so async R calls must use **`R::Async`** or **`R.eval_r_async`**, not a bare **`R.foo` with a block.** `NewBridge::EvalResult` exposes **`#ok?`**, **`#value`**, and **`#error`**. The completion block runs on a **background thread** (not the bridge reader thread). The example below is **plain Ruby** (no Rails). The R snippet sleeps (standing in for heavy work) and then returns an integer so the success branch shows a **non-nil** value. (`Sys.sleep` alone returns **NULL** in R; on success **`result.value`** is then **`nil`** in Ruby—that is expected, not a bridge error.) ``` ruby require 'thread' completion = Queue.new R.eval_r_async('({ Sys.sleep(0.3); 42L })', timeout: nil) do |result| if result.ok? puts "[completion] R finished; eval_r-style value: #{result.value.inspect}" else puts "[completion] R/bridge error: #{result.error.class}: #{result.error.message}" end completion.push(:done) end 3.times do |i| puts "[main] other Ruby work step #{i + 1}" sleep 0.05 end completion.pop puts "[main] R completion has run; exiting." ``` ``` ## [main] other Ruby work step 1 ## [main] other Ruby work step 2 ## [main] other Ruby work step 3 ## [completion] R finished; eval_r-style value: "[1] 42" ## [main] R completion has run; exiting. ``` In a **web application**, the HTTP response usually ends before R finishes, so you would not `Queue#pop` in the controller; you would persist an identifier, let the completion block write the outcome to storage, and notify the client (poll, WebSocket, Turbo Stream, etc.). The plain Ruby pattern above is only to show **when** the result exists (inside the block, or after data written there is observed elsewhere). Runnable specs live in **`new_bridge_specs/eval_r_async_spec.rb`**. ## Galaaz + Rails (JRuby) integration baseline This section documents the baseline we used to create a working Rails app with Galaaz in WSL. The goals were: 1. Rails boots under **JRuby**. 2. Galaaz is loaded from a local checkout (before publishing to RubyGems). 3. A request path can execute **`R.eval(...)`** and return a result. ### 1) Create the app with JRuby-friendly options Rails defaults can pull gems that are not ideal on JRuby-first setups (for example sqlite native extension paths and deployment extras). A minimal app avoids early friction: ```bash cd /home/rbotafogo/desenv_linux jruby -S rails new hedi --skip-git --minimal --skip-kamal --skip-solid --skip-active-record ``` Then install gems: ```bash cd /home/rbotafogo/desenv_linux/hedi jruby -S bundle install ``` ### 2) Use Galaaz as a local path gem For local development we keep a stable path: - `~/gems/galaaz` -> symlink to your Galaaz checkout - optional built gem archive in `~/gems/pkg/` In Rails `Gemfile`: ```ruby gem "galaaz", path: "/home/rbotafogo/gems/galaaz", require: false ``` And load after Rails boot in `config/application.rb`: ```ruby config.after_initialize { require "galaaz" } ``` Why `require: false` + `after_initialize`? In this integration, loading Galaaz too early via `Bundler.require` triggered Rails/JRuby initialization failures. ### 3) Simple request-path smoke test A direct smoke test from Rails runner: ```bash cd /home/rbotafogo/desenv_linux/hedi jruby -S bundle exec rails runner "puts R.eval('sum(c(1,2,3,4,5))').inspect" ``` Expected output: ```text 15.0 ``` ### 4) HTTP endpoint pattern For this baseline, a small Rack endpoint was the most stable first step to prove request-time R evaluation. (A full ActionController stack can be enabled later as the app evolves.) Minimal pattern: 1. Define a Rack app class under `lib/` that runs `R.eval(...)` and returns HTML/JSON. 2. Point a route to that Rack app (`root to: MyRackApp`). 3. Verify with browser/curl. ### 5) Running from WSL and opening from Windows Recommended bind: ```bash jruby -S bundle exec rails server -b 0.0.0.0 -p 3000 ``` Then open from Windows: - `http://localhost:3000` (usually works with WSL localhost forwarding), or - `http://:3000` if needed. In development, if Host Authorization blocks requests with unexpected Host headers, use: ```ruby # config/environments/development.rb config.hosts.clear ``` ### 6) Troubleshooting checklist - `Could not find ... in locally installed gems`: run `jruby -S bundle install` in the Rails app directory. - Stale PID after crash: remove `tmp/pids/server.pid`. - Local Galaaz path changed: verify `Gemfile` path target exists and rerun bundler. - R runtime issues: confirm GNU R is installed and on `PATH` in the same shell where Rails runs. As new Rails features are added (controllers, jobs, websockets, background rendering, plot generation), extend this section with concrete, runnable snippets and the associated operational checks. # Accessing R from Ruby One of the nice aspects of Galaaz is that variables and functions defined in R can be easily accessed from Ruby. For instance, to access the `mtcars` data frame from R in Ruby, we use the symbol `:mtcars` preceded by the `~` operator: `~R[:mtcars]` retrieves the value of the `mtcars` object in R. ``` ruby puts ~R[:mtcars] ``` ``` ## 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 ## 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 ## 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 ## 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 ## 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 ## 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 ## 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 ## 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 ``` ## Scoped symbols and lexical scoping Galaaz 2.0 uses **scoped symbols** by default. The canonical style is `R[:name]`: - `~R[:mtcars]` fetches an R object by name. - `R[:a] + R[:b]` builds an expression. - `R[:year].up_to(R[:day])` builds range expressions. If you prefer the terse `:x` syntax, you can opt in with lexical scoping using a Ruby refinement: ```ruby module MyScript using Galaaz::SymbolDSL def self.run expr = :a + :b puts expr puts ~:mtcars end end ``` `using Galaaz::SymbolDSL` is **lexically scoped**: only code in that module/file scope gets `:x` DSL behavior. Outside that scope, plain Ruby `Symbol` behavior is unchanged. To access an R function from Ruby, the R function needs to be preceded by `R.` scoping. Below we see an example of creating a R::Vector by calling the 'c' R function ``` ruby puts vec = R.c(1.0, 2.0, 3.0, 4.0) ``` ``` ## [1] 1 2 3 4 ``` Note that 'vec' is an object of type R::Vector: ``` ruby puts vec.class ``` ``` ## R::Vector ``` Every object created by a call to an R function will be of a type that inherits from R::Object. In R, there is also a function 'class'. In order to access that function we can call method 'rclass' in the R::Object: ``` ruby puts vec.rclass ``` ``` ## numeric ``` When working with R::Object(s), it is possible to use the '.' operator to pipe operations. When using '.', the object to which the '.' is applied becomes the first argument of the corresponding R function. For instance, function 'c' in R, can be used to concatenate two vectors or more vectors (in R, there are no scalar values, scalars are converted to vectors of size 1. Within Galaaz, scalar parameter is converted to a size one vector): ``` ruby puts R.c(vec, 10, 20, 30) ``` ``` ## [1] 1 2 3 4 10 20 30 ``` The call above to the 'c' function can also be done using '.' notation: ``` ruby puts vec.c(10, 20, 30) ``` ``` ## [1] 1 2 3 4 10 20 30 ``` We will talk about vector indexing in a later section. But notice here that indexing an R::Vector will return another R::Vector: ``` ruby puts vec[1] ``` ``` ## [1] 1 ``` Sometimes we want to index an R::Object and get back a Ruby object that is not wrapped in an R::Object, but the native Ruby object. For this, we can index the R object with the '>>' operator: ``` ruby puts vec >> 0 puts vec >> 2 ``` ``` ## 1.0 ## 3.0 ``` It is also possible to call an R function with named arguments, by creating the function in Galaaz with named parameters. For instance, here is an example of creating a 'list' with named elements: ``` ruby puts R.list(first_name: "Rodrigo", last_name: "Botafogo") ``` ``` ## $first_name ## [1] "Rodrigo" ## ## $last_name ## [1] "Botafogo" ``` Many R functions receive another function as argument. For instance, method 'map' applies a function to every element of a vector. With Galaaz, it is possible to pass a Proc, Method or Lambda in place of the expected R function. In this next example, we will add 2 to every element of our previously created vector: ``` ruby puts vec.map { |x| x + 2 } ``` ``` ## [1] 3 4 5 6 ``` # gKnitting a Document This manual has been formatted using 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. gKnit runs with **JRuby**, **GNU R**, and Galaaz. In gKnit, Ruby variables are persisted between chunks, making it an ideal solution for literate programming. Also, since it is based on Galaaz, Ruby chunks can have access to R variables and combining Ruby with R in one document is natural. 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 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, __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 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: ``` ruby 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 lst = R.readRDS("lst.rds") puts lst ``` ``` ## $a ## [1] 1 ## ## $b ## [1] 2 ## ## $c ## [1] 3 ``` 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 across chunks, then no overhead is needed: ``` ruby lst = R.list(a: 1, b: 2, c: 3) # any other code can be added here ``` ``` ruby puts lst ``` ``` ## $a ## [1] 1 ## ## $b ## [1] 2 ## ## $c ## [1] 3 ``` 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 (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/). ## gKnit and __R markdown__ 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. 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 access R variables (`~R[:name]`, `R.*`) through the **Galaaz bridge** while knitr drives **GNU R**—no GraalVM polyglot runtime is required. 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/ 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 '.Rmd' extension. This document has the following header for gKnitting an HTML document. ``` --- 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, 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 --- ``` For more information on the options in the Yaml header, [check here](https://bookdown.org/yihui/rmarkdown/html-document.html). ## Choosing the output format when calling gknit Yes: you can select the render target on the **command line**. **`bin/gknit`** (or **`gknit`** on your `PATH`) forwards options to **`rmarkdown::render`** via **`R::Rmarkdown.render`**. * **`--output_format FORMAT`** — name of the format, as in the YAML `output:` block. Examples: * **`html_document`** — HTML (often the default you list first under `output:`). * **`pdf_document`** — PDF (you need a working LaTeX setup, e.g. TinyTeX; see **`bin/install-tinytex`**). * **`md_document`**, **`github_document`**, or any other format defined in your YAML. * **`all`** — render **every** format declared under `output:` in the document (same idea as in R Markdown). If you **omit** **`--output_format`**, gknit passes **`NULL`** for the format argument. In that case **rmarkdown** uses the **first** format listed under **`output:`** in the YAML (and if none is specified there, behavior follows the usual rmarkdown defaults, typically HTML). Other useful flags: * **`--output_file NAME`** — output file name (optional path; see also **`--output_dir`**). * **`--output_dir DIR`** — directory for the rendered file (created if missing). * **`--bridge_timeout_sec`** / **`--callback_timeout_ms`** — longer R or install steps (see elsewhere in this manual). Examples (run from the directory where paths make sense, or use absolute paths): ```text bin/gknit blogs/manual/manual.Rmd bin/gknit --output_format html_document blogs/manual/manual.Rmd bin/gknit --output_format pdf_document blogs/manual/manual.Rmd bin/gknit --output_format all blogs/manual/manual.Rmd ``` Use **`gknit -h`** for the full option list. ## __R Markdown__ formatting Document formatting can be done with simple markups such as: ## Headers ``` # Header 1 ## Header 2 ### Header 3 ``` ## Lists ``` Unordered lists: * Item 1 * Item 2 + Item 2a + Item 2b ``` ``` Ordered Lists 1. Item 1 2. Item 2 3. Item 3 + Item 3a + Item 3b ``` For more R markdown formatting go to https://rmarkdown.rstudio.com/authoring_basics.html. ## 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, ...), an any optional chunk_label and options, as shown below: ```` ```{engine_name [chunk_label], [chunk_options]} ``` ```` 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: ```` ```{r first_r_chunk} vec <- c(1, 2, 3) print(vec) ``` ```` If this block is added to an __R markdown__ document and gKnitted the result will be: ``` r vec <- c(1, 2, 3) print(vec) ``` ``` ## [1] 1 2 3 ``` 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'. ```` ```{r second_r_chunk, echo = FALSE} vec2 <- c(10, 20, 30) vec3 <- vec * vec2 print(vec3) ``` ```` 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 ``` ## [1] 10 40 90 ``` A description of the available chunk options can be found in 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 ```` ```{r data_creation} r_vec <- c(1, 2, 3, 4, 5) reduce_sum <- function(...) { Reduce(sum, as.list(...)) } ``` ```` 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 r_vec <- c(1, 2, 3, 4, 5) reduce_sum <- function(...) { Reduce(sum, as.list(...)) } ``` We can, possibly in another chunk, access the vector and call the function as follows: ``` r print(r_vec) ``` ``` ## [1] 1 2 3 4 5 ``` ``` r print(reduce_sum(r_vec)) ``` ``` ## [1] 15 ``` ## 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: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 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. ``` r # load package and data library(ggplot2) data(mpg, package="ggplot2") mpg_select <- mpg[mpg$manufacturer %in% c("audi", "ford", "honda", "hyundai"), ] # Scatterplot theme_set(theme_bw()) # pre-set the bw theme. g <- ggplot(mpg_select, aes(displ, cty)) + labs(subtitle="mpg: Displacement vs City Mileage", title="Bubble chart") g + geom_jitter(aes(col=manufacturer, size=hwy)) + geom_smooth(aes(col=manufacturer), method="lm", se=F) ``` ``` ## `geom_smooth()` using formula = 'y ~ x' ``` ![](manual_files/figure-html/bubble-1.png) ## 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. ```` ```{ruby first_ruby_chunk} ``` ```` 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. ``` ruby a = [1, 2, 3] b = "US$ 250.000" c = "The 'outputs' function" vec = R.c(1, 2, 3) vec2 = R.c(10, 20, 30) ``` In the next block, variables 'a', 'vec' and 'vec2' are used and printed. ``` ruby puts a puts vec * vec2 ``` ``` ## 1 ## 2 ## 3 ## [1] 10 40 90 ``` Note that 'a' is a standard Ruby Array and 'vec' and 'vec2' are vectors that behave accordingly, where multiplication works as expected. ## 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: ```` This is some text with inline Ruby accessing variable 'b' which has value: ```{rb puts b} ``` and is followed by some other text! ````
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. ### 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 __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 __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: ```` ```{ruby heading} outputs "### #{c}" ``` ```` 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. Here, for instance, is a table definition in HTML and its output in the document: ```
Firstname Lastname Age
Jill Smith 50
Eve Jackson 94
```
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 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 '~R[:mtcars]'. ``` ruby R.install_and_loads('kableExtra') outputs (~R[:mtcars]).kable.kable_styling ```
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
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
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
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
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
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
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
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
## 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. ```` ```{include , relative = } ``` ```` 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 and can take a while. ```` ```{include model} ``` ```` ``` include require 'galaaz' # Loads the R 'caret' package. If not present, installs it R.install_and_loads 'caret' class Model attr_reader :data attr_reader :test attr_reader :train #========================================================== # #========================================================== def initialize(data, percent_train:, seed: 123) R.set__seed(seed) @data = data @percent_train = percent_train @seed = seed end #========================================================== # #========================================================== def partition(field) train_index = R.createDataPartition(@data.send(field), p: @percent_train, list: false, times: 1) @train = @data[train_index, :all] @test = @data[-train_index, :all] end end ``` ``` ruby mtcars = ~R[:mtcars] model = Model.new(mtcars, percent_train: 0.8) model.partition(:mpg) puts model.train.head puts model.test.head ``` ``` ## 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 ``` ## 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 Ruby’s standard library file `find.rb`. 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 on disk. ```` ```{include find, relative = FALSE} ``` ```` ``` include # frozen_string_literal: true # # find.rb: the Find module for processing all files under a given directory. # # # The +Find+ module supports the top-down traversal of a set of file paths. # # For example, to total the size of all files under your home directory, # ignoring anything in a "dot" directory (e.g. $HOME/.ssh): # # require 'find' # # total_size = 0 # # Find.find(ENV["HOME"]) do |path| # if FileTest.directory?(path) # if File.basename(path).start_with?('.') # Find.prune # Don't look any further into this directory. # else # next # end # else # total_size += FileTest.size(path) # end # end # module Find VERSION = "0.2.0" # # Calls the associated block with the name of every file and directory listed # as arguments, then recursively on their subdirectories, and so on. # # Returns an enumerator if no block is given. # # See the +Find+ module documentation for an example. # def find(*paths, ignore_error: true) # :yield: path block_given? or return enum_for(__method__, *paths, ignore_error: ignore_error) fs_encoding = Encoding.find("filesystem") paths.collect!{|d| raise Errno::ENOENT, d unless File.exist?(d); d.dup}.each do |path| path = path.to_path if path.respond_to? :to_path enc = path.encoding == Encoding::US_ASCII ? fs_encoding : path.encoding ps = [path] while file = ps.shift catch(:prune) do yield file.dup begin s = File.lstat(file) rescue Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP, Errno::ENAMETOOLONG, Errno::EINVAL raise unless ignore_error next end if s.directory? then begin fs = Dir.children(file, encoding: enc) rescue Errno::ENOENT, Errno::EACCES, Errno::ENOTDIR, Errno::ELOOP, Errno::ENAMETOOLONG, Errno::EINVAL raise unless ignore_error next end fs.sort! fs.reverse_each {|f| f = File.join(file, f) ps.unshift f } end end end end nil end # # Skips the current file or directory, restarting the loop with the next # entry. If the current file is a directory, that directory will not be # recursively entered. Meaningful only within the block associated with # Find::find. # # See the +Find+ module documentation for an example. # def prune throw :prune end module_function :find, :prune end ``` ## 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 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: ``` --- title: "gKnit - Ruby and R Knitting with Galaaz" author: "Rodrigo Botafogo" tags: [Galaaz, Ruby, R, JRuby, knitr, gknit] date: "29 October 2018" output: pdf\_document: includes: in\_header: ["../../sty/galaaz.sty"] number\_sections: yes --- ``` ## Template based documents generation When a document is converted to PDF it follows a certain conversion template. We've seen above the use of 'galaaz.sty' as a basic template to generate a PDF document. Using the 'gknit-draft' app that comes with Galaaz, the same .Rmd file can be compiled to different looking PDF documents. Galaaz automatically loads the 'rticles' R package that comes with templates for the following journals with the respective template name: * ACM articles: acm_article * ACS articles: acs_article * AEA journal submissions: aea_article * AGU journal submissions: ???? * AMS articles: ams_article * American Statistical Association: asa_article * Biometrics articles: biometrics_article * Bulletin de l'AMQ journal submissions: amq_article * CTeX documents: ctex * Elsevier journal submissions: elsevier_article * IEEE Transaction journal submissions: ieee_article * JSS articles: jss_article * MDPI journal submissions: mdpi_article * Monthly Notices of the Royal Astronomical Society articles: mnras_article * NNRAS journal submissions: nmras_article * PeerJ articles: peerj_article * Royal Society Open Science journal submissions: rsos_article * Royal Statistical Society: rss_article * Sage journal submissions: sage_article * Springer journal submissions: springer_article * Statistics in Medicine journal submissions: sim_article * Copernicus Publications journal submissions: copernicus_article * The R Journal articles: rjournal_article * Frontiers articles: ??? * Taylor & Francis articles: ??? * Bulletin De L'AMQ: amq_article * PLOS journal: plos_article * Proceedings of the National Academy of Sciences of the USA: pnas_article In order to create a document with one of those templates, use the following command: ``` gknit-draft --filename --template