finishTrial() affecting next timeline

[j-fielder]

Hi,
I have coded up a task where participants move a counter around a grid using the keyboard response plugin. To ‘win’, they must get the counter to the other edge from the start position, which then stops the task (they then repeat this, currently set up for 4 blocks). If they do not win, the task should automatically stop after 6 seconds. Each movement on the grid is set up as a trial which loops until they win, so the trial_duration option is only useful if they make no move at all (i.e. set to 6 seconds). To stop the task at 6 seconds, I have added a timer that starts from the first trial which calls finishTrial() and endCurrentTimeline() after time has elapsed, thanks to this discussion post.

This works (it stops the trial and ends the timeline after 6 seconds) but my issue is that the ‘postTrial’ screen (which is the next item in the timeline that shows a screen for 4 seconds, with no response required) is cleared by a keypress, which shouldn’t happen (my postTrial variable 'response_ends_trial: false' and I also set 'choices: jsPsych.NO_KEYS'). I am not sure why this is happening - it works fine if the trial ends because of a win, but not a timeout (i.e. if finishTrial() is run). If I run it without finishTrial() (i.e. just endCurrentTimeline()), the postTrial screen also works as it should do, but this is not a viable solution because it allows the current trial to be completed (even if time has elapsed). Similarly, if I put finishTrial() before endCurrentTimeline() in the code, it allows one more move after time has elapsed. I think this is a similar issue to this post that is unanswered. I have also tried to add a marker when the time has elapsed (end_test_timer_flag) to then allow no keys for 'choices' for the task, but this doesn't work.

Any insights into why finishTrial() is effecting the following timeline item would be much appreciated!!

As a secondary issue, I am finding finishTrial() to sometimes cause trials in the next block to skip, so the grid movement goes two squares at a time. I have not found a systematic explanation as to when or why this happens.

Here are the key snippets of code (full code below)

// Main variable for doing the grid task
var path = {
    type: 'canvas-keyboard-response',
    canvas_size: [squareSize*gridSize,squareSize*gridSize], 
    stimulus: drawGrid,
    choices: function() {
        if (tr==0) {return startAllowMoves}
        else if (end_test_timer_flag == 1) {return jsPsych.NO_KEYS} // if timed out, allow no moves (doesn't work)
        else {return allowMoves} 
    },
    trial_duration: gridTrialDuration, // this is a timeout for just 1 move (useful if no response given)
    on_load: function(){
        // set up the timer to end the current timeline after a certain duration, but only on the first trial
        if (tr == 0) {
            start_time = performance.now();
            end_test_timer = setTimeout(function() {
                end_test_timer_flag = 1;
                // this stuff is just for testing
                var end_time = performance.now();
                var elapsed_time = end_time - start_time;
                console.log("elapsed time: ", elapsed_time);
                // this function is all you need to end the current timeline
                jsPsych.endCurrentTimeline();
                // this function ends the current trial 
                jsPsych.finishTrial({status: "ended early"}); 
            }, time_limit);
        }
        tr+=1
        console.log('tr (move) = ' + tr)
    }, 
    
    data: {trialnumber: tr},
    on_finish: function(data) {
        if (data.key_press == leftKey) {xPos-=squareSize, data.move = "Left"}
        else if (data.key_press == upKey) {yPos-=squareSize, data.move = "Up"}
        else if (data.key_press == rightKey) {xPos+=squareSize, data.move = "Right"}
        else if (data.key_press == downKey) {yPos+=squareSize, data.move = "Down"}
        data.location = [xPos,yPos]
        gridBoundaries(xPos,yPos) // Define which moves are allowed depending on finishing position
        data.win  = checkIfOppositeEdge(xPos, yPos, xStartPos, yStartPos, gridSize, squareSize); // See if counter is now on opposite edge of grid than started
        win = data.win // update variable 'win' to use for setting the border colour
        data.movement = allowMoves
        // Save all moves into arrays
        grid_visitedLocs.push([xPos,yPos])
        grid_keysPressed.push(data.key_press)
        grid_rtList.push(data.rt)
        grid_timeElapsedList.push(data.time_elapsed)
        grid_wins.push(data.win)

        // clear the timer if task has been won
        if (win == 1) {
            clearTimeout(end_test_timer) 
            console.log('clearTimeout function called')
        }
    },
}

// Only run the path timeline until they win
var path_loop_node = {
    timeline: [path],
    loop_function: function(){
        // get the data from the previous trial and check if it was a win
        var data = jsPsych.data.get().last(1).values()[0];
        if(data.win == 0){ 
            return true;
        } else {
            if(data.win == 1) {console.log('trial was won, loop stopped')}
            return false;
        }}
}  

// Nested timeline for the main 'grid' variables
// put together so that 'end timeline' just ends this nested one (rather than whole block)
var loop_node_oneGrid = {
    timeline: [set_up, preTrial, path_loop_node] 
};

// Nested timeline for the after-grid variables 
var loop_node_afterGrid = {
    timeline: [postTrial, ITI],
};

// To loop over all timelines, until max number of blocks is reached
var loop_node_allTask = {
    timeline: [loop_node_oneGrid,loop_node_afterGrid],
    loop_function: function(){
      if (block == maxGridBlocks){ 
        return false;
      } else {
        block+=1
        console.log('block is ' + block)
        return true;
      }
    },
};

And here is the full file. Note that I am using version 6 because this task will be added onto an experiment that we already have custom plugins for using version 6.

// --------------------------------------------------------------------------------------------------------
// 1) Initialise variables and set up variables for the task  ---------------------------------------------
// (NB: others for the grid are initialised in the set_up function at the beginning of each set of trials)
// --------------------------------------------------------------------------------------------------------

timeline = []
let tr = 0
let block = 1

var gridSize = 5 // number of squares for the grid, e.g. 5x5
var squareSize = 70 // canvas size of each grid square
var maxGridBlocks = 4 // number of times each set will repeat 

var upKey = 87 //'w'
var downKey = 90 // 'z'
var leftKey = 65 //'a'
var rightKey = 83 //'s'

var agentColour = 'red'
var startBorderColour = 'purple'
var endBorderColour = 'turquoise'
var preTrialBorderColour = 'yellow'
var preTrialDuration = 2000 // in ms 
var ITIDuration = 2000 
var postTrialDuration = 4000 // in ms 
var gridTrialDuration = 6000 // in ms

var time_limit = 6000;
var start_time;
var end_test_timer;
var end_test_timer_flag;

// Get all possible start positions (using functions from below)
const startPositions = getOuterBorderCoordinates(gridSize, squareSize);
const shuffledStartPositions = shuffleStartPos(startPositions)

// initalise arrays for data saving later on
var grid_visitedLocs = []
var grid_moves = []
var grid_rtList = []
var grid_timeElapsedList = []
var grid_keysPressed = []
var grid_wins = []

// --------------------------------------------------------------------------------------------------------
// 2) Define functions needed for the task  ---------------------------------------------------------------
// --------------------------------------------------------------------------------------------------------

// Function to calculate all possible start coordinates depending on size of grid
function getOuterBorderCoordinates(gridSize, squareSize) {
    const startPositions = [];
    // Top edge (excluding corners)
    for (let xStartPos = squareSize; xStartPos < gridSize * squareSize - squareSize; xStartPos += squareSize) {
      startPositions.push({ xStartPos, yStartPos: 0 });
    }
    // Right edge (excluding corners)
    for (let yStartPos = squareSize; yStartPos < gridSize * squareSize - squareSize; yStartPos += squareSize) {
      startPositions.push({ xStartPos: gridSize * squareSize - squareSize, yStartPos });
    }
    // Bottom edge (excluding corners)
    for (let xStartPos = gridSize * squareSize - squareSize * 2; xStartPos >= squareSize; xStartPos -= squareSize) {
      startPositions.push({ xStartPos, yStartPos: gridSize * squareSize - squareSize });
    }
    // Left edge (excluding corners)
    for (let yStartPos = gridSize * squareSize - squareSize * 2; yStartPos >= squareSize; yStartPos -= squareSize) {
      startPositions.push({ xStartPos: 0, yStartPos });
    }
    return startPositions;
}

// Function to shuffle the start positions so they're in a random order
function shuffleStartPos(array) {
    for (let i = array.length - 1; i > 0; i--) {
      const j = Math.floor(Math.random() * (i + 1));
      [array[i], array[j]] = [array[j], array[i]];
    }
    return array;
}

// Function to determine if they've 'won' the trial (got to opposite side of grid), returns 1 if they have
function checkIfOppositeEdge(xPos, yPos, xStartPos, yStartPos, gridSize, squareSize) {
    const maxXPos = gridSize * squareSize - squareSize;
    const maxYPos = gridSize * squareSize - squareSize;
    
    const onOppositeEdgeX = (xPos === 0 && xStartPos === maxXPos) || (xPos === maxXPos && xStartPos === 0);
    const onOppositeEdgeY = (yPos === 0 && yStartPos === maxYPos) || (yPos === maxYPos && yStartPos === 0);
    
    // returns 1 if it's opposite (either X or Y) or 0 if not
    return onOppositeEdgeX || onOppositeEdgeY ? 1 : 0;
}

// Function to set the outer border colour depending on a win
function setBorderColour(win) {
    let border_colour;
    if (win === 0) {
      border_colour = startBorderColour;
    } else if (win === 1) {
      border_colour = endBorderColour;
    } 
    return border_colour;
}

// Function to draw the preTrial anticipatory period canvas (just outer box)
function preTrial_drawGrid(c) {
    // Render canvas
    var ctx = c.getContext("2d");
    // Outer border set colour:
    ctx.strokeStyle = preTrialBorderColour;
    ctx.lineWidth = 12;
    ctx.strokeRect(0,0,(squareSize*gridSize),(squareSize*gridSize))   
}

// Function to draw the grid for the main trials
function drawGrid(c) {
    // Render canvas
    var ctx = c.getContext("2d");
    // Draw grid area
    for (let i=0; i<gridSize; i++) {
        for (let j=0; j<gridSize; j++) {
            // inner squares:
            ctx.strokeStyle = 'black';
            ctx.lineWidth = 2;
            ctx.strokeRect((i*squareSize),(j*squareSize),squareSize,squareSize)
        }
    }
    // Outer border:
    ctx.strokeStyle = setBorderColour(win); // colour dependent on win
    ctx.lineWidth = 12;
    ctx.strokeRect(0,0,(squareSize*gridSize),(squareSize*gridSize))
    // Draw agent
    ctx.fillStyle = agentColour
    ctx.arc(xPos+(squareSize/2), yPos+(squareSize/2), (squareSize/2.5), 0, 2 * Math.PI) // start point is at top right of the square, so shift it over a bit. radius is a bit smaller than half the square size
    ctx.fill()
}

// Function to draw the grid for after the trial (held at final position)
function drawPostTrialGrid(c) {
    // Render canvas
    var ctx = c.getContext("2d");
    // Draw grid area
    for (let i=0; i<gridSize; i++) {
        for (let j=0; j<gridSize; j++) {
            // inner squares:
            ctx.strokeStyle = 'black';
            ctx.lineWidth = 2;
            ctx.strokeRect((i*squareSize),(j*squareSize),squareSize,squareSize)
        }
    }
    // Outer border:
    // FOR DEBUGGING PURPOSES, HAVE MADE THIS SCREEN GREEN (to tell when it goes onto postTrial timeline)
    //ctx.strokeStyle = setBorderColour(win); 
    ctx.strokeStyle = 'green'; // colour to mark that it's the posttrial screen
    ctx.lineWidth = 12;
    ctx.strokeRect(0,0,(squareSize*gridSize),(squareSize*gridSize))
    // Draw agent
    ctx.fillStyle = agentColour
    ctx.arc(xPos+(squareSize/2), yPos+(squareSize/2), (squareSize/2.5), 0, 2 * Math.PI) // start point is at top right of the square, so shift it over a bit. radius is a bit smaller than half the square size
    ctx.fill()
}

// Function to draw the ITI fixation cross
function drawITI(c) {
    // Render canvas
    var ctx = c.getContext("2d");
    // Set style for the cross lines
    ctx.strokeStyle = "black";
    ctx.lineWidth = 2;

    // Draw horizontal line
    ctx.beginPath();
    ctx.moveTo(c.width / 2 - 25, c.height / 2);
    ctx.lineTo(c.width / 2 + 25, c.height / 2);
    ctx.stroke();

    // Draw vertical line
    ctx.beginPath();
    ctx.moveTo(c.width / 2, c.height / 2 - 25);
    ctx.lineTo(c.width / 2, c.height / 2 + 25);
    ctx.stroke();
}


// Define boundaries for movement within grid, i.e. which keys they're allowed to press
function gridBoundaries(x,y) {
    // if within boundaries, allow all keys 
    if (0<x && x<((gridSize*squareSize)-squareSize) && 0<y && y<(gridSize*squareSize)-squareSize) {allowMoves = [leftKey,upKey,rightKey,downKey]}
    /// EDGES:
    // if on the left, don't allow left hand move
    else if (x==0 && 0<y && y<(gridSize*squareSize)-squareSize) {allowMoves = [upKey,rightKey,downKey]}
    // if on the furthest right, don't allow right hand move
    else if (x==((gridSize*squareSize)-squareSize) && 0<y && y<((gridSize*squareSize)-squareSize)) {allowMoves = [leftKey,upKey,downKey]}
    // if at the top, only allow down (or L/R)
    else if (0<x && x<((gridSize*squareSize)-squareSize) && y==0) {allowMoves = [leftKey,rightKey,downKey]}
    // if on bottom, only allow up (or L/R)
    else if (0<x && x<((gridSize*squareSize)-squareSize) && y==((gridSize*squareSize)-squareSize)) {allowMoves = [leftKey,upKey,rightKey]}
    // CORNERS:
    // if in top left corner, only allow down and right
    else if (x==0 && y==0) {allowMoves = [rightKey,downKey]}
    // if in bottom left corner, only allow down and right
    else if (x==0 && y==((gridSize*squareSize)-squareSize)) {allowMoves = [upKey,rightKey]}
    // if in bottom right corner only allow top and left
    else if (x==((gridSize*squareSize)-squareSize) && y==((gridSize*squareSize)-squareSize)) {allowMoves = [leftKey,upKey]}
    // if in top right corner, only allow down and left
    else if (x==((gridSize*squareSize)-squareSize) && y==0) {allowMoves = [leftKey,downKey]}
    return allowMoves;
    
}

// --------------------------------------------------------------------------------------------------------
// 3) Set up different variables to later push into the timeline ------------------------------------------
// --------------------------------------------------------------------------------------------------------

// Show anticipatory grid (just outer border) 
var preTrial = {
    type: 'canvas-keyboard-response',
    canvas_size: [squareSize * gridSize, squareSize * gridSize],
    stimulus: preTrial_drawGrid,
    trial_duration: preTrialDuration, 
    response_ends_trial: false, 
};

// Freeze the screen and just show final position
var postTrial = {
    type: 'canvas-keyboard-response',
    canvas_size: [squareSize * gridSize, squareSize * gridSize],
    choices: jsPsych.NO_KEYS,
    stimulus: drawPostTrialGrid, 
    trial_duration: postTrialDuration, 
    stimulus_duration: postTrialDuration,
    response_ends_trial: false, 
};

// Display ITI (fixation cross)
var ITI = {
    type: 'canvas-keyboard-response',
    canvas_size: [squareSize * gridSize, squareSize * gridSize],
    stimulus: drawITI,
    trial_duration: ITIDuration, //getRandomIntInclusive(6000, 8000)
    response_ends_trial: false, 
};

// To re-initialise grid task variables for every block
var set_up = {
    type: 'call-function',
    func: function() {
        tr = 0
        win = 0
        end_test_timer_flag = 0;
        // Need to set start positions, then they're updated depending on key presses (xPos and yPos)
        xStartPos = shuffledStartPositions[block].xStartPos 
        yStartPos = shuffledStartPositions[block].yStartPos

        // Define the first movements allowed dependent on start position (gets updates from there within function)
        startAllowMoves = gridBoundaries(xStartPos, yStartPos)

        // Initialise for the grid drawing
        xPos = xStartPos
        yPos = yStartPos
    }
}

// Main variable for doing the grid task
var path = {
    type: 'canvas-keyboard-response',
    canvas_size: [squareSize*gridSize,squareSize*gridSize], 
    stimulus: drawGrid,
    choices: function() {
        if (tr==0) {return startAllowMoves} // NB: needs to be defined for first trial, as allowMoves only updated based on next position. 
        else if (end_test_timer_flag == 1) {return jsPsych.NO_KEYS} // if timed out, allow no moves (doesn't work)
        else {return allowMoves} 
    },
    trial_duration: gridTrialDuration, // this is a timeout for just 1 move (useful if no response given)
    on_load: function(){
        // set up the timer to end the current timeline after a certain duration, but only on the first trial
        if (tr == 0) {
            start_time = performance.now();
            end_test_timer = setTimeout(function() {
            end_test_timer_flag = 1;
                // this stuff is just for testing
                var end_time = performance.now();
                var elapsed_time = end_time - start_time;
                console.log("elapsed time: ", elapsed_time);
                // this function is all you need to end the current timeline
                jsPsych.endCurrentTimeline();
                // this function ends the current trial 
                jsPsych.finishTrial({status: "ended early"});
            }, time_limit);
        }

        tr+=1
        console.log('tr = ' + tr)

    }, 
    
    data: {trialnumber: tr},
    on_finish: function(data) {
        if (data.key_press == leftKey) {xPos-=squareSize, data.move = "Left"}
        else if (data.key_press == upKey) {yPos-=squareSize, data.move = "Up"}
        else if (data.key_press == rightKey) {xPos+=squareSize, data.move = "Right"}
        else if (data.key_press == downKey) {yPos+=squareSize, data.move = "Down"}
        data.location = [xPos,yPos]
        gridBoundaries(xPos,yPos) // Define which moves are allowed depending on finishing position
        data.win  = checkIfOppositeEdge(xPos, yPos, xStartPos, yStartPos, gridSize, squareSize); // See if counter is now on opposite edge of grid than started
        win = data.win // update variable 'win' to use for setting the border colour
        data.movement = allowMoves
        // Save all moves into arrays
        grid_visitedLocs.push([xPos,yPos])
        grid_keysPressed.push(data.key_press)
        grid_rtList.push(data.rt)
        grid_timeElapsedList.push(data.time_elapsed)
        grid_wins.push(data.win)

        // clear the timer if task has been won
        if (win == 1) {
            clearTimeout(end_test_timer) 
            console.log('clearTimeout function called')
        }

    },
}

// Only run the path timeline until they win
var path_loop_node = {
    timeline: [path],
    loop_function: function(){
        // get the data from the previous trial and check if it was a win
        var data = jsPsych.data.get().last(1).values()[0];
        if(data.win == 0){ 
            return true;
        } else {
            if(data.win == 1) {console.log('task was won, loop stopped')}
            return false;
        }}
}  

// Nested timeline for the main 'grid' variables
// put together so that 'end timeline' just ends this nested one (rather than whole block)
var loop_node_oneGrid = {
    timeline: [set_up, preTrial, path_loop_node] 
};

// Nested timeline for the after-grid variables 
var loop_node_afterGrid = {
    timeline: [postTrial, ITI], 
};

// To loop over all timelines, until max number of blocks is reached
var loop_node_allTask = {
    timeline: [loop_node_oneGrid,loop_node_afterGrid],
    loop_function: function(){
      if (block == maxGridBlocks){ 
        return false;
      } else {
        block+=1
        console.log('block is ' + block)
        return true;
      }
    },
};

// Now push the final nested timeline for all screens
timeline.push(loop_node_allTask)
jsPsych.init({
    timeline: timeline
  });

[jodeleeuw]

Hi @j-fielder,

When you call jsPsych.finishTrial() outside the context of the plugin then it's possible that some of the events that the plugin sets up are still active. For example, if the plugin sets up an event to listen for a keyboard press and then end the trial, that event has to be cleared. In the plugin code we typically do this by ensuring that when the plugin ends there are no lingering events, and jsPsych.pluginAPI.cancelAllKeyboardResponses() (docs) is one way that can be done. It's probably safe to call this method right before you call .finishTrial(), though it's not a use case that we have tested extensively.

[j-fielder]

Thank you very much @jodeleeuw! adding in jsPsych.pluginAPI.cancelAllKeyboardResponses() right before calling jsPsych.finishTrial() has worked.