outtab = groupQuery(groupstruct,dataQuery,[handle_missing])
GROUPQUERY helps you quickly find and summarize information within a groupstruct. By providing this function with a groupstruct along with relevant experiment names, measure names and condition, factor or item names, the function will organize participant-wise outputs into a big, labelled table that is suitable for submitting to various types of analysis. GROUPQUERY can also help by handling cases where data are missing for some participants.
The required variable 'groupstruct' is a scored groupstruct, as obtained by running groupScore, or a filepath to that groupstruct. The required variable 'dataQuery' will contain one or more "queries", with each one gathering data from one or more experiments, measures and conditions and/or items. In particular, the variable should be a struct containing the following fields: - tasks: a cell array of strings consisting of the names of all tasks to be indexed using this query. A list of all available tasks can be found by inspecting the fieldnames of groupstruct.ppt_results. e.g., query.exp_names = {'study1_easyKeys','study2_easyKeys'} - measures: a cell array of strings consisting of the variable names of any measures to be extracted. A list of all available measures can be found by inspecting the variable/column names of the relevant table. For example, one could search in: groupstruct.ppt_results.test1_easyKeys.factor1 e.g., query.measures = {'acc_mean','rt_first_median'} - targets: a cell array of strings consisting of the names of all factors, conditions and/or items for which scores should be obtained. If a factor is specified, that entry will be replaced with all conditions (other than 'overall') belonging to that factor. If an entry matches more than one of a factor, condition, and/or item, interpretation will follow the order factor > condition > item. Note that a mix of factors, conditions and items can be supplied. A list of relevant factors can be found by inspecting the fieldsnames of the relevant experiment. For example, one could search in groupstruct.ppt_results.study1_easyKeys. A list of available conditions can be found by searching the row names of a factor, such as groupstruct.ppt_results.study1_easyKeys.factor1. A list of available items can be found by searching the row names of the relevant experiment in groupstruct.group_items. e.g., query.targets = {'factor1','factor1x2_nestinglvl2', ... 'factor1_diff','colorful_cond','grey_cond','item12'} Note that "OR" logic will be followed when evaluating which fields should be returned. For example, a query with two experiments, two measures and two targets would return 2 tasks x 2 measures x 2 targets = eight output columns. Also note that it is often desirable to combine more than one query at a time. For example, you might want to combine values for colorful_cond in the task study1 with values for for age in the task demographics, even though not all participants completed both tasks and you want different values from the tasks..To combine them nicely, simply combine queries using a cell array. For example, comboQuery = {query1, query2}, and submit comboQuery to GROUPQUERY. The optional variable 'handle_missing' is a string that tells GROUPQUERY what to do when a data point is not available in a given query. The string can be set to any of the following options: - 'drop' (default): no data is returned from the participant with a missing data point. - 'nan': a nan value is substituted for the data point. - 'mean', 'median', or 'mode': the mean, median, or mode value obtained by evaluating the distribution across all participants for the variable in question is substituted for the missing data point. OUTTABLE = GROUPQUERY(groupstruct, dataQuery) returns a data table in which participants are listed in rows and variables listed in columns. Appropriate labels are applied to help interpret the table. Hint: To convert the output table into a data matrix, see table2array. To obtain the participant names, inspect outtable.Properties.RowNames. To obtain the variable names, inspect outtable.Properties.VariableNames. To see a nice visualization of your variables with inspectable data points, use easyPlot(outtable). To see a correlation matrix of your variables, use easyPlot(outtable,'corr').