datastruct = easyType(datastruct [,'dim'] [,'onset'] [,'stim'] [,'cond'] [,'cresp'] [,'respmap'] [,'resp_type'] [,'trial_dur'] [,'nesting'] [,'draw_func_args'] [,'trial_summary_func_args'] [,'info'] [,'valid_keys'] [,'shadow_text'] [,'init_text']) [] = optional parameters '' = parameter-value pairs
EASYTYPE is intended as a quick way to gather and organize keypress from response data. Each call to the function is a 'trial' in which more data are collected. It builds and logs a structure prepared by initEasyType that can be easily saved and later analyzed in matlab, and which contains much of the important information you would normally hope to collect upon prompting for a response. It also attempts to reduce the burden of gathering a response by assuming the format of your test question will remain the same across instances: most paramaters are set once using initEasyType and can then be forgotten. The function saves all of its information after each response and is logged (to both a matlab and text file) in case disaster strikes in your matlab session. It can also optionally report helpful output to the console so you can see how your participant is doing.
D = easyType(S) returns a datastruct using EASYTYPE default values. S
is a test-specific data structure prepared by running initEasyType to
specify test-related parameters like valid keys, maximum time duration,
etc.
D = easyType(datastruct,param1,val1,param2,val2...) sets various
optional parameters. Parameters are case-insensitive, and each string
parameter must be followed by a value as indicated:
'dim' Four-element 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 did not provide a default box
dim with initEasyType, you will be required to supply one
here.
Default: entire screen
'onset' Numeric Scalar.
Start time of the trial. It is better to use the time
returned by, e.g., your draw command than the onset of this
function for more accurate measurement. However, if you
leave this field empty, the duration will begin from the
time this function is launched.
Default: output of GetSecs command
'stim' String.
A string describing the stimulus presented in this trial.
Specify here to store the information in your datastruct
and enhance console and text-file data-logging. If omitted
or repeated, a generated string containing repeat count
will be used in its place. stim is used as a row name for
the trial table.
Default: '---'
'cond' Scalar positive integer, NaN, string, or string cell array.
Specifies the condition to which the current trial belongs.
If omitted, left empty, or set to NaN, condition -1 will be
recorded. It can be specified either by a positive integer,
NaN, or by string name. If a condmap was specified in
initEasyType, a corresponding condition string will be
reported. When there are multiple condition factors, can be
supplied as a numeric array or cell array of strings where
each entry corresponds to a different condition factor; in
this case, there must be an equal number of condmap entries
supplied to initEasyType, and each entry of cond must be
the same type. As a shortcut with multiple condition
factors, cond can be supplied as a single string
(conditions delimited by underscores) which will be
compared to row names of the master condmap to determine
which conditions to assign for each factor. If no condition
in a condmap matches the string, the condition will be
appended to the condmap.
Default: -1
'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 (unless you specified a default_cresp with
initEasyType). 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: {}
'shadow_text' String.
If specified, this string will appear in grey italics in
the text box until a valid key is pressed, at which point
it will disappear and be replaced by standard text
reflecting user input as per normal.
Default: ''
'init_text' String.
If specified, this string will appear in the text box at
the beginning of the trial. The text will be "typed out"
very quickly instead of appearing right away - this is
unfortunately the only way to make it editable. User input
will be ignored during this rapid typing. The init text
will be treated as prior user input, i.e., any valid typed
input by the user will be appended to the string. The
string can also be edited and deleted as per normal user
input. Overrides the shadow_text parameter.
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: {}
'valid_keys' String.
A string of keys that, when supplied, restricts which keys
will draw text to the text window. Supply the shortcut
'num' or 'text' to limit responses to numeric or text keys.
Default: all keys
'trial_dur' Numeric positive scalar.
The maximum period, specified in seconds, for which you
would like to present participants with the initial
promptscreen while waiting for a response. Must be a
duration greater than 0. If you did not provide a default
prompt_dur during initialization, you will be required to
enter one here.
Default: []
'nesting' Numeric vector of positive integers.
Used to specify the nested structure of trials in an
experiment. Hierarchy is represented in descending order
from left to right, e.g., block 2, subblock 1, trial 4
would be represented as [2 1 4]. This information will be
retained in the datastruct trials table, and is also used
to create depth-specific summaries in easyScore. The
supplied vector can be of any length, but the nesting
vector must be of consistent length across all trials of an
experiment. If the nesting structure has more than one
layer (i.e. more than one element in the nesting vector),
this parameter must be explicitly supplied for each trial
in the experiment. If a single-element nesting vector is
supplied to the first trial, this parameter does not need
to be supplied with each call, and will be instead
incremented by one automatically from the previous trial
nesting value.
Default: [trial]
'info' Any data type.
Populate this field with any kind of meta-data about the
trial. It will be associated with that trial and remain
available for later reference in the datastruct, including
by trial_summary_funcs.
Default: {}
'respmap' Table mapping strings to numeric values and labels.
Defines the semantic and numerical "meaning" of a set of
anticipated input strings. 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: empty table
'draw_func_args' Cell array.
A cell array of optional arguments that control the
optional draw_func. 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 the initEasyType initialization function, as well as response data from each call to EASYTYPE. Fields corresponding to absent optional parameters are set to default values.