Alert function

When turned on, the alert function is called at the occurrence of certain task flow events such as task start/end, block changes and script errors. It can be used to insert your own initializaztion/clean-up code, start an external device before/after a task or get updates about the task progress.

Turning on and off the alert function

The alert function can be turned on/off with the [Alert] button on the main menu. The [Edit] button opens the current alert_function.m.

Structure of alert_function.m

The alert function must be named "alert_function.m" and have the following structure. The "hook" indicates the event at which the function is called, so place your code under appropriate case statements.

function alert_function(hook,MLConfig,TrialRecord)

    % 'task_end' and 'task_aborted' are mutually exclusive. If one occurs, the other does not.
    % If you want to run some clean-up code for both events, use 'fini'.
    switch hook
        case 'init'          % when the [RUN] button is clicked
		
        case 'task_start'    % when the task is started by '[Space] Start'
		
        case 'block_start'   % when a new block starts
		
        case 'trial_start'
		
        case 'trial_end'
		
        case 'block_end'
		
        case 'task_paused'   % when the task is paused with ESC
		
        case 'task_resumed'  % when the task is resumed by '[Space] Resume'
		
        case 'task_end'      % when the task is finished successfully
		
        case 'task_aborted'  % when the task is terminated with an error
		
        case 'fini'          % when the task window is closed
		
    end
	
end

If it is necessary to exchange information with the rest of the task code, use the TrialRecord.User field. For example, if you want to stop the task after a certain number of success trials, you can do it as below (although there are many other ways to do so).

        case 'trial_end'

            % It is assumed you recorded the success status of each trial with the trialerror()
            % function in your timing script.
            success_count = sum(0==TrialRecord.TrialErrors);

            % Also you assigned the maximum number of success trials that you want to run
            % to TrialRecord.User.max_success_trials in the timing script.
            if success_count == TrialRecord.User.max_success_trials
                TrialRecord.Pause = true;  % The task will be paused.
            end

Writing your own alert fuction

If you edit the alert function in the NIMH ML directory, the changes affect all the tasks that you run. If you want to customize the function only for a particular task, make a copy of it to the task directory and edit the copy. When "alert_function.m" is found both in the NIMH ML directory and your task directory, the one in the task directory has priority.

The "alert_function.Slack.m" file in the NIMH ML directory is an example that sends notifications to your smartphone via the Slack app. To try it, copy it to your task directory, rename the file to "alert_function.m" and follow the instructions in the file.