datastruct = easyCursor(datastruct [,'cursor_start'] [,'cursor_img'] [,'brush_width'] [,'brush_color'] [,'canvas_origin'] [,'canvas_size'] [,'canvas_img'] [,'onset'] [,'draw_func_args'] [,'input_func_args'] [,'trial_summary_func_args'] [,'respmap'] [,'stim'] [,'cond'] [,'cresp'] [,'trial_dur'] [,'nesting'] [,'trial_bin'] [,'rotate']) [] = optional parameters '' = parameter-value pairs
EASYCURSOR is intended as a quick way to gather and organize cursor response data. Each call to the function is a 'trial' in which more data are collected. It builds and logs a structure prepared by initEasyCursor that can easily be 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 parameters are set once using initEasyCursor 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 = easyCursor(S) returns a datastruct using EASYCURSOR default values. S is a test-specific data structure prepared by running initEasyCursor to specify test-related parameters like sample rate, maximum time duration, etc. D = easyCursor(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: '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] '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. Additionally, an image matrix may be supplied. The coordinates of the cursor will reside at the centre of the loaded image. If a default_cursor_img is also provided to initEasyCursor, the one provided here will override it. Default: Simple crosshairs 'brush_width' Positive numeric scalar. When draw_mode is set to true, specifies the width of the brush strokes that are drawn (in pixels). Default: 2 '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) '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 '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 '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. If a canvas_rect was not supplied, 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. If supplied here, canvas_img will override the value of default_canvas_img stored in the datastruct from initEasyCursor. If the image is too big for the "canvas" area, it will be shrunk proportionally. If it is too small, it will be centred within the canvas and scaled up. To avoid these effects, specify the canvas size appropriately. Default: 255 (white) '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 'draw_func_args' Cell array. A cell array of optional arguments that will be passed on to each call of the draw function. 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 input_func_args format of {screen_pointer, canvas_rect, allow_mouse_exit, use_OS_cursor} where the latter two arguments are booleans. Default: {default_parent, canvas_rect, false, false} '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: {} 'respmap' Table. Table mapping response zones to numeric values and labels. Use makeMap to generate this map. If you did not supply a default_respmap to initEasyScale, you will be required to supply one here. Default: empty table '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. 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: {} '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] 'trial_bin' Cell array. Values can be given here as a cell array. These values are then passed on to draw_func, although they remain unchanged during a trial. Values such as coloured rectangular regions for a cursor hover experiment can be specified here. If specified, trial_bin will override default_trial_bin (if it was given in initEasyCursor). Cells 1-3 are reserved for internal use and should be left empty (values supplied to trial_bin(1:3) will be overwritten). Default: {reserved,reserved,reserved [,]} 'rotate' Scalar. When using an internal cursor, mouse input can be rotated by the amount specified in this parameter. This would cause cursor movement that is directed straight up from its origin to instead result in movement that is directed clockwise by the number of degrees specified here. Default: 0
datastruct: a data structure containing the various parameters that were provided to the initEasyCursor initialization function, as well as response data from each call to EASYCURSOR. Fields corresponding to absent optional parameters are set to default values.