Reactive notebooks for R. Change a cell, and every cell that depends on it reruns, so what you see always matches the code.
Ember reads each cell's code to work out which variables it defines and which it uses, and keeps the notebook as a dependency graph. Cells run in the order the graph needs, not the order they appear on the page.
Status: early development, not yet on CRAN. Expect rough edges; see what's missing.
Rscript analysis.R gives the notebook's
results (with the same package versions), the file diffs cleanly in git,
and it opens in any editor.# install.packages("pak")
pak::pak("jowch/Ember")
Ember includes a little C code, so installing from source needs a compiler (Rtools on Windows, the Xcode command line tools on macOS).
Start Ember and open it in your browser:
srv <- ember::start_server()
It opens the start page and prints its link:
Ember is running at http://127.0.0.1:4321/?secret=...
Stop it by calling $stop() on the returned server, or by quitting R.
The link carries a key that changes each time Ember starts. If a browser tab says "This link needs Ember's current key", open the link printed in the R console; Ember prints it again when that happens.
The start page lists your notebooks. Click New
notebook, give it a name and a folder, and it opens. To open a notebook
you already have, use the start page's file field, or pass the file to
start_server("analysis.R"). From inside a notebook, the flame at the top
left or ⋯ → Open another notebook goes back to the start page.
A notebook you open from a file starts in safe preview: click Run this notebook to run it. Then write code in the cells. Shift+Enter runs a cell, and ⋯ → Keyboard shortcuts lists the rest. When you're done:
srv$stop()
Ember listens on port 4321 (or the next free port), on your machine only.
To use it on a remote machine, forward that port over SSH,
ssh -L 4321:localhost:4321 server, and open the address it prints. Behind
a proxy such as Posit Workbench or JupyterHub, pass the proxy's host name:
start_server("analysis.R", allowed_hosts = "workbench.example.org").
A proxy that serves Ember under a path prefix should redirect the bare
prefix to one with a trailing slash, as JupyterHub's server proxy does:
Ember never sees the prefix, so its relative links resolve one level too
high against a URL without that slash.
Packages from CRAN and Bioconductor need nothing more than library(dplyr):
Ember installs them into the notebook's own library, at the notebook's date.
For a package from GitHub or an r-universe, write the install call you would
anyway, then library() it:
remotes::install_github("lab/mypkg")
library(mypkg)
Ember reads the install call as where the package lives and records it in
the notebook. The call itself doesn't run, in Ember or in ember::run():
the notebook's lock decides what is installed, and the cell says so.
For a slider, text box or dropdown whose value is a variable, use the emberui package. Ember installs it like any other package. Moving the input reruns the cells that read the variable:
library(emberui)
n <- input_slider(10, 500, value = 100, step = 10)
hist(rnorm(n))
Under plain Rscript, n is the default, 100, once emberui is installed
(install.packages("emberui", repos = "https://jowch.r-universe.dev")). ?emberui::input_slider
lists the other inputs, and input_list() combines several into one.
To run a saved notebook from start to finish outside the browser, with the package versions it records:
ember::run("analysis.R")
Known gaps are tracked as GitHub issues, labelled P1 to P3 by priority, and the design is in docs/design.md.
Ember's browser interface is forked from Pluto.jl (MIT), by Fons van der Plas and the Pluto.jl authors. The logo's lettering is drawn from Instrument Sans (SIL Open Font License). See inst/COPYRIGHTS.
MIT