MATLAB Python

easyScore

Syntax

datastruct = easyScore(datastruct [,'bin_length'] [,'rescore'] [,'summary_func'] [,'trial_summary_func'] [,'keep_resp_input_vecs'] [,'drop_nans'] [,'custom_basket'] [,'extended'] [,'strict'] [,'priority'] [,'trials'] [,'max_depth'] [,'resp_man_handling']) [] = list of optional parameter-value pairs '' = parameter-pair values

Description

EASYSCORE performs data summary and data organization after you have finished logging responses. In particular, it generates some useful statistics (e.g., condition means, experiment duration, ITI) that are retained in a "ppt_results" field of the returned datastruct. If a bin_length is specified, regressor vectors will be calculated as well. Files produced by EASYSCORE are stored in the computer's SPTB "Scored" folder location (by default, in ~/Documents/Participant Data/Scored). Unlike the source files, score files are considered temporary in nature and will be overwritten without warning. Accordingly, it is not advised to modify score file. Instead, work with unscored datastructs files and save updated versions to the "Modified" directory. Requires third-party function swtest.m by Ben Saieda (http://bit.ly/1zTMxbg).

Usage

D = easyScore(datastruct) returns a datastruct with all the information contained in the original datastruct but containing additional useful statistics. datastruct may be supplied either as a loaded datastruct or a partial, regexp, or complete path to a datastruct (an error will be thrown if multiple files match the input pattern). The scored datastruct will be both returned to the user and written to disk in the STPB "Scored" folder. D = easyScore({expt_name, ppt_name}) follows the same behaviour, but attempts to load the datastruct from a file in the SPTB folder. If multiple sessions are present, an error will be thrown unless the "session" parameter is used. If a file in the "Modified" folder is available for a given combination of participant and experiment, this is given preference; otherwise, a raw file is used. This preference may be altered using the force_target parameter (see below). D = easyScore(datastruct,param1,val1,param2,val2...) and D = easyScore({expt_name,ppt_name},param1,val1,param2,val2...) follow the behaviour specified above, while setting various optional parameters. Parameters are case-insensitive, and each string parameter name must be followed by a value as indicated: 'bin_length' Numeric scalar or empty array. If you are running your experiment in conjunction with some other modality (e.g., fMRI) in which the sampling rate is not continuous, it can be helpful to specify which "bin" corresponds to trial onset ("tr" in fMRI parlance). By specifiying bin_length here, you can identify the corresponding bin number (important: indexes from 1). bin_length should be specified in seconds. If bin_length is specified, fields which are normally presented in seconds will be translated to bin units (e.g., onset, rt, dur). Default: [] 'rescore' Boolean. If set to false, EASYSCORE will search for the result of a previous run of EASYSCORE that was saved to disk in the "Scored" folder. If one is found, the result from the file will be returned instead of running calculations again. Default: true 'summary_func' String or function handle. You may specifiy a function to supplement the automatic scoring outputs of easyScore to analyze subsets of datastruct.trials. You may wish to summarize user responses in more sophisticated ways than e.g., just taking the mean across each trial subset. This function is called many times during analysis: once for an overall score, but also once for each condition, depth of nesting, etc., so it is a good way to quickly implement your statistic for interpretation at many depths of your output. You usually will have set summary_func when calling initEasy* during data collection, but you may wish to override this setting, or you may have changed your mind about the summary_func you want to use for analysis. In either case, you may specify the summary_func here to override the summary_func set in the datastruct. Default: [] 'summary_func_args' Cell array. Whereas datastruct.trials is supplied as the first parameter to summary_func, the contents of this parameter are supplied second. As with the summary_func parameter, this overrides any arguments that were previously set for the datastruct with initEasy*. Default: {} 'trial_summary_func' String or function handle. Similar to summary_func, trial_summary_func operates on each row of your trials table independently, summarizing that trial's performance for later automatic summary. As with summary_func, this overrides any prior setting stored in the datastruct. Default: [] 'trial_summary_func_args' Cell array. Similar to summary_func_args, but supplied to trial_summary_func. Default: {} 'keep_resp_input_vecs' Boolean. If set to true, resp_input_vec data will not be cleared from the datastruct during participant trial consolidation. While this is set to true by default, some resp_input_vecs can easily become enormous, and it may be convenient (or necessary) to drop these vectors during scoring, instead extracting needed information from them before EASYSCORE is run. Default: true 'drop_nans' Boolean. If set to true, null responses will be dropped prior to scoring, which would otherwise result in a summary statistic that was also NaN. This is done by default for all variables in your datastruct, with the exception of accuracy, which is split into "acc" and "acc_respsonly" variables. You can alter this behaviour by toggling this parameter. This may be important e.g., for spotting problems in special or auxilliary variables you have created, or when using custom statistics. 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. 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). Default: false 'strict' Boolean. Normally, datastructs must be formatted in the manner the current version of SPTB uses. This means that EASYSCORE will crash part-way through processing datastructs created with legacy SPTB versions. To avoid crashes, GETDATASTRUCT will normally patch missing parameters with empty values in hopes of letting you continue. But if you want to be extra careful about catching possible errors at the depth of EASYSCORE before they migrate to other parts of the code, you can set this parameter to true. Default: false 'priority' String or cell array of strings. The search priority for finding a given datastruct name can be set here. For instance, if you wanted to search for scored files only, you would specify 'scored'. If you wanted to obtain files from the scored directory, using the raw directory as a fallback, you would specify {'Scored', 'mod'}. Note that directories can be omitted from the priority list to avoid searching in those directories. You can select among 'curr' (working directory), 'mod', 'raw', 'group', and 'scored' options. Default: {'curr','mod','raw','group','scored'} 'resp_man_handling' Two-cell array. Based on using easyCode, the resp_man field can accumulate responses from multiple raters, multiple responses from the same rater, and multiple scales, not all of which are necessarily visited by the same rater. In addition, not all items are necessarily scored at all. All of this ambiguity needs to be sorted out by EASYSCORE for subsequent processing, and EASYSCORE can implement various strategies for doing so. Supply a two-cell array, choosing the first "strategy" string from the following: - latest_multi (default): for each scale and item, obtain the latest rating from each of the designated rater(s). Produce a separate variable for each rater. Items with no entry from a designated rater will receive a NaN in the corresponding scale_rater column. - latest_merge: similar to latest_multi, but take the average of the scores obtained across raters. If any designated rater has not supplied an entry for a given item, a NaN will be recorded. - latest_all: for each scale and item, take the most recent rating that has been supplied by any of the designated rater(s). Items with no entry from all of the designated rater(s) will receive a NaN value. - average_multi: for each scale and item, take the average rating across attempts by the same rater. Multiple designated raters as handled as in latest_multi. - average_merge: similar to average_multi, but take the average of the scores obtained across raters. The second cell in the array should be a string containing the rater's initials, or a cell array of strings containing the list of designated raters per above. If left empty or set to 'all', all raters will be used. The third (optional) cell may contain a string or cell array of strings incorporating one or more of the following options: - ignore_missing: instead of producing a NaN value for a given scale and item when a rater is missing in the 'merge' modes, produce a value using whichever raters are available for that scale and item. - agreement: for each scale and item, instead of an average rating, produce a 1 where all ratings are the same, and a 0 where the ratings are different. NaN will be returned if there is only one available rater for a scale and item, or when using latest_all mode. - variance: for each scale and item, instead of an average rating, report the variance (sigma squared) across ratings. If only two raters are present, a difference score will be used in place of variance. NaN will be returned if there is only one available rater for a scale and item, or when using latest_all mode. - count: for each scale and item, instead of an average rating, report the number of ratings that went into the computation. When used with average_multi or average_merge, an array of values is returned, with each entry reflecting the number of ratings from one rater. Default: {'latest_multi','all',[]} 'trials' String, cell array of strings, scalar, or numeric array. If a specific trial or set of trials is identified using this variable, then EASYSCORE will return a datastruct containing only those trials that are matched. Unmatched trials will be ignored. Trials can be identified by row number or a specific stimulus / row name. Default: [] 'max_depth' Integer scalar. By default, EASYSCORE will generate condition summaries for each depth of nesting (e.g., overall, block, sub-block...) up to three layers deep. However, generating these summaries takes extra time and is not always useful. To save time and/or memory, set this parameter to 0 to generate condition summaries for the top depth of nesting only (i.e., collapsing across all blocks, sub-blocks, etc.), or process extra layers by setting this to a higher value. Note that increasing this value has the side-effect of considerably slowing down computation and increasing demand on memory. Default: 2 'max_interaction' Integer scalar. By default, EASYSCORE will assess all possible condition interactions up to a two-way interaction. For three-way interactions or deeper, you will need to set this parameter to a higher value, corresponding to the level of interaction you wish to entertain. Note that increasing this value generates exponentially more combinations, and will result in slower computation / greater demand on memory. Default: 2