Skip to contents

Parsing justifications

Source: R/parse_justifications.R
parsing_justifications.Rd

This function is normally called by load_justifications(); however, sometimes it may be desirable to parse justifications embedded in more complex objects, for example as provided by yum::load_and_simplify(). Therefore, this function can also be called directly.

Usage

parse_justifications(
  x,
  justifierFields = "^date$|^framework$",
  fromFile = NULL,
  path = NULL,
  storeDecisionGraphSvg = FALSE,
  silent = TRUE
)

# S3 method for justifierDecisionGraph
print(x, ...)

# S3 method for justifierDecisionGraph
plot(x, ...)

Arguments

x

An object resulting from a call to yum::load_and_simplify().

justifierFields

Which fields to copy from justifier metadata to the elements within the specified scope.

fromFile

The file from which the justifier specifications were read.

path

The path holding these justifier specifications (not necessary if fromFile is provided).

storeDecisionGraphSvg

Whether to also produce (and return) the SVG for the decision graph.

silent

Whether to be chatty or quiet.

...

Additional arguments are passed on to graphics::plot() for the print method or to DiagrammeR::render_graph() for the plot method.

Value

The parsed justifier object.

Details

While there is some flexibility in how justifications can be specified, they are most easily processed further if they all follow the same conventions. This function ensures this. The convention is as follows:

  • all specifications are provided in four 'flat' lists, named after the types of elements they contain;

  • all elements have a unique identifier

  • all references to other elements are indeed only references to the other elements' id's in these 'flat lists'

Examples

### Specify an example text
exampleFile <-
  system.file("extdata",
              "simple-example.jmd",
              package="justifier");

### Show contents
cat(readLines(exampleFile), sep="\n");
#> This is an example of minutes that include
#> a source, an assertion, and a justification. For example, in
#> the meeting, we can discuss the assertion that sleep deprivation
#> affects decision making. We could quickly enter this assertion in
#> a machine-readable way in this manner:
#> 
#> ---
#> assertion:
#>  -
#>    id: assertion_SD_decision
#>    label: Sleep deprivation affects the decision making proces.
#>    source:
#>      id: source_Harrison
#> ---
#> 
#> Because it is important to refer to sources, we cite a source as well.
#> We have maybe specified that source elsewhere, for example in the
#> minutes of our last meeting. That specification may have looked
#> like this:
#> 
#> ---
#> source:
#>  -
#>    id: source_Harrison
#>    label: "Harrison & Horne (2000) The impact of sleep deprivation on decision making: A review."
#>    xdoi: "doi:10.1037/1076-898x.6.3.236"
#>    type: "Journal article"
#> ---
#> 
#> We can now refer to these two specifications later on, for
#> example to justify decisions we take.

### Load it with yum::load_and_simplify()
loadedMinutes <- yum::load_and_simplify(exampleFile);

### Show contents
names(loadedMinutes);
#> [1] "assertion" "source"   

### Parse 'manually'
parsedJustifications <- justifier::parse_justifications(loadedMinutes);

### Show contents
names(parsedJustifications);
#> [1] "raw"            "structured"     "logging"        "frameworks"    
#> [5] "fwApplications" "supplemented"   "decisionTrees"  "decisionGraphs"