Package 'rhylthyme'

The program as a list

Description

The parsed program JSON, unchanged. jsonlite::toJSON(as.list(p), auto_unbox = TRUE, null = "null", digits = NA) turns it back into the program's JSON, and p$json holds the text exactly as it was read.

Usage

## S3 method for class 'rhylthyme_program'
as.list(x, ...)

Arguments

x	A rhylthyme_program.
...	Unused.

Value

A list.

---

A finished plot of a Rhylthyme program

Description

ggplot(program) + geom_rhylthyme() with theme_rhylthyme() and the program's name as the title. With one lane per track the fill legend only repeats the lane names, so it is left out. Add to it like any ggplot.

Usage

## S3 method for class 'rhylthyme_programs'
autoplot(object, ...)

## S3 method for class 'rhylthyme_run'
autoplot(object, ...)

## S3 method for class 'rhylthyme_program'
autoplot(object, ...)

Arguments

object	A rhylthyme_program.
...	Passed on to geom_rhylthyme() (e.g. lanes = "task", collapse_replicates = TRUE).

Value

A ggplot.

Examples

library(ggplot2)
p <- read_rhylthyme(system.file("extdata", "breakfast_schedule.json", package = "rhylthyme"))
autoplot(p)
autoplot(p, lanes = "task")

---

Turn programs into plotting data

Description

One row per step: the columns of steps(), plus program (a factor, for faceting), step_key (the step id, prefixed by the program within a set of programs, so it is unique), track (a factor in authored order; tracks with the same name share a level, and a colour), the lane factors lane (by track), step_lane and task_lane (see lanes in geom_rhylthyme(); levels run bottom to top so the first track or step is drawn at the top, and within a set each program's lanes are its own), and range_min / range_max (a variable step's shortest and longest end; NA otherwise). start, end and the ranges are seconds from program start, or clock times for programs read with start_at / finish_at; they carry a class that makes ggplot2 use scale_x_rhylthyme() (or scale_x_rhylthyme_clock()) by default, as track does for scale_fill_rhylthyme() and the lanes for scale_y_rhylthyme(). The program rides along as the "rhylthyme_program" attribute, for geom_rhylthyme()'s arrows and replicate collapsing.

Usage

## S3 method for class 'rhylthyme_program'
fortify(model, data, ...)

## S3 method for class 'rhylthyme_programs'
fortify(model, data, ...)

## S3 method for class 'rhylthyme_run'
fortify(model, data, ...)

Arguments

model	A rhylthyme_program or rhylthyme_programs().
data	Ignored.
...	Ignored.

Value

A data frame.

---

Plot a Rhylthyme schedule

Description

geom_rhylthyme() draws one bar per step, from its start to its end, in one lane per track, with arrows for dependencies between lanes and step names on (or beside) the bars. With a program as the plot's data (ggplot(program) + geom_rhylthyme()), the aesthetics default to xmin = start, xmax = end, y = lane, fill = track, step = step_id and label = name, and the arrows come from the program's dependencies(); anything you map or pass yourself wins. The geom also works by name: geom = "rhylthyme".

Usage

geom_rhylthyme(
  mapping = NULL,
  data = NULL,
  stat = "rhylthyme",
  position = "identity",
  ...,
  arrows = TRUE,
  labels = TRUE,
  ranges = TRUE,
  estimates = TRUE,
  lanes = c("track", "step", "task"),
  collapse_replicates = FALSE,
  dependencies = NULL,
  label_size = 3,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_rhylthyme(
  mapping = NULL,
  data = NULL,
  geom = "rhylthyme",
  position = "identity",
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping	Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.
data	The data to be displayed in this layer. There are three options: If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot(). A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created. A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).
stat	The statistical transformation to use on the data for this layer. When using a ⁠geom_*()⁠ function to construct a layer, the stat argument can be used to override the default coupling between geoms and stats. The stat argument accepts the following: A Stat ggproto subclass, for example StatCount. A string naming the stat. To give the stat as a string, strip the function name of the stat_ prefix. For example, to use stat_count(), give the stat as "count". For more information and other ways to specify the stat, see the layer stat documentation.
position	A position adjustment to use on the data for this layer. This can be used in various ways, including to prevent overplotting and improving the display. The position argument accepts the following: The result of calling a position function, such as position_jitter(). This method allows for passing extra arguments to the position. A string naming the position adjustment. To give the position as a string, strip the function name of the position_ prefix. For example, to use position_jitter(), give the position as "jitter". For more information and other ways to specify the position, see the layer position documentation.
...	Other arguments passed on to ggplot2::layer(), such as colour = "white".
arrows	Draw dependency arrows between lanes, as curves the way rhylthyme.com draws them: a sweep into the waiting step's start, or an S-curve between the two bars when they are close. Solid for a step that waits for another; dashed when it starts before the other ends (a negative offset); dotted for a step that runs only if the other aborts.
labels	Draw each bar's label: inside the bar when it fits, else just after it when the lane has room, else not at all.
ranges	Show each variable step's range: a faded extension from its planned end to its longest, and a thin line under the bar from its shortest to its longest.
estimates	Outline, dotted, the bars whose length is an estimate (instrument steps with no duration, indefinite steps, and durations ⁠rhylthyme plan⁠ filled in), as rhylthyme.com does.
lanes	What each lane is, for a program as the data: "track" (the default; one lane per track, as on rhylthyme.com), "step" (one lane per step, a classic Gantt; step names are then on the axis, so bars get no label unless you map one) or "task" (one lane per resource type, so contention shows). In any mode, bars that overlap in a lane are stacked so none hides another.
collapse_replicates	Draw one bar per authored step instead of one per replicate instance, spanning all its instances and labelled with the count (only for a program as the data; steps() is unaffected).
dependencies	A data frame with from_step, to_step and relation (and offset), as dependencies() returns, matched to the step aesthetic. Taken from the program when the plot's data is one.
label_size	Label text size, in mm (as ggplot2::geom_text()'s size).
na.rm	If FALSE, the default, steps with no computed time are removed with a warning; if TRUE, silently.
show.legend	logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display. To include legend keys for all levels, even when no data exists, use TRUE. If NA, all levels are shown in legend, but unobserved levels are omitted.
inherit.aes	If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. annotation_borders().
geom	The geometric object to use to display the data for this layer. When using a ⁠stat_*()⁠ function to construct a layer, the geom argument can be used to override the default coupling between stats and geoms. The geom argument accepts the following: A Geom ggproto subclass, for example GeomPoint. A string naming the geom. To give the geom as a string, strip the function name of the geom_ prefix. For example, to use geom_point(), give the geom as "point". For more information and other ways to specify the geom, see the layer geom documentation.

Details

Aesthetics: xmin, xmax and y (required); fill, colour, alpha, linewidth, linetype; label (the text for each bar), step (the id the dependencies table refers to), xlower and xupper (a variable step's shortest and longest end) and estimate (TRUE for an estimated length). For a program these default to range_min, range_max and estimate.

Value

A layer to add to a plot.

Examples

library(ggplot2)
p <- read_rhylthyme(system.file("extdata", "breakfast_schedule.json", package = "rhylthyme"))
ggplot(p) + geom_rhylthyme()
ggplot(p) + geom_rhylthyme(labels = FALSE)

---

Read a Rhylthyme program

Description

Reads a Rhylthyme program (JSON), checks it against the program schema and times every step with the same engine rhylthyme.com uses.

Usage

read_rhylthyme(x, validate = TRUE, start_at = NULL, finish_at = NULL)

Arguments

x	The program: a path to a JSON file, an ⁠http(s)://⁠ URL (a rhylthyme.com program page, ⁠.../p/<id>⁠, or share link, ⁠...?share=<id>⁠, is read through the site's public API), a JSON string, or a list (as from jsonlite::read_json(), or built in R; a length-one vector becomes a JSON scalar, so wrap a one-element array in list() or I()).
validate	If TRUE, the default, a program that breaks the schema is an error listing every problem (see validate_rhylthyme()). FALSE reads it anyway, for drafts; steps are then timed as far as the engine can.
start_at, finish_at	Anchor the program to the clock: when it starts, or when its last step should end ("everything ready at 6 pm"). A POSIXct or a string as.POSIXct() understands, in the local time zone. Give one at most. steps() then adds start_time and end_time, and plots have a clock-time axis.

Value

A rhylthyme_program: a list with the program's name, description, schema_version and source, the steps, tracks and dependencies tables (see steps()), the parsed program and its json text, and start_at when anchored. Times are seconds from program start.

Examples

p <- read_rhylthyme(system.file("extdata", "breakfast_schedule.json", package = "rhylthyme"))
p
read_rhylthyme('{"programId": "tea", "name": "Tea", "resourceConstraints": [],
  "tracks": [{"trackId": "kettle", "name": "Kettle",
  "steps": [{"stepId": "boil", "name": "Boil", "duration": {"type": "fixed", "seconds": 180},
  "startTrigger": {"type": "programStart"}}]}]}')
# Everything ready at 6 pm
p <- read_rhylthyme(system.file("extdata", "breakfast_schedule.json", package = "rhylthyme"),
  finish_at = "2026-11-26 18:00")
steps(p)[c("name", "start_time", "end_time")]

---

Read a Rhylthyme run record

Description

A run record (the runs schema) is what actually happened when a program was run: when each step really started and ended, and what ended it. It is written by the rhylthyme runner and by rhylthyme.com.

Usage

read_rhylthyme_run(x, program = NULL, validate = TRUE, clock = TRUE)

Arguments

x	The run record: a path, an ⁠http(s)://⁠ URL, a JSON string or a list, as for read_rhylthyme().
program	The program that was run (a rhylthyme_program, or anything read_rhylthyme() accepts). Optional, but it gives each step its track, name and task, maps replicate instances to the program's step ids, and brings the dependency arrows; without it, steps are named by id and share one lane.
validate	Check the record against the runs schema (see read_rhylthyme()).
clock	If TRUE, the default, times are anchored at the record's startedAt: steps() adds start_time and end_time, and plots have a clock-time axis. FALSE keeps elapsed seconds.

Value

A rhylthyme_run: a list with name, run_id, program_id, program_version, started_at, ended_at, outcome (completed, aborted or abandoned), context, the steps table and the parsed record. The steps table has one row per step in the record: the program's step_id and track columns, the actual start, end and duration (seconds from startedAt; NA for a step that never started), status (completed, aborted, skipped, unfinished or not_started), ended_by, failed (an instrument command failed at least once) and last_code (its last reply), and the plan the runner had (planned_start, planned_end).

Examples

extdata <- function(f) system.file("extdata", f, package = "rhylthyme")
dinner <- read_rhylthyme(extdata("thanksgiving_one_oven.json"))
run <- read_rhylthyme_run(extdata("thanksgiving_one_oven.run.json"), program = dinner)
run
steps(run)[c("name", "start", "end", "status")]
autoplot(run)

---

Versions of the embedded engine and the schemas it reads

Description

rhylthyme_engine_version() is the version of the @rhylthyme/timeline timing engine this package carries: step times match rhylthyme.com's for that engine version. rhylthyme_schema_versions() lists the program schemaVersions read_rhylthyme() accepts.

Usage

rhylthyme_engine_version()

rhylthyme_schema_versions()

Value

A character vector.

Examples

rhylthyme_engine_version()
rhylthyme_schema_versions()

---

The web timeline's colour palettes

Description

Read from the embedded engine, so they are exactly rhylthyme.com's.

Usage

rhylthyme_palettes()

Value

A named list of character vectors of hex colours.

Examples

names(rhylthyme_palettes())
rhylthyme_palettes()$classic

---

Several Rhylthyme programs together

Description

Combines programs so they can be tabulated and plotted together: steps(), tracks(), dependencies() and resources() stack each program's table with a program column, and a plot keeps each program's lanes separate (facet with facet_wrap(~ program, scales = "free_y"), or use autoplot()). Step ids may repeat between programs: plots match dependencies within a program only. c(p1, p2) does the same.

Usage

rhylthyme_programs(...)

Arguments

...	rhylthyme_programs, runs from read_rhylthyme_run(), or sets of them. Argument names become the program labels; otherwise each program's name is used, made unique.

Value

A rhylthyme_programs.

Examples

library(ggplot2)
breakfast <- read_rhylthyme(system.file("extdata", "breakfast_schedule.json", package = "rhylthyme"))
both <- rhylthyme_programs(Saturday = breakfast, Sunday = breakfast)
both
autoplot(both)

---

Scales for Rhylthyme plots

Description

A program plotted with geom_rhylthyme() picks these by default: its bars are filled by track from rhylthyme.com's palette, and its time axis reads as elapsed time (or clock time, when the program was read with start_at or finish_at). Add one yourself to change its options; any other ggplot2 scale replaces them as usual.

Usage

scale_fill_rhylthyme(palette = "classic", ..., aesthetics = "fill")

scale_colour_rhylthyme(palette = "classic", ..., aesthetics = "colour")

scale_color_rhylthyme(palette = "classic", ..., aesthetics = "colour")

scale_x_rhylthyme(
  name = ggplot2::waiver(),
  breaks = elapsed_breaks,
  labels = ggplot2::waiver(),
  ...
)

scale_y_rhylthyme(...)

scale_x_rhylthyme_clock(name = ggplot2::waiver(), ...)

Arguments

palette	A palette name: one of names(rhylthyme_palettes()).
aesthetics	The aesthetics the scale applies to.
name, breaks, labels, ...	Passed on to the underlying ggplot2 scale.

Details

• scale_fill_rhylthyme() / scale_colour_rhylthyme(): the web timeline's palettes, in the same order (colours repeat, as on the web, when there are more tracks than colours). See rhylthyme_palettes().

• scale_x_rhylthyme(): seconds from program start, labelled m:ss, or h:mm once the axis reaches an hour, at round breaks (1, 5, 15 or 30 minutes, 1 or 2 hours, ...). Titled "Elapsed (m:ss)" or "Elapsed (h:mm)" unless you give a title.

• scale_x_rhylthyme_clock(): clock times, for an anchored program; a ggplot2::scale_x_datetime() titled "Clock time".

• scale_y_rhylthyme(): the lanes, labelled by track, step or task name (within a set of rhylthyme_programs() each program's lanes are its own even when names repeat).

Value

A ggplot2 scale.

Examples

library(ggplot2)
p <- read_rhylthyme(system.file("extdata", "breakfast_schedule.json", package = "rhylthyme"))
ggplot(p) + geom_rhylthyme() + scale_fill_rhylthyme("cookbook")
ggplot(p) + geom_rhylthyme() + scale_x_rhylthyme(name = "Time since start")

---

Tables from a Rhylthyme program

Description

Each returns a plain data frame, ready for dplyr and ggplot2.

Usage

steps(x, ...)

tracks(x, ...)

dependencies(x, ...)

resources(x, ...)

## S3 method for class 'rhylthyme_program'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'rhylthyme_program'
tidy(x, ...)

Arguments

x	A rhylthyme_program.
...	Unused.
row.names, optional	Unused; for compatibility with as.data.frame().

Details

• steps(): one row per step, replicate instances included, in authored order: track_id, track_name, track_index, step_id, name, task, start and end (seconds from program start, as the engine times them), duration, resolved (FALSE when the engine could not place the step), duration_type (fixed, variable, indefinite or instrument), min_seconds and max_seconds (the authored range), estimate (the planned length is a guess: instrument steps with no duration, indefinite steps, and durations ⁠rhylthyme plan⁠ filled in), trigger_type, and for a replicate instance instance_of (the authored step) and instance_index. For a program read with start_at or finish_at, also start_time and end_time (POSIXct). as.data.frame() and tidy() give the same table.

• tracks(): one row per track as the engine lays them out (replicate and template tracks included): track_id, name, track_index, parent_track_id, template_id, n_steps, start, end.

• dependencies(): one row per trigger that refers to another step: from_step, to_step, relation (end_to_start, start_to_start or on_abort), offset in seconds (buffers included; negative for a hand-off before the other step ends), trigger_type, and logic (all or any) for a trigger inside a compound one.

• resources(): one row per task: task, max_concurrent (NA for a task steps use that has no constraint), description, n_steps.

Value

A data frame.

Examples

p <- read_rhylthyme(system.file("extdata", "breakfast_schedule.json", package = "rhylthyme"))
steps(p)
tracks(p)
dependencies(p)
resources(p)

---

Summarise a Rhylthyme program

Description

Summarise a Rhylthyme program

Usage

## S3 method for class 'rhylthyme_program'
summary(object, ...)

Arguments

object	A rhylthyme_program.
...	Unused.

Value

A summary.rhylthyme_program: a list with name, schema_version, makespan (seconds), n_steps, n_estimated, n_unresolved, and the tracks() and resources() tables. Printing it shows each track's steps and time span, and each resource's limit.

Examples

summary(read_rhylthyme(system.file("extdata", "breakfast_schedule.json", package = "rhylthyme")))

---

A clean theme for Rhylthyme timelines

Description

A minimal theme for Gantt charts: light vertical grid lines on the time axis, none between lanes, no y-axis title (the lanes name themselves) and the legend underneath.

Usage

theme_rhylthyme(base_size = 11, base_family = "")

Arguments

base_size, base_family

Base font size (pt) and family.

Value

A ggplot2 theme.

Examples

library(ggplot2)
p <- read_rhylthyme(system.file("extdata", "breakfast_schedule.json", package = "rhylthyme"))
ggplot(p) + geom_rhylthyme() + theme_rhylthyme()

---

Check a Rhylthyme program against the schema

Description

Lists every problem the program schema finds, each tied to the step (or track) it is in. read_rhylthyme() runs the same check and stops on the first invalid program; use this to see all the problems as a table.

Usage

validate_rhylthyme(x)

Arguments

x	A program: anything read_rhylthyme() accepts, or a rhylthyme_program.

Value

A data frame with one row per problem (none when the program is valid): track_id, step_id (NA where the problem is not inside a track or step, or the step has no id), where (the field, relative to the step or track), message and path (a JSON pointer into the program).

Examples

validate_rhylthyme('{"name": "Draft", "tracks": [{"trackId": "a", "steps": [{"name": "x"}]}]}')

---