Package 'tokr'

Description

Loading the package registers the engine tok, so a chunk written as ⁠```{tok}⁠ in R Markdown or Quarto holds a model. Chunk options:

Usage

eng_tok(options)

Arguments

Details

• tok.output: "svg" (default) draws the diagram; "check" prints the diagnostics; "fmt" prints the canonical text; "bpmn" prints the BPMN XML.

• tok.title: title drawn above the diagram.

• tok.lang: language of the messages (default: the option tok.lang, then "en").

• tok.export: a directory; every file of ⁠tok export⁠ is also written there.

The diagram is written as an SVG file and included like a figure (fig.cap and the other figure options apply), which suits HTML output; for PDF output use tok.output = "check" or include an exported picture.

Value

The chunk output, for knitr.

Examples

# the engine is registered when the package is loaded
if (requireNamespace("knitr", quietly = TRUE)) {
  is.function(knitr::knit_engines$get("tok"))
}

Description

tok_bpmn() exports BPMN 2.0 XML with diagram layout, which opens in Camunda Modeler and bpmn.io; tok_svg() draws the diagram. Both stop with the list of errors when the model has errors (see tok_check()).

Usage

tok_bpmn(x, file = NULL, lang = getOption("tok.lang", "en"))

tok_svg(x, file = NULL, title = NULL, lang = getOption("tok.lang", "en"))

Arguments

Value

The XML or SVG text; invisibly when written to file.

Examples

model <- system.file("examples", "wypozyczenie.tok", package = "tokr")
xml <- tok_bpmn(model)
substr(xml, 1, 120)
svg <- tok_svg(model, title = "Interlibrary loan")
nchar(svg)

Description

Runs the checks of ⁠tok check⁠: syntax, identifiers, flows, pools and lanes, decision tables, forms, simulation parameters and the BPMN 2.0 rules.

Usage

tok_check(
  x,
  lang = getOption("tok.lang", "en"),
  level = c("full", "analytic", "basic"),
  bpmn = TRUE
)

Arguments

Value

A data frame of class tok_diagnostics with the columns line, code, severity ("error", "warning" or "note"), id and message, one row per problem; no rows when the model has no problems.

Examples

tok_check('tok 0.3 "Example"
start s "Start"
task a "Work"
end e "End"
flow s -> a -> e')

Description

Evaluates a decision of the model for the given inputs, as ⁠tok eval⁠ does. In a model of language 0.7 the decision is evaluated with the decisions, input data and business knowledge models it requires, and the inputs are the input data by FEEL name; in earlier models the decision table alone is evaluated with the hit policy of the table.

Usage

tok_eval(x, decision, inputs = list(), lang = getOption("tok.lang", "en"))

Arguments

Value

In a model of language 0.7 the value of the decision (a number, string, logical value, list or named list; NULL for null), a list of named lists as a data frame. In earlier models: for the hit policies unique, first, any and priority a named list output name → value (NULL when no rule matches); for collect a data frame with one row per matched rule.

Examples

f <- system.file("examples", "propozycja-zakupu.tok", package = "tokr")
tok_eval(f, "tryb-akceptacji", list(rodzaj = "drukowana", cena = 120))

Description

Writes what ⁠tok export⁠ writes: NAME.bpmn, NAME.svg, one .dmn file per decision table and one .form file per form, ready to deploy to Camunda 8.

Usage

tok_export(x, dir = ".", name = NULL, lang = getOption("tok.lang", "en"))

Arguments

Value

The paths of the written files, invisibly.

Examples

out <- file.path(tempdir(), "tok-export")
files <- tok_export(system.file("examples", "propozycja-zakupu.tok", package = "tokr"),
                    dir = out)
basename(files)
unlink(out, recursive = TRUE)

Description

Prints the model as ⁠tok fmt⁠ does: one statement per line, canonical order of attributes, comments kept.

Usage

tok_fmt(x, write = FALSE, lang = getOption("tok.lang", "en"))

Arguments

Value

The canonical text (invisibly when the file is rewritten).

Examples

tok_fmt(system.file("examples", "wypozyczenie.tok", package = "tokr"))

Description

Reads a BPMN 2.0 file (for example drawn in Camunda Modeler) and returns the model as tok text, as ⁠tok import⁠ does.

Usage

tok_import(file, keep_ids = TRUE)

Arguments

Value

A tok_model; warnings about elements tok does not keep are in its element warnings and are also signalled.

Examples

bpmn <- tempfile(fileext = ".bpmn")
tok_bpmn(system.file("examples", "wypozyczenie.tok", package = "tokr"), file = bpmn)
m <- tok_import(bpmn)
m
unlink(bpmn)

Description

Shows the diagram in the RStudio or Positron viewer, or in the web browser.

Usage

tok_plot(x, title = NULL, lang = getOption("tok.lang", "en"))

Arguments

Value

The path of the temporary SVG file, invisibly.

Examples

if (interactive()) {
  tok_plot(system.file("examples", "wypozyczenie.tok", package = "tokr"))
}

Description

Reads a .tok file. The result can be passed to every other function of the package; they also accept the path of a .tok file or the text of a model directly.

Usage

tok_read(path)

Arguments

Value

An object of class tok_model: a list with the elements text, path and name (the file name without the extension).

Examples

m <- tok_read(system.file("examples", "wypozyczenie.tok", package = "tokr"))
m

Description

Runs the discrete-event simulation of ⁠tok sim⁠: cases arrive, wait for the resources of ⁠by=⁠, take the durations of ⁠duration=⁠ and choose flows by their conditions and probabilities, as the simulate, resource and variable statements of the model say. The same model and seed always give the same result, number by number the result of ⁠tok sim⁠ and of the Python package.

Usage

tok_sim(x, cases = NULL, seed = NULL, lang = getOption("tok.lang", "en"))

Arguments

Details

Times of the simulation are calendar times counted from ⁠start=⁠ of simulate. In the event log and the table of cases they are POSIXct values in UTC; a ⁠start=⁠ without a UTC offset is taken as UTC, so the clock times are those of ⁠tok sim --log⁠.

The event log has one row per activity instance, as ⁠tok sim --log⁠ writes it: the columns case, activity (identifier), label, resource ("" when the activity has no ⁠by=⁠), enqueue (when the case reached the activity), start (when a performer started the work; NA when the activity was interrupted while waiting), end (when it completed or was interrupted) and status ("completed" or "interrupted"). The columns case_id, activity_id (the label, or the identifier when the activity has no label), activity_instance_id (the row number), resource_id (NA when none), schedule (= enqueue) and complete (= end of completed instances, NA for interrupted ones) repeat them under the names process-mining packages expect. For example, with bupaR:

bupaR::activitylog(s$log, case_id = "case_id", activity_id = "activity_id",
                   resource_id = "resource_id",
                   timestamps = c("schedule", "start", "complete"))

Value

An object of class tok_sim, a list with the elements:

• kpi: the indicators of ⁠tok sim --json⁠, a list with seed; cases (a list of started, finished and by_end_event, a named integer vector of finished cases per end event); cycle_time (a list of mean_s, median_s and p90_s in seconds, NA without finished cases, and the same as short texts mean, median, p90); activities, a data frame with one row per activity (activity, label, count of completed instances, mean_wait_s, mean_processing_s, mean_wait, mean_processing); resources, a data frame with one row per resource (resource, label, count, utilization as a fraction); horizon_s, the simulated period in seconds; and warnings.

• log: the event log, a data frame described above.

• cases: a data frame with one row per case: case, start, end (NA for an unfinished case), end_event (NA for an unfinished case), cycle_time_s, and one column per case variable. A variable that holds a single value in every case is a vector (logical, numeric or character, NA where the case has no value; durations in seconds), any other a list; a variable named like one of the first five columns gets the prefix variable_.

• warnings: conditions or expressions the simulator could not evaluate.

• seed: the seed used, as a number.

• horizon: the simulated period in seconds, from the first arrival to the last event.

• report: the text report of ⁠tok sim⁠ in the language lang, which print() shows.

The object also keeps the model, the number of cases and the seed of the run, so tok_xes() can write its event log as XES.

as.data.frame() returns the event log. The function stops with the errors of the model (see tok_check()) and with the errors of the simulator as ⁠tok sim⁠ reports them, for example ⁠tok.sim.SimError: the process 'process' has no start event⁠.

Examples

f <- system.file("examples", "kwerenda-symulacja.tok", package = "tokr")
s <- tok_sim(f)
s
s$kpi$resources
head(s$log)
table(tok_sim(f, cases = 50, seed = 3)$cases$end_event)

Description

Version of the tok engine

Usage

tok_version()

Value

The version of the Rust engine compiled into the package.

Examples

tok_version()

Description

Writes the event log of tok_sim() as an XES document (IEEE 1849-2016, eXtensible Event Stream), the exchange format of process-mining tools such as ProM, pm4py, bupaR, Disco and Celonis; it is the file of ⁠tok sim --xes⁠.

Usage

tok_xes(
  x,
  file = NULL,
  cases = NULL,
  seed = NULL,
  lang = getOption("tok.lang", "en")
)

Arguments

Details

The log has one trace per case and up to three events per activity instance, with the transitions of the standard lifecycle model: schedule when the case reached the activity, start when a performer started the work and complete when it completed; an instance interrupted by a boundary timer ends with ati_abort when it was running and with withdraw when it was still waiting for a performer. Events carry concept:name (the label of the activity), concept:instance, org:resource, time:timestamp (with milliseconds and the UTC offset of ⁠start=⁠ of simulate) and activity (the identifier). Traces carry the case number, start, end, end_event, cycle_time_s and the case variables as typed attributes. See docs/simulation.md in the repository for the details.

Value

The XES text; invisibly when written to file.

Examples

f <- system.file("examples", "kwerenda-symulacja.tok", package = "tokr")
s <- tok_sim(f, cases = 20)
xes <- tempfile(fileext = ".xes")
tok_xes(s, xes)
substr(tok_xes(f, cases = 2, seed = 7), 1, 200)