[datastruct, type, fn] = getDatastruct(datastruct [,'type_assertion'] [,'trials'] [,'recovery_handling'] [,'priority'] [,'session_handling'] [,'strict']) DESCRIPTION GETDATASTRUCT is a convenience function for loading and/or validating a datastruct or groupstruct (datastruct will be used as shorthand for both in this help file). Extensive checking of the loaded object is performed to ensure it is formatted as appropriate for its object type. USAGE D = getDatastruct(datastruct) returns a datastruct supplied either as an already-loaded datastruct, or a partial, rexexp, or complete string path to a datastruct (an error will be thrown if multiple files match the input pattern). D = getDatastruct({expt_name, ppt_name, session, type}) attempts to load the datastruct from a file in the SPTB folder based on the standard SPTB data directory location and standard file formatting. By default, if a file in the SPTB Modified folder is available for a given combination of participant and experiment, this is given preference; otherwise, a raw file is used. Where multiple versions of a file in the Modified folder exist (e.g., exp_..._coded and exp_..._coded_rekeyed), the one with the most operations applied is selected. Where multiple processing paths have been taken (e.g., exp_.._coded_rekeyed and exp_.._rekeyed_coded), an error will be thrown and the first method / explicit filepath selection will be required as above. D = getDatastruct({expt_name, ppt_name, session}) as well as D = getDatastruct({expt_name, ppt_name}) both follow the same behaviour as above using fewer parameters. However, if multiple sessions or data types are present, an error is thrown. D = getDatastruct({group_name}) will return the latest version of a groupstruct for the specified group. [D,T] = getDatastruct(...) will behave as above, but also returns a string T designating the type of the datastruct (e.g,. 'easyKeys'). [D,T, FN] = getDatastruct(...) will behave as above, but also returns a string FN designating the path to the loaded datastruct. D = getDatastruct(datastruct,param1,val1,param2,val2...) follows 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: 'type_assertion' String or cell array of strings. If a particular type of datastruct is expected, that can be specified here and an error raised if a different type was obtained instead. Options are: easyKeys, easyType, easyVoice, easyCursor, easyScale, datastruct, groupstruct, and any_valid. Default: [] 'trials' String, cell array of strings, scalar, or numeric array. If a specific trial or set of trials is identified using this variable, then GETDATASTRUCT 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: [] 'ops' String or cell array of strings. Constrain loading of datastructs to those on which certain operations have been performed (such as coding or scoring). See getSPTBfilename for details. Default: {} '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. Default: {'Modified','Raw'} 'strict' Boolean. By default, GETDATASTRUCT will throw an error when an expected parameter is missing. By setting this parameter to false, you can use GETDATASTRUCT to tolerate these cases and continue processing; missing fields will be populated with empty values. Use this option at your own peril, as missing parameters may cause issues with downstream functions. Default: true 'recovery_handling' String. In the case where multiple versions of a file are found within a single session (e.g., when the experiment crashed and was restarted), this parameter determines how GETDATASTRUCT acquires data from the files. NOTE: if an optional 'recovery_handling' field exists in the datastruct, the discovered value will be used if this parameter was not supplied. The following values are valid: 'first' - trial data from all discovered files is consolidated into one trial table, with preference going to earlier responses in the case of duplicates. This is the default behaviour. 'concatenate' - data from all files is combined without without discarding any trials. All row names (stimuli) are suffixed by the date string of the file in order to be uniquely identified. 'last' - only the most recently created file is used, and the rest are ignored. Default: 'first' 'session_handling' 2-cell array. If there are multiple sessions for an experiment that are meant to be merged into one datastruct, this parameter can be used to achieve that. The first cell of the array must be a string or function handle specifying what function will be applied to the numeric data being merged. The second cell can either be a numeric array of session numbers, or a 2-cell string array of filename references to be merged. NOTE: if an optional 'session_handling' field exists in the datastruct, the discovered value will be used if this parameter was not specified. The following values are valid: - 'none': no merging operation will be performed, and the 'recovery_handling' setting will be used. - 'diff': values in the second supplied target session are subtracted from the first. [any other string/function handle] - the function will attempt to evaluate the string as a function on the two sets of values (e.g., 'mean', 'sum'). Default: {'none', []}