Home > demos > demo_extract_multi_measures.m

demo_extract_multi_measures

PURPOSE ^

% Summary

SYNOPSIS ^

function demo_extract_multi_measures(option)

DESCRIPTION ^

% Summary
 This function outputs a .csv file containing basic statistics at a subject level or at the
 event level.
% Required Arguments
 var_list
       -- cell array, list of variable named found in the derived folders
          of multiwork subjects
 subexpIDs
       -- integer array, list of subjects or experiments
 filename
       -- full path or relative path of where to save the .csv file
% Optional Arguments
 The measures you specify control for the granularity of the output
 args.cevent_measures
       -- cell array of strings, any of the following
               'individual_prop_by_cat'      (default)
               'individual_freq_by_cat'      (default)
               'individual_mean_dur_by_cat'  (default)
               'individual_median_dur_by_cat'
               'individual_number_by_cat'

 args.cont_measures
       -- cell array of strings, any of the following
               'individual_mean'             (default)
               'individual_median'           (default)
               'individual_std'
               'individual_min'
               'individual_max'

 
 Note: can remove the suffix '_by_cat' from the end of the measures to show get one aggregated statistic across all categories
       -- e.g. 'individual_prop'

 args.persubject
       -- If 1, statistics are aggregated across events and the output
          contains one row per subject
 
 args.cevent_name
       -- string, cevent variable name -- Defines the windows of time to extract data from.
          Meaning, for args.cevent_name = 'cevent_speech_utterance', each
          variable in var_list will be cut to each utterance event.
       -- In the output file, each row will contain statistics for one
          event. Therefore, if subject 3201 has 30 utterance events, there will
          be 30 rows for subject 3201 in the output file, with statistics during each utterance.
       -- By default, this is set to 'cevent_trials'
 
 args.cevent_values
       -- array of integers, indicating the categories to include from the cevent in args.cevent_name
       -- e.g., for args.cevent_name = 'cevent_eye_roi_child', then
          args.cevent_values = [1 2 3 4];
       -- must be specified if args.cevent_name is specified
 
 args.label_matrix
       -- NxM array, where N is number of unique categories in the variables indicated in var_list, and
          M is the number of unique categories in args.cevent_name
       -- This option will concatenate data based on target / others mapping. That is, the output will put all target values into column 1, and others into column 2.
       -- e.g. if var_list = {'cevent_eye_roi_child'} and args.cevent_name = 'cevent_speech_naming_local-id'            
       -- args.label_matrix = [1 2 2 3;   % naming object 1
                               2 1 2 3;   % naming object 2
                               2 2 1 3;]  % naming object 3
                    ROI object 1 2 3 4
       -- The values in the matrix refer to the columns of the output .csv results.
       -- array(1,1) = 1, meaning when naming is object 1, and eye ROI is 1, then put the resulting statistic into column 1
       -- array(2,1) = 2, meaning when naming is object 2, and eye ROI is 1, then put the resulting statistic into column 2
       -- array(3,4) = 3, meaning when naming is object 3, and eye ROI is 4 (face), then put the resulting statistic into column 3
       -- So in this example, whenever naming matches the ROI object, we put that statistic into the first column of the output .csv
 
 args.label_names
       -- cell array of strings, user-defined labels of the output columns after re-mapping based on args.label_matrix
       -- e.g. {'target', 'others', 'face'}, for values 1, 2, and 3, respectively
 
 args.whence
       -- string, 'start', 'end', or 'startend'
       -- this parameter, when combined with args.interval, allows you to shift the args.cevent_name window times by a certain amount. The shift can be respect to the start, end, or full event.
 args.interval
       -- array of 2 numbers, [t1 t2], where t1 and t2 refer to the offset to apply in each args.cevent_name window times.
       -- e.g., [-5 1] and whence = 'start', then we take the onset of each cevent and add -5 seconds to get new onset. Likewise, we add 1 second to onset to get new offset.
       -- therefore, if the original event was [45 55], then
          if args.whence = 'start', then new event is [40 46]
          if args.whence = 'end', then new event is [50 56]
          if args.whence = 'startend', then new event is [40 56]

 args.within_ranges
       -- 1 or 0
       -- if 0, then we get the complement of args.cevent_name, or event_NOT.
       -- Note, there is not category, so it effectively turns it into an event based analysis. Therefore, not compatible with label_matrix

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function demo_extract_multi_measures(option)
0002 %% Summary
0003 % This function outputs a .csv file containing basic statistics at a subject level or at the
0004 % event level.
0005 %% Required Arguments
0006 % var_list
0007 %       -- cell array, list of variable named found in the derived folders
0008 %          of multiwork subjects
0009 % subexpIDs
0010 %       -- integer array, list of subjects or experiments
0011 % filename
0012 %       -- full path or relative path of where to save the .csv file
0013 %% Optional Arguments
0014 % The measures you specify control for the granularity of the output
0015 % args.cevent_measures
0016 %       -- cell array of strings, any of the following
0017 %               'individual_prop_by_cat'      (default)
0018 %               'individual_freq_by_cat'      (default)
0019 %               'individual_mean_dur_by_cat'  (default)
0020 %               'individual_median_dur_by_cat'
0021 %               'individual_number_by_cat'
0022 %
0023 % args.cont_measures
0024 %       -- cell array of strings, any of the following
0025 %               'individual_mean'             (default)
0026 %               'individual_median'           (default)
0027 %               'individual_std'
0028 %               'individual_min'
0029 %               'individual_max'
0030 %
0031 %
0032 % Note: can remove the suffix '_by_cat' from the end of the measures to show get one aggregated statistic across all categories
0033 %       -- e.g. 'individual_prop'
0034 %
0035 % args.persubject
0036 %       -- If 1, statistics are aggregated across events and the output
0037 %          contains one row per subject
0038 %
0039 % args.cevent_name
0040 %       -- string, cevent variable name -- Defines the windows of time to extract data from.
0041 %          Meaning, for args.cevent_name = 'cevent_speech_utterance', each
0042 %          variable in var_list will be cut to each utterance event.
0043 %       -- In the output file, each row will contain statistics for one
0044 %          event. Therefore, if subject 3201 has 30 utterance events, there will
0045 %          be 30 rows for subject 3201 in the output file, with statistics during each utterance.
0046 %       -- By default, this is set to 'cevent_trials'
0047 %
0048 % args.cevent_values
0049 %       -- array of integers, indicating the categories to include from the cevent in args.cevent_name
0050 %       -- e.g., for args.cevent_name = 'cevent_eye_roi_child', then
0051 %          args.cevent_values = [1 2 3 4];
0052 %       -- must be specified if args.cevent_name is specified
0053 %
0054 % args.label_matrix
0055 %       -- NxM array, where N is number of unique categories in the variables indicated in var_list, and
0056 %          M is the number of unique categories in args.cevent_name
0057 %       -- This option will concatenate data based on target / others mapping. That is, the output will put all target values into column 1, and others into column 2.
0058 %       -- e.g. if var_list = {'cevent_eye_roi_child'} and args.cevent_name = 'cevent_speech_naming_local-id'
0059 %       -- args.label_matrix = [1 2 2 3;   % naming object 1
0060 %                               2 1 2 3;   % naming object 2
0061 %                               2 2 1 3;]  % naming object 3
0062 %                    ROI object 1 2 3 4
0063 %       -- The values in the matrix refer to the columns of the output .csv results.
0064 %       -- array(1,1) = 1, meaning when naming is object 1, and eye ROI is 1, then put the resulting statistic into column 1
0065 %       -- array(2,1) = 2, meaning when naming is object 2, and eye ROI is 1, then put the resulting statistic into column 2
0066 %       -- array(3,4) = 3, meaning when naming is object 3, and eye ROI is 4 (face), then put the resulting statistic into column 3
0067 %       -- So in this example, whenever naming matches the ROI object, we put that statistic into the first column of the output .csv
0068 %
0069 % args.label_names
0070 %       -- cell array of strings, user-defined labels of the output columns after re-mapping based on args.label_matrix
0071 %       -- e.g. {'target', 'others', 'face'}, for values 1, 2, and 3, respectively
0072 %
0073 % args.whence
0074 %       -- string, 'start', 'end', or 'startend'
0075 %       -- this parameter, when combined with args.interval, allows you to shift the args.cevent_name window times by a certain amount. The shift can be respect to the start, end, or full event.
0076 % args.interval
0077 %       -- array of 2 numbers, [t1 t2], where t1 and t2 refer to the offset to apply in each args.cevent_name window times.
0078 %       -- e.g., [-5 1] and whence = 'start', then we take the onset of each cevent and add -5 seconds to get new onset. Likewise, we add 1 second to onset to get new offset.
0079 %       -- therefore, if the original event was [45 55], then
0080 %          if args.whence = 'start', then new event is [40 46]
0081 %          if args.whence = 'end', then new event is [50 56]
0082 %          if args.whence = 'startend', then new event is [40 56]
0083 %
0084 % args.within_ranges
0085 %       -- 1 or 0
0086 %       -- if 0, then we get the complement of args.cevent_name, or event_NOT.
0087 %       -- Note, there is not category, so it effectively turns it into an event based analysis. Therefore, not compatible with label_matrix
0088 
0089 switch option
0090     
0091     case 1
0092         %% basic usage -- each row will be one full trial
0093         
0094         % 'obj#' means the function will grab 'cont_vision_obj1_child',
0095         % 'cont_vision_obj2_child', and 'cont_vision_obj3_child'
0096         var_list = {'cevent_inhand_child', 'cevent_eye_roi_child', 'cont_vision_size_obj#_child'};
0097         subexpIDs = [32]; % this can also be a list of experiments
0098         filename = '/scratch/multimaster/demo_results/extract_multi_measures/example1.csv';
0099         args = [];
0100         extract_multi_measures(var_list, subexpIDs, filename, args);
0101         
0102     case 2
0103         %% same as above, with with args.persubject = 1 -- each row will be all trials concatenated together. args.persubject = 1 will work with any of examples in this demo
0104         
0105         var_list = {'cevent_inhand_child', 'cevent_eye_roi_child', 'cont_vision_size_obj#_child'};
0106         subexpIDs = [32]; % this can also be a list of experiments
0107         filename = '/scratch/multimaster/demo_results/extract_multi_measures/example2.csv';
0108         args.persubject = 1;
0109         extract_multi_measures(var_list, subexpIDs, filename, args);
0110         
0111     case 3
0112         %% get data at specific window by specifying args.cevent_name, args.cevent_values, args.label_matrix, and args.label_names -- each row will be one naming instance
0113         
0114         var_list = {'cevent_inhand_child', 'cevent_eye_roi_child', 'cont_vision_size_obj#_child'};
0115         subexpIDs = [32]; % this can also be a list of experiments
0116         filename = '/scratch/multimaster/demo_results/extract_multi_measures/example3.csv';
0117         args.cevent_name = 'cevent_speech_naming_local-id'; % these are the windows of time, or instances, from which data will be extracted and measured
0118         args.cevent_values = 1:3; % which categories in cevent_name you wish to use
0119         %% label_matrix explanation
0120         % -this is a 3 x 3 matrix, mapping the categories in the var_list
0121         % variables to those categories in the cevent_name variable.
0122         
0123         % -the numbers in the matrix indicate which groups we wish to put
0124         % data into. In the example below, there are groups 1 and 2, 1
0125         % being 'target' and 2 being 'other'
0126         
0127         % -columns correpond var_list categories, and rows correspond to
0128         % cevent_name categories.
0129         
0130         % -in the matrix below, the first row is 1 2 2. Since it's the
0131         % first row, this is when cevent_speech_naming_local-id is equal to
0132         % 1, in other words, when the parent names obj1. This means if the
0133         % child is touching obj1 while the obj1 is being name, this data
0134         % will be placed into category 1. When the child is touching obj2
0135         % while obj1 is being named, this data will be placed into category
0136         % 2. Likewise, when the child is touching obj3 while the obj1 is
0137         % begin named, the data will be placed into category 2.
0138         
0139         % -this effectively puts "target" data into category 1 and "other"
0140         % data into category 2
0141         args.label_matrix = [
0142             1 2 2; % naming obj1
0143             2 1 2; % naming obj2
0144             2 2 1]; %naming obj3
0145         
0146         % -we can now name those two categories as 'target' and 'other' -if
0147         % there are 2 distinct numbers in label_matrix, there should be 2
0148         % distinct names in label_names
0149         args.label_names = {'target'};%, 'other'};
0150         
0151         args.cevent_measures = 'individual_prop';
0152         args.cont_measures = 'individual_mean';
0153         % one can specify the measures they wish for each data type
0154         % individual_prop_by_cat will output data for each object
0155         % individual_prop will will average the data across objects
0156         
0157         extract_multi_measures(var_list, subexpIDs, filename, args);
0158         
0159         
0160     case 4
0161         %% if a subject is missing either the cevent_name, or the variable in var_list, it will fill the csv with NaN values
0162         
0163         var_list = {'cevent_inhand_child', 'cevent_eye_roi_does_not_exist', 'cont_vision_size_obj#_child'};
0164         subexpIDs = [32]; % this can also be a list of experiments
0165         filename = '/scratch/multimaster/demo_results/extract_multi_measures/example4.csv';
0166         args = [];
0167         extract_multi_measures(var_list, subexpIDs, filename, args);
0168         
0169     case 5
0170         %% if you want to include 'face' looks. Note that for variables that doesn't have a face category, it won't product results for 'face';
0171         
0172         % For example, cevent_inhand_child does not have a category 4,
0173         % therefore the function will process this variable as if the
0174         % label_matrix were 3x3, [1 2 2; 2 1 2; 2 2 1]. Also, the number of
0175         % names in label_names does not necessarily need to match the
0176         % number of distinct values in label_matrix. For example, if the
0177         % label_name = {'target' 'other'}, the function will simply not
0178         % process the face group (3), and it will not show up on the csv.
0179         % To put it this way, the function will only use what is given or
0180         % what is possible, and whatever is extra will be ignored.
0181         
0182         var_list = {'cevent_inhand_child', 'cevent_eye_roi_child', 'cont_vision_size_obj#_child', 'cevent_eye_joint-attend_both'};
0183         subexpIDs = [32]; % this can also be a list of experiments
0184         filename = '/scratch/multimaster/demo_results/extract_multi_measures/example5.csv';
0185         args.cevent_name = 'cevent_speech_naming_local-id';
0186         args.cevent_values = 1:3;
0187         args.label_matrix = [
0188             1 2 2 3;
0189             2 1 2 3;
0190             2 2 1 3];
0191         args.label_names = {'target', 'other', 'face'};
0192         extract_multi_measures(var_list, subexpIDs, filename, args);
0193         
0194     case 6
0195         %% use custom ranges based on 2 or 3 columns in a csv file
0196         
0197         csvdata = get_csv_form('/scratch/multimaster/demo_results/extract_pairs_multiwork/case1/example1.csv', [2 6]);
0198         subexpIDs = csvdata.sub_list;
0199         args.event_ranges = csvdata.ranges; % of if cevent, args.cevent_ranges
0200         var_list = {'cevent_inhand_child', 'cevent_eye_roi_child', 'cont_vision_size_obj#_child', 'cevent_eye_joint-attend_both'};
0201         filename = '/scratch/multimaster/demo_results/extract_multi_measures/example6.csv';
0202         extract_multi_measures(var_list, subexpIDs, filename, args);
0203         
0204     case 7
0205         %% use the within_ranges parameter. Specifying args.within_ranges = 0 will use in-between cevents as the base time windows. This may be useful for calculating baseline measures.
0206         
0207         var_list = {'cevent_inhand_child', 'cevent_eye_roi_child', 'cont_vision_size_obj#_child', 'cevent_eye_joint-attend_both'};
0208         subexpIDs = [32]; % this can also be a list of experiments
0209         filename = '/scratch/multimaster/demo_results/extract_multi_measures/example7.csv';
0210         args.cevent_name = 'cevent_speech_naming_local-id';
0211         args.cevent_values = 1:3;
0212         args.within_ranges = 0; % 1 is the default behavior, 0 is between ranges. Will get all non-naming moments.
0213         extract_multi_measures(var_list, subexpIDs, filename, args);
0214         
0215         
0216     case 8
0217         %% specify interval and whence parameters to shift your base cevent by a certain amount, and extract data during these shifted time windows. E.g. measure ROI 5 seconds before each inhand.
0218         
0219         var_list = {'cevent_eye_roi_child', 'cevent_eye_roi_parent'};
0220         subexpIDs = [32]; % this can also be a list of experiments
0221         filename = '/scratch/multimaster/demo_results/extract_multi_measures/example8.csv';
0222         args.whence = 'start'; % the point of reference, which is either the 'start' of the cevent (onset), or the 'end' of the cevent (offset)
0223         args.interval = [-5 0]; % the shift relative to the point of reference indicated in whence.
0224         % [-5 0] means 5 seconds before each event, up to the onset of that
0225         % event.
0226         % [-5 -1] means 5 seconds before each event, up to 1 second before
0227         % that event.
0228         % [-10 2] means 10 seconds before each event, up to 2 seconds AFTER
0229         % the start of the event.
0230         
0231         args.cevent_name = 'cevent_inhand_child';
0232         args.cevent_values = 1:3;
0233         extract_multi_measures(var_list, subexpIDs, filename, args);
0234         
0235     case 9
0236         %% to concatenate across
0237         % default cevent measures are proportion, frequency, and mean duration
0238         % default cont measures are mean and median
0239         % specify specific measures for cevent and cont based measures
0240         
0241         var_list = {'cevent_eye_roi_child', 'cont_vision_size_obj#_child'};
0242         subexpIDs = [32]; % this can also be a list of experiments
0243         filename = '/scratch/multimaster/demo_results/extract_multi_measures/example9.csv';
0244         args.cevent_measures = {'individual_prop'};
0245         args.cont_measures = {'individual_mean'};
0246         extract_multi_measures(var_list, subexpIDs, filename, args);
0247 end
0248 end

Generated on Wed 24-May-2017 00:00:56 by m2html © 2005