[finfo, recognized, unrecognized] = getSPTBfilename(fpath, [,'multisession'] [,'multidate'] [,'priority'] [,'recursive'] [,'search_depth'] [,'sort'] [,'validate'] [,'ops'])
GETSPTBFILENAME is a function for obtaining relevant complete file paths and filenames, as well as for filtering out non-SPTB datastructs and gathering useful information about a datastruct. The function assumes that the user has not fiddled with the filename (don't alter filenames manually; use easyImport with the rename_ppt parameter set instead; see easyImport for details).
FINFO = getSPTBfilename(FPATH) returns file information. If FPATH is supplied as empty, or as a directory, the function will operate recursively over all elements of the current or specified directory, returning many files. This can be an efficient way to, for example, get all the files from a participar participant or group of participants. If a relative filepath is supplied but is not in the current directory, the SPTB folders will be searched in the order specified by 'priority' (below) until a file is matched (for this type of search, it is helpful to specify a participant name prefix, e.g., '101/myexpt*'. If FPATH is a path to a specific file, only that file will be processed. If FPATH contains wildcards (whether in the directory path or file name, e.g., '1*/myexpt*'), all matching files and directories will be processed. FINFO = getSPTBfilename(DATASTRUCT) returns file information from a datastruct, rather than a string. The filename provided is generated based on a best guess, given the information in the datastruct. FINFO = getSPTBfilename({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. FINFO = getSPTBfilename({EXPT_NAME, PPT_NAME, SESSION}) as well as FINFO = getSPTBfilename({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. FINFO = getSPTBfilename({GROUP_NAME}) will return the latest version of a groupstruct for the specified group. [FINFO, RECOGNIZED, UNRECOGNIZED] = getSPTBfilename(FPATH) follows the behaviour specified above, but returns a RECOGNIZED cell array of datastructs matched by the FPATH input, as well as an UNRECOGNIZED cell array of datastructs that, based on their filenames, do not appear to be SPTB objects. FINFO = getSPTBfilename(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: 'multisession' String. GETSPTBFILENAME needs to know what to do when it encounters datastructs reflecting multiple sessions from the same experiment (same experiment name, participant name and datatype). By default, it will return all of the matching files that it finds, but sometimes it's necessary to obtain only the first or last file (e.g., when scoring the file with easyScore, having multiple sessions in the returned list might cause the file to be scored twice). For these circumstances, supply "first" or "last" here, or provide an integer scalar to indicate which session should be returned (i.e., 'first' and 1 return the same result). Default: {'all'} 'multidate' String. Sometimes, multiple versions of a file can be found even within a single session (e.g., when the experiment crashed and was restarted). As with the multisesssion parameter, you can specify the multidate parameter to have GETSPTBFILENAME return the first, last, or all datastructs from a particular single session; or specify an integer. Default: {'all'} 'ops' String or cell array of strings. It can sometimes be more convenient to sort files on the basis of which operations have been performed on the file than when it was acquired. Supply operations here to limit search results to those files. Choose among 'scored' and 'coded'. 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. You can select among 'curr' (working directory), 'mod', 'raw', 'group', and 'scored' options. Default: {'curr','mod','raw','group','scored'} 'recursive' Boolean. When set to true, searches found directories recursively. Default: true 'sort' Boolean. Normally, getSPTBfilename just produces a long array of search results. However, it can alternately produces a results sorted according to each field of finfo (e.g, experiment, session, participant, or data type). This option changes the output of finfo to be a table containing files sorted by experiment name, participant, datastruct type and session number. Default: false 'validate' Boolean. Normally, getSPTBfilename will load every file it tries to process to check whether it's a real datastruct. With larger datasets this can be unnecessarily time-consuming. Set validate to true to skip loading of the file and work with the string only. Default: false 'search_depth' Scalar. Used internally to track recursion depth. Default: 0