Custom Stimulus Functions

It is possible to write your own parametric stimulus function. To do so, write a MATLAB m-file function and store it in [ScanImage® Installation Directory]\+scanimage\+mroi\+stimulusfunctions\. The function should be in the form:

[xx,yy] = stimFunction(tt,[additional optional arguments])

The input and output arguments are as follows:

tt

A vector of linearly increasing times. It is commonly normalized before use in parameterized equations.

xx

A column vector of the same size as tt consisting of the X-component of the position for each time in tt.

yy

A column vector of the same size as tt consisting of the Y-component of the position for each time in tt.

The size of tt depends on the number of ROIs in the ROI Group Editor. By default, the number of points to define all the ROIs in an ROI Group is 10,000. This number is divided equally between each of the ROI. Thus, an ROI Group consisting of

  • Pause function

  • Logspiral function

  • Pause function

  • Sinesquare function

will have 2,500 points of definition per ROI.

The x and y position should range from -1 to 1. The size, location and rotation of the stimulus function is defined by the size, location, and rotation of the drawn ROI in the ROI Group Editor.

Note

the x and y components of an ROI’s location and size as well as its rotation can all be precisely defined by entering them in via the fields in the bottom right of the ROI Group Editor.

Optional arguments can be used to further parameterize the function. For instance, the log spiral function has a ‘revolutions’ parameter which is used to define the number of turns in the spiral.


Example

The \+scanimage\+mroi\+stimulusfunctions\logspiral.m function can be taken as an example of stim function for creating a new function.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
function [xx,yy] = logspiral(tt,varargin)
% logarithmic spiral stimulus

% the following line will be parsed by the ROI editor to present a list of
% options. should be in the format: parameter1 (comment), parameter2 (comment)
%% parameter options: revolutions (Number of revolutions), direction (Can be 'inward' or 'outward')

%% parse inputs
inputs = scanimage.mroi.util.parseInputs(varargin);

if ~isfield(inputs,'revolutions') || isempty(inputs.revolutions)
    inputs.revolutions = 5;
end

if ~isfield(inputs,'direction') || isempty(inputs.direction)
    inputs.direction = 'outward';
end

if ~isfield(inputs,'a') || isempty(inputs.a)
    inputs.a = 0;
end

tt = tt ./ tt(end); %normalize tt
switch inputs.direction
    case 'outward'
        % Nothing to do
        % tt = tt;
    case 'inward'
        tt = fliplr(tt);
    otherwise
        error('Unknown direction: %s',inputs.direction);
end

%% generate output
if inputs.a == 0;
    xx = tt .* sin(inputs.revolutions .* 2*pi .* tt);
    yy = tt .* cos(inputs.revolutions .* 2*pi .* tt);
else
    tt = tt-max(tt);
    xx = exp(inputs.a .* tt) .* sin(inputs.revolutions .* 2*pi .* tt);
    yy = exp(inputs.a .* tt) .* cos(inputs.revolutions .* 2*pi .* tt);
end

Note how optional arguments are parsed by the ScanImage® class scanimage.mroi.util.parseInputs(varargin) on line 9. If expected arguments are not given, they are given default values (lines 11 - 21). The parameterized equations are defined within the if-else statement in lines 35 - 42.