MATLAB Python

initEasyCursor

Syntax

datastruct = initEasyCursor(exp_name, ppt_name [,'parent'] [,'session'] [,'default_cursor_start'] [,'device_poll_rate'] [,'sample_rate'] [,'record_rate'] [,'require_click'] [,'draw_mode'] [,'draw_func'] [,'trial_summary_func'] [,'default_draw_func_args'] [,'default_input_func_args'] [,'default_trial_summary_func_args'] [,'live_score'] [,'default_canvas_origin'] [,'default_canvas_size'] [,'default_canvas_img'] [,'default_cursor_img'] [,'default_brush_width'] [,'default_brush_color'] [,'exit_keys'] [,'default_respmap'] [,'default_cresp'] [,'stimmap'] [,'condmap'] [,'trigger_next'] [,'prompt_dur'] [,'exp_onset'] [,'resp_buffer'] [,'cursor_device'] [,'exit_device'] [,'default_trial_bin'] [,'console'] [,'files'] [,'params'] [,'isi'] [,'feedback'] [,'break'] [,'num_trials']) [] = optional parameters '' = parameter-value pairs

Description

This is a helper function to initialize the data structure that easyCursor 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 variables 'exp_name' and 'ppt_name' are strings to identify this particular easyCursor test, and will be used for file management. '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.

Usage

D = initEasyCursor(exp_name,ppt_name) returns a datastruct filled with default values and strings exp_name and ppt_name as the experiment and participant names. D = initEasyCursor(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 pointer. The reference window in which the easyCursor visual components will reside. This pointer is needed in order to allow for incremental drawing, and to set the initial cursor position. Default: 0 'default_cursor_start' 4-D vector of positive numbers: [X Y L R] The X and Y pixel coordinates where the cursor will begin relative to the upper-left corner experiment window. L and R specify the states of the left and right mouse buttons respectively, with a value of 0 denoting a disengaged button, and any other number denoting an engaged button. Default: [0 0 0 0] 'device_poll_rate' Positive numeric scalar. Determines the number of times per second the cursor can be polled for input by the system. Specified in Hertz. Default: 60 'sample_rate' Numeric scalar in range (0, 1000] Determines the number of times per second the cursor state is sampled and recorded. Higher sample rates will result in higher resolution pointer trajectories. If the input is a specific device and the sample_rate exceeds the device_poll_rate, resampling is performed on collected data to interpolate where necessary. Default: device_poll_rate * 1.25 'record_rate' Numeric scalar. Specifies the final sample rate which is stored in the final output datastruct. This value can be used to reduce demands on program memory. Default: device_poll_rate 'require_click' Boolean. If set to true, easyCursor will require a cursor click in a valid region in order to terminate the trial. If specified when 'draw_mode' is set to true, it will be silently ignored. Default: false 'draw_mode' Boolean. If set to true, easyCursor will operate in drawing mode, in which case left cursor click draws ink to the canvas, and right cursor click erases the ink. Draw mode runs until either the trial duration times out, or a specified exit_key is pressed. Default: false 'draw_func' String or function handle. A function that governs the drawing of the window display as the trial progresses. If not specified, this will default to drawFunc_cursor which facilitates a freehand drawing mode. If draw_mode is set to true, drawFunc_cursor will be used as the draw_func and any supplied argument will be silently ignored. Default: [] 'trial_summary_func' String or function handle. Score func is a function that can be used to generate statistics measures desired by the user. The output of these statistics is stored in the resp_auto field of the trials table within the datastruct, and will be included in the basket variables analyzed by a call to easyScore. 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. Default: {} 'default_input_func_args' Cell array. A cell array of optional arguments that will be passed on to each call of the input function. The input function is hard-coded to be inputFunc_mouse which expects optional default_input_func_args format of {screen_pointer, canvas_rect, allow_mouse_exit, use_OS_cursor} where the latter two arguments are booleans. Default: {parent, canvas_rect, false, false} 'default_trial_summary_func_args' Cell array. A cell array of optional arguments that will be passed on to each call of the scoring function. Default: {} 'live_score' Boolean If set to true, trial_summary_func will be applied after each trial rather than in easyScore. Unless live feedback is required, it is recommended to leave this parameter at "false", as unforseen problems with your trial_summary_func may interrupt the experiment. Default: false 'default_canvas_origin' Numeric array: [X1 Y1 X2 Y2] When draw_mode is set to true, [X1 Y1] specifies the upper-left boundary of the drawing canvas. [X2 Y2] can also be supplied to specify the lower-right boundary (as in standard rect format). The boundaries are pixel coordinates with respect to the supplied window or screen pointer. Y2-Y1 is the height of the canvas, and X2-X1 is the width. Both height and width must be greater than zero. When a complete rect is specified here, canvas_size is ignored. Default: entire screen 'default_canvas_size' Numeric array: [width height] When draw_mode is set to true and canvas_origin has been set using a 2-element vector, [width height] specifies the width and height of the canvas. Both must be greater than zero. These values are ignored when canvas_origin was supplied as a rect. Default: entire screen 'default_canvas_img' Colour vector [R G B a], grayscale scalar, image matrix, or string. When draw_mode is set to true, this specifies the desired colour for the canvas which is being drawn on. R, G, B, and a must be unsigned integers in the range [0, 255]. R, G, and B denote colour levels of red, green, blue respectively, with 0 being none, and 255 being full saturation. The 'a' value is an optional alpha value and determines opacity (255 for opaque, 0 for transparent). Can be specified as a single positive integer in the range [0, 255] to specify a grayscale intensity with 0 being black, and 255 being white. Alternatively, an image matrix can be supplied to be drawn on top of. The default canvas will be the current window display instead of a white screen. If specified as a string, the code will try to load the string as an image matrix to be used as the canvas. Default: 255 (white) 'default_brush_width' Positive numeric scalar. When draw_mode is set to true, specifies the width of the brush strokes. Default: 2 'default_brush_color' Integer triplet [R G B] or grayscale scalar. When draw_mode is set to true, this specifies the desired colour for the brush strokes on the canvas. 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. Can be specified as a single positive integer in the range [0, 255], to specify a grayscale intensity with 0 being black, and 255 being white. Default: 0 (black) 'default_cursor_img' String, or image matrix. The relative or absolute string path to the image that will be used by easyCursor to represent the cursor object. The coordinates of the cursor will reside at the centre of the loaded image. Can also be given as an image matrix. Default: OS cursor 'exit_keys' Cell array of strings. Specifies the keys that can be pressed during draw mode to terminate the trial. 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. Default: {} 'default_respmap' Table. Table mapping response zones to numeric values and labels. Use makeMap to generate this map. If you do not supply a default_respmap here, you will be required to supply a respmap to easyCursor each time you call it. Default: empty table 'default_cresp' Cell array of strings. The string descriptors that specify zones of the response space that will be treated as correct responses. The string entries must be a subset of the descriptors in respmap. 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. Default: {} 'stimmap' Table mapping stimuli to numeric values. When calling easyCursor, 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 easyCursor call in which you specify a stimulus. Use makeMap to generate this map. If left blank here, easyCursor 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 easyCursor, 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 easyCursor code execution will carry on as soon as a response is detected. If set to false, easyCursor 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 emtpy 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 'exit_device' Numeric integer, string, or cell array of strings The device that will be monitored for infor about whether to terminate a trial. 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 'cursor_device' Numeric integer, string, or cell array of strings The device that will be monitored by input_func for cursor movements. The device that will be monitoted on whether to terminate a trial. 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 case getInputDevice will try to guess the correct deviceID. Default: arbitrary mouse selected from available devices 'default_trial_bin' Cell array. Values can be given here as a cell array. These values are then passed on to input_func and draw_func, although they remain unchanged during a trial. Values such as coloured rectangular regions for a cursor hovering experiment can be specified here. If draw_mode is set to true, the default trial_bin will be automatically generated from the default_canvas_img and default_cursor_img parameters, but this can be overridden by supplying a default_trial_bin here. Default: [] '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 easyCursor is called in order to make sure the latest data is available in case of a crach. 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). This may be preferred when you wish to draw the trial screen yourself, rather than having it be replaced by a fixation cross and drawn by SPTB. 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 easyCursor. If you prefer to have the break right before the n+1 call to easyCursor, 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

Output

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.