easyLaunch(ppt_ID, session_data [,'start_at'] [,'end_at'] [,'speed'] [,'keyboard'] [,'admin_input'] [,'mouse'] [,'audio_input'] [,'display_dist'] [,'display_height'] [,'display_width'] [,'display_res'] [,'font'] [,'font_size'] [,'wrap_text'] [,'font_color'] [,'bg_color'] [,'wait_dur'] [,'isi_dur'] [,'debug_display'] [, 'fMRI'] [,'finish_func'] [,'finish_func_args'] [,'nosplash']) [] = optional parameters '' = parameter-value pair variables
EASYLAUNCH sets and initializes a large amount of information needed for your experiments, helping to control and organize your studies while also centralizing the information that is used by them for easy changes. It acts as a wrapper, translating information supplied to it into parameters, paths, device tokens, and other information needed by most experiments. It is usually easiest to call EASYLAUNCH from a "launcher" file that you will use to control your overall study. Please see demoEasyLaunch and demoEasyLaunch_advanced for examples of recommended usage. EASYLAUNCH passes arguments 'params', 'tokens', and 'input_args' to each experiment. 'params' contains useful info about the experiment environment (e.g., display resolution). 'tokens' contains temporary pointers (e.g., to the main window, to a random stream, etc.). 'input_args' is a cell array of variable length containing custom variables to be shared with an experiment. Be sure to explore these params and tokens variables as received by your experiment to learn about all the great information that they make available to your studies. Make sure to use these fields whenever possible for better control over your study as a whole (e.g., switching between fMRI and keyboard inputs with the flip of a boolean; and ensuring that the key labels shown to the participant are consistent with this switch). The required parameter 'ppt_ID' is a non-path string and is used to uniquely identify data to a particular participant. 'session_data' is a vector of cells defining experiments to be called and their specific configurations.
Use of easyLaunch is somewhat complex. We suggest you begin by reading the example usage in demoEasyLaunch and demoEasyLaunch_advanced. Detailed usage is below. easyLaunch([], session_data) prints a list of session information to the terminal. session data is a cell array with N sessoion entries, each consisting of a cell array containing 2 or 3 elements: {title, function_to_call [,supplemental_args]} - title: the name you wish to give the session. - function_to_call: the .m file on the matlab path that will be launched. - supplemental args: This should be a cell array with any extra values you want to provide to your function. This can allow to use a single experiment script in various ways (e.g., different practice, study and test sections, or using stimulus sets). Your function will be called in the format: myFunc(params, tokens, supplemental_args) easyLaunch(ppt_ID, session_data) runs through the experiments in session_data with a particular participant ID, starting with the first session. easyLaunch(ppt_ID, session, varargin) sets various optional parameters. Parameters are case-insensitive, and each string parameter must be followed by a value. The optional parameter values are as indicated: 'start_at' Integer or String. A session number or session name for the launcher to start at. To obtain a list of valid inputs (as derived from the supplied session_map), call easyLaunch with an empty ppt_ID or an invalid session name. Default: 1 'end_at' Integer or String. A session number or session name for the launcher to end at. These values can be obtained in the same way as for 'start_at'. Set to 'auto' to end at next empty label or last session. Default: [] 'speed' Integer. An integer respresenting the desired speed of the demos. Setting this parameter to 1 runs the demos at normal speed, where as setting this parameter to a value closer to zero runs the experiment at a multiple of that speed (e.g., 0.001 means that what used to take a second now only takes a millisecond). Default: [] 'keyboard' String. A string describing the keyboard name (eg., 'Apple Keyboard'). Multiple keyboard names may also be specified in a cell array, with preferred devices listed first. If this parameter is specified but the device is not found, then EASYLAUNCH will throw an error. Type "edit demoEasyLaunch_advanced" to learn more about obtaining the names of your devices. Default: [] 'mouse' String. A string describing the mouse name (eg., 'USB Laser Mouse'). Used in the same way as the 'keyboard' parameter. Default: [] 'audio_input' String. A string describing the name of a microphone or other source of audio input (eg., 'Built-in Input'). Used in the same way as the 'keyboard' parameter. Default: [] 'admin_input' String. A string describing the name of a device taking admin control. Used in the same way as the 'keyboard' parameter. If set, then this device will be used in tokens.admin_keys, tokens.admin_input as well as keys.admin. Otherwise, those fields will be set to the value in tokens.user_keys, tokens.user_input and keys.user. By using keys.admin at key points in your experiment (e.g., press key to start), you can alter this argument to change whether the flow of your task is managed (e.g., by an experimenter in a control room; or waiting for an fMRI trigger) vs. full user control. Default: [] 'display_dist' Positive scalar. A positive real number representing the physical distance of the target monitor from user's eyes. If computation of visual degrees per pixel is desired, this parameter must be supplied along with display_height, display_width, and display_res. Default: [] 'display_height' Positive scalar. A positive real number representing the screen height. If omitted, visual degrees per pixel will not be computed. Default: [] 'display_width' Positive scalar. A positive real number representing the physical screen width. If omitted, visual degrees per pixel will not be computed. Default: [] 'display_res' Positive scalar. A positive real number representing the monitor resolution. If omitted, visual degrees per pixel will not be computed. Default: [] 'font' String. A string describing the font name. Default: 'Arial' 'font_size' Integer. An integer representing the size of the font. Default: 28 'wrap_text' Integer. An integer representing the characters per line before strings wrap to the next line. Default: 74 'font_color' Vector of integers. A vector of integers representing RGB font color. Default: [200 200 200] 'bg_color' Vector of integers. A vector of integers representing RGB background color. Default: [50 50 50] 'wait_dur' Positive scalar A positive real number representing how long to wait between sections in seconds. Default: 2.5 'isi_dur' Positive Scalar. A positive real number representing the interstimulus interval (gap between questions) in seconds. Default: 0.25 'debug_display' Boolean. A boolean specifying whether you're in debug mode or not. Unlike the debug_mode set automatically by the speed parameter, which causes the experiment to be drawn in a quarter screen, debug_display runs debugging in full-screen mode. This is probably most useful for when you've got the bulk of your experiment coded and want to test the timing of your display, which is negatively impacted by *not* using full-screen mode, because the desktop compositor remains active. Default: false 'fMRI' String. When set to the name of an fMRI device, strings here reflect the contents of an fMRI context. Instead of keycap names, finger positions are named things like "pinky" or "left pinky" and are remapped accordingly. Currently, the only string recognized is "current_design" reflecting the convention for Current Design devices. However, if you send if your own device standards we will happily add them here. Start messages will also be updated to say things like "waiting for scanner", etc. Default: [] 'finish_func' String or function handle. A function or name of a function to execute after all experimental tasks are complete. It takes arguments in a similar manner to regular functions (i.e., params, tokens, varargin). This can be used e.g., to thank a participant for their time, or to log data at the end of a session. Default: [] 'finish_func_args' Cell array. When using a wrap func, optional arguments can be passed along to it in the third position using this parameter. Default: [] 'nosplash' Boolean or vector. Lead from one function straight into another without interrupting the experiment with the "this is part X of X" display. The display will still show for the first session to help confirm participant ID. Handy for experiments where you do a lot of switching between tasks. Can be provided either as a boolean (applying to all sessions) or a cell array of strings indicating which sections should be excluded from splash strings (based on the session names in session_data). Default: false