Randomise at run time

This helper function constructs a timeline where the order of test elements (or blocks of test elements) is determined at run time.

randomise_at_run_time(
  label,
  logic,
  save_order = function(order, state, ...) save_result(state, label, order)
)

Arguments

label

(Character scalar) A label for storing the generated order of test elements.

logic

List where each top-level element corresponds to a randomisation unit. These randomisation units may be either single test elements, lists of test elements, or timelines.

save_order

A function called at run time to save the result of get_order. It should accept three arguments: order, state, and .... order corresponds to the output of get_order, whereas state corresponds to the participant's state object. The default setting saves the generated order in psychTestR's default results repository, under the label label.

Value

A list of test elements or equivalently a timeline that can be combined with other test elements or timelines. These test elements will be presented in a freshly randomised order for each participant.

Note

This function can be nested arbitrarily many times.

Examples

if (FALSE) {
join(
  randomise_at_run_time(
    "main",
    list(
      randomise_at_run_time(
        "1",
        list(one_button_page("1a"),
             one_button_page("1b"),
             one_button_page("1c"))
      ),
      randomise_at_run_time(
        "2",
        list(one_button_page("2a"),
             one_button_page("2b"),
             one_button_page("2c"))
      ),
      randomise_at_run_time(
        "3",
        list(one_button_page("3a"),
             one_button_page("3b"),
             one_button_page("3c"))
      )
    )
  )
) %>% join(final_page("End")) %>% make_test()
}