groupStruct = groupScore(group_name, template, include [,'tasks'] [,'tasks_excluded'] [,'normalize'] [,'custom_basket'] [,'drop_nans'] [,'extended'] [,'getDatastruct_params'] [,'easyScore_params']) [] = optional parameters '' = parameter-pair values
GROUPSCORE does some helpful summary and data organization on a given list of participants. Using the template participant, experiment data is collected and consolidated into experiment-specific fields of groupStruct for later analysis. Using easyScore, some useful statistics (e.g., condition means, response rate, ITI) are calculated on the resulting groupstruct and reported using the corresponding experiment-specific fields.
The required variable 'group_name' is a string identifying the group being analyzed by GROUPSCORE, and cannot be a path. The required 'template' variable is a path containing data for a template participant whose easy* files will be used to determine which experiments should be analyzed groupStruct. 'template' must be given as a participant name that is visible to showMeTheData. The 'include' variable is used to limit which participants are included in the GROUPSCORE analysis. It can be an explicit list of participant names which are to be included, or a regular expression. For example, the following inputs would be acceptable: include = 'AL_*'; include = {'AL_021','AL_022','AL_023'}; include = {'AL_01*','AL_02*','AL_03[123]'}; When 'include' is left empty, all participant folders will be searched for files matching those of the template participant. G = groupScore(group_name,template_ppt,include) returns a groupstruct named group_name with the datastructures in the template_ppt's data folder consolidated with matching structures found in all participants of template's parent directory. G = groupScore(group_name,template_ppt,include,param1,val1,param2, val2,...) also sets various optional parameters. Parameters are case-insensitive, and each string parameter must be followed by a value as indicated: 'tasks' String or cell array of strings. Normally, all tasks that have been completed by the template participant are processed. However, an explicit list of tasks to be analyzed can be supplied using this parameter. Each available task from the template participant will be searched for each string supplied here. Use the string, or partial string, you supplied as the exp_name when creating your datastruct, or look at the filename prefix of files in your participant folder as seen before the participant name (_ppt). It is also possible to perform regexp matching. However, note that including any tasks that are unmatched will cause an error to be thrown. Default: {} 'tasks_excluded' String or cell array of strings. Like the tasks parameter, this can be used to help specify which tasks should be included. This can be helpful for e.g., excluding tasks with a certain prefix. By default, practice tasks are excluded. Default: {'practice'} 'normalize' Boolean. When performing analyses, it can sometimes be desirable to remove between-subject sources of variance prior to assembling participant responses. Setting this parameter to "true" will normalize (z-score) all numeric trial, trial_scored and item values by participant before they are merged into the groupstruct. Default: false 'drop_nans' Boolean. When a participant has not completed a condition or test that was completed by the template participant, there is typically a NaN recorded in place of the missing data that, when included in a group average, would yield a group result of NaN. At the risk of possibly masking missing data issues, set this variable to true to exclude these NaN cases when performing group summaries. Note: you must set this parameter separately within easyScore_params (below) to apply this behaviour to single trials of individual participants. Default: true 'custom_basket' Cell array of strings or function handles. By default, key variables in your datastruct, including those in resp_man and resp_auto, are analyzed using a "basket" of descriptive statistics functions, including the functions 'mean', 'median', 'sum', 'std', 'min', and 'max'. You can replace these, or add your own custom statistics, by naming them here. Note: these statistics are applied only at the group level. To apply to individual participant measures, set the corresponding parameter in easyScore_params (below). Default: {'mean', 'median', 'sum', 'std', 'min', 'max'} 'extended' Boolean. Set this flag to true in order to add skew, kurtosis, and normality to your "basket" of descriptive statistics. Make sure you have swtest by Ben Saida on your matlab path (see dependencies below). Note: these statistics are applied only at the group level. To apply to individual participant measures, set the corresponding parameter in easyScore_params (below). Default: false 'easyScore_params' Cell array. To directly control the behaviour of easyScore (called by groupScore during scoring), supply any desired parameter-value pairs here as a cell array. See 'help easyScore' for more information on available parameters. Note that the defaults for some variables differ from easyScore defaults. For example, 'max_depth' (0), 'rescore' (false), and 'keep_resp_input_vec' (false). Also, the 'no_merge' option of recovery_handling is unavailable. Note there are many useful parameters you should take the time to investigate, such as 'resp_man_handling', 'max_interaction', 'summary_func', 'drop_nans', and others. To use different controls for different tasks, call groupScore multiple times and limit your task scope using 'tasks' (above). Default: {} 'getDatastruct_params' Cell array. As with easyScore params, the paramers use to control getDatastruct loading can be directly controlled. See 'help getDatastruct' for more information on available parameters. Without input here, the default behaviour of getDatastruct is followed. Note that the 'no_merge' option of 'recovery_handling' is unavailable in GROUPSCORE. Default: {}; 'getSPTBfilenames_params' Cell array. As with easyScore params, the paramers use to control file searching can be directly controlled. See 'help getSTPBfilenames' for more information on available parameters. Without input here, the first matching date and session will be sampled. Default: {'multisession','first','multidate','first'}