datastruct = easyImport(filename, 'exp_name', 'ppt_name', 'header_row', 'timestamp_col' 'nesting_cols', 'data_cols' [,'delimiter'] [,'start_row'] [,'row_format'] [,'session'] [,'stim_col'] [,'stimmap'] [,'cond_cols'] [,'condmap'] [,'respmap'] [,'acc_col'] [,'info_cols'] [,'trial_summary_func'] [,'trial_summary_func_args'] [,'record_rate'] [,'exp_onset'] [,'exp_offset'] [,'headless']); [] = optional parameters '' = parameter-value pairs


EASYIMPORT allows you to import data output files that were generated using a different experiment package into an easyScale datastruct, so that you can manage and anaylze your data with the SuperPsychToolbox suite of tools. This allows you to take advantage of the data organization and analysis functions available through e.g., easyScore, groupScore and dataBind; and to standardize your data format for future access. The function does not require a particular delimeter type, however, it does require that information is organized into S x F format in a text file, where S is samples over rows (where a single trial may contain many potential samples) and M is data fields over columns. Just as with any other datastruct, processing should be performed on one participant task and session at a time.


D = easyImport(filename,param1,val1,param2,val2...) returns an easyScale datastruct based on file described by filename. The datastruct is also written to disk based on existing preferences and convention (see easyScale output), Several pair-value parameters are required: 'exp_name' String. Name of the experiment being performed (used in filename). 'ppt_name' String. Name of the participant being analyzed (used in filename). 'header_row' Boolean or scalar. Indicates whether the file contains column headers that should be used to define the columns. If set to true, the header row will be obtained from row 1; if set to a scalar, the header row will be obtained from the specified row. The titles in the header row can be used to index the "cols" fields below with respective column names. 'timestamp_col' Scalar or string. The column number (counting up from 1) that contains timestamps for the onset of each sample. Can be provided as a string if a header is available. 'nesting_cols' Numeric array or cell array of strings. The column numbers or names that contain information about the position of this trial in the experiment (e.g., block number or trial number). Any number of columns can be provided, but they should be organized in order of the largest to smallest organizing unit (e.g., [block_col subblock_col trial_col]). Note that more than one row can belong to a particular trial, but trials that are out of order (occuring earlier in the nesting order than subsequent trials) will cause an error. If you don't have this information, you must still explicitly leave this parameter empty - each sample will be treated as a trial. 'data_cols' Numeric array or cell array of strings. The column numbers or names that contain data recorded during the trial. This can be as few as one, or as many as are desired. Data will be compiled into the resp_input_vec field and the final value of the trial will be used in resp (this can be altered using the trial_summary_func parameter below). When using an easyScale input type, data_cols may contain any number of variables to be included in the resp_input_vec. When using the easyKeys input type, data_cols must contain three column names describing a column for resp, rt, and cresp. If any of these is missing, an empty entry may be substituted for their name in the three-cell array. In addition to the above required arguments, a number of optional parameters can be specified as parameter-value pairs: 'delimiter' String. The token used to separate cells of data. For example, in a CSV file, commas separate each cell. In some other file types, tab or space is used. Default: ',' 'start_row' Scalar. This value is used to indicate on what line the data samples to be read begin (counting up from line 1). It will normally begin right after the header row, or line 1 if no header is present. Default: Header row + 1 'row_format' String. EASYIMPORT will try its best to parse your columns into string- and double-containing ones, but if this isn't working quite right, or you want to use more efficient data precisions, you can specify a format string here. See "help textscan" for information about the required structure of this string. Default: [] 'session' Scalar. Session number (used to integrate or compare across experimental sessions). Default: 1 'stim_col' Scalar or string. Column number or name containing either stimulus strings or integer ID's to be recorded as the stimulus associated with each trial (see also "stim" and "stimID" in easyScale). If omitted or repeated, a generic row number will be described in its place. An error is thrown is different stimulus labels appear among samples of the same trial. Default: [] 'stimmap' Table mapping stimulus names to stimulus ID's. See easyScale for stimmap description. Will be used to generate stimulus ID's or stimulus strings from whichver of those two was NOT provided in stim_col. Default: [] 'cond_cols' Numeric array or cell array of strings. Column numbers or names containing integers or strings describing the condition associated with that trial. If omitted, a null condition will be described in place. See also "cond" parameter in easyScale. Default: [] 'condmap' Table mapping condition names to condition ID's. If provided, will translate condition values or names into specific corresponding names or values. See also "condmap" parameter in easyScale. Default: [] 'respmap' Table mapping data outcomes to response categories. If provided, will translate bin data into categorical values or strings. See also "respmap" parameter in easyScale. Default: [] 'acc_col' Scalar or string. Number or name of column containing either binary values (corresponding to accuracy) or cresp values (corresponding to options in a provided respmap). See also "cresp" parameter in easyScale. Default: [] 'info_cols' Numeric array or cell array of strings. Column numbers or names containing meta-data about the trial. See also "info" parameter in easyScale. Default: [] 'trial_summary_func' String or function handle. A trial_summary_func can be applied to the data at the time they are imported. See "trial_summary_func" parameter of initEasyScale. Default: [] 'trial_summary_func_args' Cell array. A cell array of optional arguments to be supplied to trial_summary_func, if specified. Default: [] 'record_rate' Scalar. The rate in Hz at which samples should be retained in the easyScale datastruct. Available samples will be up- or down-sampled to this rate. See also "record_rate" parameter in easyScale. Default: [] 'exp_onset' Scalar. Timestamp associated with the start time of the experiment. Normally, this is inferred based on the first onset timetamp, but an alternate time can be specified here. This may be important if, e.g., you intend to align data from another data source that involved a synchronization event that was timestamped on both systems' clocks. Default: first sample onset 'exp_offset' Scalar. Timestamp associated with the end time of the experiment. Normally, this is associated with the final offset of the experiment plus the mean trial duration, but an exact time can be specified here. This may be useful e.g., for generating exact vectors for regression with fMRI data. Default: final sample onset plus mean trial duration


datastruct: a data structure containing the imported data. See also output for easyScale.