Weave Reports

Introduction

In this tutorial, we show how to leverage JuliaHub to generate reproducible reports using Weave.jl.

Getting Started

Full code referenced by this tutorial can be found in this repository.

To access the code locally, first clone the project:

git clone https://github.com/JuliaComputing/WeaveReportsTutorial.jl

Then open the tutorial folder in VSCode and ensure that the working directory points to the tutorial's root folder (using pwd() in Julia's REPL). To activate the project, press ] key in the REPL to use the package mode, then type the following command:

pkg> activate .
pkg> instantiate

Using VSCode Extension

Launching the generation of a report through JuliaHub VSCode Extension is no different than the submission of any other script.

The file launcher-juliahub.jl contains the following code:

using Weave
using Dates

const xaxis = get(ENV, "xaxis", "sepal.length")
const yaxis = get(ENV, "yaxis", "petal.width")
const date = Dates.today()

const path_results = "$(@__DIR__)/results"
const report_name = "weave-iris"

weave("$(@__DIR__)/reports/$(report_name).jmd",
    out_path = "$(path_results)",
    fig_path = "$(path_results)/fig",
    doctype = "md2html",
    args = (date = date, xaxis = xaxis, yaxis = yaxis))

ENV["RESULTS_FILE"] = "$(path_results)/$(report_name).html"

The referenced report template is reports/weave-iris.jmd. This template as well as the above launcher script are identical to scripts intended to run locally. The only difference is the RESULTS_FILE environment variable used to specify the path of the report to be returned as a result file.

Since this launcher script is referring to another file (reports/weave-iris.jmd), some caution is needed to use valid paths. A simple trick is to use the absolute path provided by the @__DIR__ macro which returns the path of the file being executed.

Reports as an App

A convenient approach to leverage the reproducibily of Weave.jl reports is to use them as an application on JuliaHub, following the same principles as outlined in the introductory tutorial to applications.

As noted in the launcher scripts above, some arguments were passed to the report: xaxis, yaxis and date. Since applications allow the user to specify ENV variables during the launching process, reports as a JuliaHub's application are a convenient way to produce parametrized on-demand reports.

For example, after registering the WeaveReportsTutorial.jl as an application, we can now easily create a report based on any given xaxis and yaxis user-defined parameters:

The resulting html report shows that axis were set based on parameters passed through WEAVE_ARGS:

Known limitations

• Only html (md2html) reports are supported at the moment (md2pdf not available).
• GLMakie is not supported. If plots using Makie are desired, CairoMakie should be used instead.