datastruct = initEasyType(exp_name, ppt_name, [,'parent'] [,'session'] [,'default_respmap'] [,'default_dim'] [,'margin'] [,'back_colour'] [,'font_type'] [,'font_size'] [,'font_colour'] [,'char_limit'] [,'exit_keys'] [,'default_cresp'] [,'default_resp_type'] [,'case_sensitive'] [,'stimmap'] [,'condmap'] [,'trigger_next'] [,'prompt_dur'] [,'exp_onset'] [,'resp_buffer'] [,'device'] [,'console'] [,'files'] [,'params'] [,'isi'] [,'feedback'] [,'break'] [,'num_trials'] [,'draw_func'] [,'draw_func_args'] [,'summary_func'] [,'summary_func_args'] [,'headless'] [,'trial_summary_func'] [,'live_score'] [,'default_trial_summary_func_args']) [] = optional parameters '' = parameter-value pairs
This is a helper function to initialize the data structure that easyType takes as input. These parameters normally stay the same for a given type of datastruct, so they can be set once here and forgotten. In general, you should only need to call this function once for each type of question in your experiment. The required variable 'exp_name' is a string to identify this particular easyType test, and will be used for file management. The supplied 'exp_name' variable cannot be a directory. 'ppt_name' is a required non-path string and is used to uniquely identify data to a particular person. 'trial_summary_func' an optional function called during easyScore, or after each trial using the 'live_score' parameter, for customized evaluation and scoring of trial responses.
D = initEasyType(exp_name,ppt_name) returns a datastruct filled with
default values and string exp_name as the experiment name and ppt_name
as the participant name.
D = initEasyType(exp_name,ppt_name,param1,val1,param2,val2...) sets
various optional parameters. Parameters are case-insensitive, and each
string parameter must be followed by a value as indicated:
'session' Scalar integer.
This number will be used to identify the session number of
the experiment. Multiple-session experiments can be
analyzed and compared later on.
Default: 1
'parent' Window or screen pointer.
The reference window for which the input box coordinates
will refer to. This is always required, as a parent window
is needed to draw the text box and print updates.
Default: 0
'default_dim' 4-vector of positive numbers: [X1 Y1 X2 Y2].
[X1 Y1] specifies the upper-left boundary of the input text
box, and [X2 Y2] specifies the lower-right boundary. The
boundaries are pixel coordinates with respect to the
supplied window or screen pointer. Y2-Y1 is the height of
the box, and X2-X1 is the width. Both height and width must
be greater than zero. If you do not supply a default_dim
here, you will be required to supply a box to easyType each
time you call it.
Default: entire screen
'margin' Positive numeric scalar.
Specifies the margin in pixels to leave between the text
and the top-left corner of the input text box.
Default: 4
'back_colour' Unsigned integer [R G B] triplet or grayscale scalar.
Specifies the desired colour for the input text box
background. R, G, and B must be unsigned integers in the
range [0, 255]. and denote colour levels of red, green, and
blue respectively, with 0 being none, and 255 being full
saturation. Alternatively, back_colour can be specified as
a single positive integer in the range [0, 255], which
would specify a grayscale intensity with 0 being black, and
255 being white.
Default: 255 (white)
'font_type' String specifying font type.
This is the font that will be used for the input text box.
If a font is selected that doesn't exist, no error is
raised and the font will be set to the default value.
Default: 'Courier New'
'font_size' Scalar positive integer in the range [1, 72].
Specifies the size of the font being input by the user.
Note: If box dimensions are not specified, the supplied
font_size may be too large for the input box.
Default: 14
'font_colour' Unsigned integer [R G B] triplet.
Specifies the desired font colour of text being input into
the input box. R, G, and B must be unsigned integers in the
range [0, 255], and denote colour levels of red, green, and
blue respectively, with 0 being none, and 255 being full
saturation. Alternatively, back_colour can be specified as
a single positive integer in the range [0, 255], which
would specify a grayscale intensity with 0 being black, and
255 being white.
Default: [0 0 0] (black)
'char_limit' Two-element vector of positive integers: [MIN MAX].
Specifies the required range of characters that needs to be
input for the experiment to proceed. MIN and MAX must both
be 0 or greater, and MIN must be equal to or less than MAX.
If the number of input characters violates these
restrictions, a warning message will be displayed in the
input box.
Default: [0 10000]
'exit_keys' Cell array of strings.
Specifies the keys that terminate collection of text by
easyType. Use KbName('KeyNames') to see a list of all
keynames. The command KbName('UnifyKeyNames') is
recommended at the top of your script to ensure maximum
portability between operating systems. Note: an exit key
press doesn't automatically trigger the next trial (unless
trigger_next is set to true), but waits for the duration to
time out. If exit_keys is set to empty, the user is forced
to wait for the duration to time out before the experiment
continues.
Default: {'Return'}
'default_cresp' Cell array of strings or NaN's.
The strings that should be treated as being correct
responses. If there is no one correct answer, omit this
parameter, and all valid responses will be treated as
correct. NaN indicates that a null response is correct. If
there is more than one correct response, specify cresp as a
cell array of strings (with NaN as a valid element as
well).
Default: {}
'default_resp_type' 2-element cell array of strings.
Determines the type of response expected by easyType when
an exit key is pressed. If not provided or set to an empty
string, all types of responses are accepted.
When an exit key is pressed, the response string is stored
in two variables: 'num' which is a numeric value obtained
by using str2double on the response string, and 'text'
which is a character array.
The first cell must be a string that will be evaluated as a
boolean, and can incorporate the 'num' and 'text' variables
mentioned above. The second cell is a string message that
will be displayed to the user if the condition in the first
cell does not evaluate to true. For example, to ensure the
user input is a number greater than 0, the
default_resp_type can be given as,
{'~isnan(num) && num>0', 'must be number greater than 0'};
Default: {}
'default_respmap' Table mapping strings to numeric values and labels.
Defines the semantic and numerical "meaning" of a set of
anticipated input strings. On trials where no
trial-specific respmap is provided, this one will be used
instead. Case insensitive matching is used against strings
in the "input" field and then mapped to the descriptors and
values fields, as appropriate. Although freeform easyType
responses are less likely on average to exactly match
prepared inputs, this respmap is also displayed by
easyCode, and may facilitate manual response scoring. Use
makeMap to generate this map.
Default: []
'case_sensitive' Boolean.
Determines whether or not the string comparisons between
user input and the correct response are case-sensitive.
Default: false
'stimmap' Table mapping stimuli to numeric values.
When calling easyType, you will have the option of
specifying the active stimulus. If you want to better keep
track of which stimulus is which across tests, it can be
helpful to assign a unique id to each stimulus that you can
use to sort stimuli later. If you provide this map here, it
will be used as a lookup table on each easyType call in
which you specify a stimulus. Use makeMap to generate this
map. If left blank here, easyType will dynamically generate
its own id map as stimuli are fed to it that can then be
fed in here (pass in datastruct.stimmap).
Default: empty table
'condmap' Table mapping conditions to numeric values.
When calling easyType, you will have the option of
specifying a condition number for each trial. If you want
to better keep track of which condition is which and
assemble onsets across tests with a consistent matrix size,
it can be helpful to assign a unique id to each condition
here. If you provide this map (use makeMap to generate it),
conditions will be translated into the corresponding string
(e.g., cond=2 and condmap={'on','off'} would be reported as
'off') and onset maps will be generated in a consistent
way. If left empty or omitted here, the condition string
will be reported as a string version of the number (e.g.,
'2'). For experiments with multiple condition factors,
supply this argument as a cell array of condmaps.
Default: empty table
'trigger_next' Boolean.
Determines if easyType code execution will carry on as soon
as a response is detected. If set to false, easyType will
wait after a response until the specified duration has
elapsed, which could be useful in situations where it is
desirable to hold stimulus presentation rate constant (e.g.
in an fMRI study); whereas setting it to true might make
sense in a self-paced scenario.
Default: true
'prompt_dur' Numeric scalar or empty array.
The maximum period, specified in seconds, for which you
would like to present participants with the initial prompt
screen while waiting for a response. Must be greater than
0. It can be provided as an empty array if you would like
to provide prompt_dur dynamically during an experiment.
Default: []
'exp_onset' Numeric scalar.
By default, onset times will be measured relative to the
time at which this initialization function is called (i.e.,
the difference in GetSecs between later trials and
initialization). Onsets can alternately be measured
relative to a different initialization time, e.g., one
passed by a trigger_next function used to synchronize the
experiment with some other data source (e.g., an fMRI
scanner).
Default: output of GetSecs command
'resp_buffer' Numeric scalar.
Time period for which response information will be written
to disk as temporary files. This can be used to backup
responses for long trials in case there is a program crash.
If supplied as NaN, no periodic response logging is
performed.
Default: NaN
'device' Numeric integer, string, or cell array of strings.
The keyboard device that will be monitored for responses.
Can be specified explicitly as a numeric deviceID, or
supplied as a full or partial device name, full serial
number, or full locationID, in which cases getInputDevice
will try to guess the correct deviceID.
Default: arbitrary keyboard selected from available devices
'console' Boolean.
Determines whether or not performance information (e.g.,
stim, resp, rt, cresp, acc) is printed to the screen each
time a question is asked.
Default: false
'files' Boolean.
Determines if the datastruct is saved to a .mat and .txt
file each time easyType is called in order to make sure the
latest data is available in case of a crash.
Default: true
'params' Struct.
Structure object as supplied by easyLaunch. These can be
retained in the datastruct either for use by secondary
functions or just for logging purposes.
Default: []
'isi' Boolean.
Set this to any positive value to have easyKeys produce a
centred fixation cross for that duration in seconds. To
have the ISI period take place before a trial begins, set
the value to negative (e.g., -1 would produce a one-second
isi before a trial). This can help with timing, as internal
SPTB preparation for the trial is able to take place during
the ISI period. To have the ISI take place after the trial
is complete, set the value to positive (e.g., 1 would
produce a one-second isi after a trial). Requires a parent
window to be set.
Default: 0
'feedback' Scalar or 4-cell array.
By default, no feedback is presented to the user. However,
if a parent is provided, you can provide a positive value
here to have feedback presented for that many seconds. The
default feedback values are "Correct!" in green,
"Incorrect" in red, or "Too slow" in red. However,
alternate strings or image filepaths can be used instead.
To do so, provide a four-cell array, with feedback duration
in the first position, followed by feedback for a correct
answer, then for an incorrect answer, then for a null
response (applied only when a null response is incorrect).
Default: 0
'break' Scalar or 2-cell array.
By default, the experiment is the same on every loop.
However, if a parent is provided, you can provided a
positive value n here to provide a 10-second break after
every nth call to easyType. If you prefer to have the break
right before the n+1 call to easyType, e.g., -2 in a
four-trial experiment such that the experiment will provide
a break after trial 2 but not right before it concludes
after trial 4), you can set n to a negative value. When set
to zero, no breaks are provided. For more control over
breaks, provide a 2-cell array instead, with break
frequency in the first position, followed in the second
position by either a numeric break duration (e.g., 5) or
key to press to continue (e.g., 'space').
Default: 0
'num_trials' Positive integer.
Set this to a positive integer representing the total
number of trials expected to supply your drawFunc with
information about experiment progress (which you may
optionally draw). Also prevents the goofy but usually
harmless situation where you display a break right after
the final trial of your experiment. This will NOT prevent
you from running more trials than the number you have
allotted, although warnings will be printed to the console.
Therefore, this parameter can also help catch bugs in your
experimental logic.
Default: nan
'summary_func' String or function handle.
For later scoring, you may specifiy a function to
supplement the automatic scoring outputs of easyScore to
analyze subsets of datastruct.trials. You may wish to
summarize user responses in more sophisticated ways than
e.g., just taking the mean across each trial subset. This
function is called many times during analysis: once for an
overall score, but also once for each condition, level of
nesting, etc., so it is a good way to quickly implement
your statistic for interpretation at many levels of your
output. If you don't have this now, that's okay -- you can
add it later or override your choice with easyScore.
Default: []
'draw_func' String or function handle.
By default, easyType just draws a textbox on the screen that
you yourself prepare. However, if you wish easyType to draw
its own presentation of your stimuli, you can set this
parameter to a string describing a position in which the
question should be drawn relative to the textbox ('above',
'below', 'left', 'right', 'behind'). Alternatively, you can
specify your own function handle for drawing (it may be
helpful to inspect drawSPTBtextbox as a template). If set
to an empty string, no drawing is done. Requires parent to
be specified. Optionally, params can be specified (without
it, a default drawing style is used).
Default: ''
'default_draw_func_args' Cell array.
A cell array of optional arguments that will be passed
on to each call of the draw function. The default function,
drawSPTBtextbox, can be supplied as follows:
draw_func_args are expected in a three-cell array. easyType
will supplement any drawing you have done before calling
easyType by drawing (in order of cell position) a label,
stimulus, position, and the provided initialization text
(disappears when typing begins). The label may be any text.
Stimulus may be any text, image, audio file, or video; by
default, it is the stimulus provided to easyType. Start
text can be any string and by default designates the exit
key, if any.
Default: {[], stimulus, ...
'Begin typing, and press
datastruct: a data structure containing the various parameters that were provided to this initialization function. Fields corresponding to absent optional parameters are set to default values. datastruct contains a field 'box' which contains parameters specific to the input box such as font size, background colour, etc.