@pcllab/plugin-core v0.0.1

plugin-core

This plugin handles most of the core procedures of an experiment. The tasks that tasks that it can do include (but are not limited to) showing instructions, short-answer tasks, cued-recall tasks, ratings tasks, etc.

Table of contents

• Core
  • Parameters
    • Stimuli Parameters
    • Display Parameters
    • Timing Parameters
    • Miscellaneous Parameters
    • Stimulus Hyperparameters
  • Additional Features
    • Hook Functions
    • A note on done_callback
    • Feedback
    • Adaptive Spacing
    • Free Recall of Text
    • Free Recall of a Word List

Parameters

Stimuli Parameters

Display Parameters

Timing Parameters

Miscellaneous Parameters

Stimulus Hyperparameters

In addition to the parameters passed to jsPsych, the plugin has an additional layer of parameters specific to each stimulus in the stimuli object.

A quick example:

If we wanted one stimulus of our procedure to show 2 response boxes and display panels, we can do that by including certiain hyperparameters in the stimulus object.

[
    ...
    \\ Regular boring stimuli
    ...

    {
        cue: 'The ______ is ____',
        cue_panel_title: 'Fancy cue panel header',
        target_list: ['Earth', 'flat'],
        response_panel_title: 'Enter your honest opinion',
        response_count: 2
    }
]

The core plugin supports many ways for a subject to generate a response. The type of display is controlled by the response_type hyperparameter.

* Under construction

Additional Features

Hook Functions

The core plugin exposes an interface to hook into certain events during the trial. The on_stimulus_start and on_stimulus_end functions pass in a pluginAPI object as a parameter to the provided callbacks. Read more about the pluginAPI object in the Adaptive Spacing section.

A note on done_callback

The done_callback callback provides a way to dynamically retrieve the data produced by the procedure. The callback passes back a list containing datablocks pertaining to each trial of the procedure.

Keep in mind that the data produced may or may not contain all the parameters mentioned above, depending on how the plugin is configured.

A quick example:

function list_data(data) {
    data.forEach((datablock, index) => {
        console.log(`Data for stimulus ${index + 1}: `, datablock)
    })
}

...

jsPsych.init({
    ...
    timeline: [{
        type: pcllabCore,
        ...
        done_callback: list_data
    }]
})

/*
Data for stimulus 1: {
    cue: 'Example cue'
    cue_list: ['Cue 1', 'Cue 2', ...]
    rt: 1673
    rt_first_keypress: 534
    ...
}

Feedback

The callback feedback_html provides a way to show feedback after a screen given the feedback flag is set to true. The core plugin passes in a list of all the data recorded till that point. The plugin expects the provided callback to return some html that will be rendered on the screen.

    const trial = {
        type: pcllabCore,
        stimuli: [
            {
                cue: 'Should pineapples be on pizza',
                target: 'yes',
            },
        ],
        ...,
        feedback: true,
        feedback_html: (data) => {
            const lastData = data.slice(-1)[0]
            if (lastData.response === lastData.target) {
                return `<h4 class="text-center">You answered correctly</h4>`
            } else {
                return `<h4 class="text-center">You answered incorrectly</h4>`
            }
        }
    }

Adaptive Spacing

The pluginAPI object passed into certain hook functions as a parameter provides a set of functions that can be used to get information about the trial and modify the timeline.

pluginAPI.getAllData Datablock[] getAllData(void) Returns a list of all datablocks recorded till the present time.

pluginAPI.getLastData Datablock getLastData(void) Returns the most recent datablock recorded.

pluginAPI.getCompletedStimuli Stimulus[] getCompletedStimuli(void) Returns a list of all the stimuli blocks that were run till the present time.

pluginAPI.getRemainingStimuli Stimulus[] getRemainingStimuli(void) Returns a list of all the stimuli blocks in order that are still scheduled for execution.

pluginAPI.setTimeline void setTimeline(Stimulus[]) Sets the remaining timeline items to the list of stimuli.

Data Generated

This plugin collects the following data for each stimulus:

Examples

Instructions (Study Text)

Present instructions, or study a text, with a title and text

In this example, need to note how this.instructions is set up (it's calling in instructions.json)

const lookUp = {
  type: pcllabCore,
  stimuli: [this.instructions["look-up"]],
  response_count: 0,
  show_button: true,
  button_text: "Continue",
  data: {
    phase: "instructions",
  },
};

Study Words (Study Items)

Show how words or word pairs would be in a JSON, then how Core would read in that JSON word list. (Words, word pairs, key terms)

File would be word-list.json or word-pairs.json

Also explain how to show individual stimuli

Study Word Pairs

const studyItemsTrial = {
  type: pcllabCore,
  stimuli: [
    { response_type: "study_items", cue: "Kirvis", target: "Axe" },
    { response_type: "study_items", cue: "Marco", target: "Polo" },
  ],
  maximum_time: 5000,
  show_progress: true,
  response_count: 0,
};

Cued Recall

Explain how cued recall is done. Word as cue, or a question as cue. Box size differs.

const cuedRecallTrial = {
  type: pcllabCore,
  stimuli: [
    { response_type: "study_items", cue: "A", target: "Apple" },
    {
      response_type: "study_items",
      cue: "What is the answer to life the universe and everything?",
      target: "42",
    },
    { cue: "A", target: "Apple", response_count: 1 },
    {
      cue: "What is the answer to life the universe and everything?",
      target: "42",
      response_count: 1,
    },
  ],
  input_size: "small",
  response_count: 0,
  show_button: true,
};

Free Recall of Text

The title of a text is shown, with x-large response box. (Prompts can also be shown?)

Free Recall of a Word List

We have a specific way we do this.