Home > demos > demo_extract_pairs_multiwork.m

demo_extract_pairs_multiwork

PURPOSE ^

% Overview

SYNOPSIS ^

function demo_extract_pairs_multiwork(option)

DESCRIPTION ^

% Overview
 Finds moments from two cevents that match a specified temporal relation
 
 Will loop through all events in cev1 and find those events in cev2 that
 match the temporal relation given in the threshold parameter. These
 matches (or pairs) are output in a resulting CSV file.
 author: sbf@umail.iu.edu
% Required Arguments
 subexpIDs
         -- integer array, list of subjects or experiments
 cev1
         -- string, cevent variable name
 cev2
         -- string, cevent variable name
 timing_relation
         -- string of characters that indicate the temporal relations
 
         on1 and off1 correspond to cev1 onset and offset, respectively.
         on2 and off2 correspond to cev2 onset and offset, respectively.
 
         'more(A,B,T)' means A comes before B with a gap more than T seconds.
         'less(A,B,T)' means A comes before B with a gap less than T seconds.
         A and B are to be replaced with any combination of on1, off1, on2,
         and off2. T is optional, and if it is not provided, will not
         consider the gap between A and B.
 
         e.g.
         timing_relation = 'more(on1, on2, 4)' means on1 must come before on2 in time,
         with a gap of more than 4 seconds.
         timing_relation = 'less(off2, on1, 2)' means off2 must come before on1 in time, with a
         gap of less than 2 seconds.
 
         Note, you can chain multiple timing relations together using '&' or '|'. This
         means AND and OR, respectively. Use parentheses to indicate
         more complex timings.

         e.g.  
         timing_relation = 'more(on1, off1, 4) & less(on1, on2, 2)' means events in
         cev1 must be greater than 4 seconds long, and must start at most
         2 seconds before the events in cev2
 
 mapping
         -- Nx2 array that indicates which categories are to be matched
            together.
 savefilename
         -- string indicating where to save the CSV file. The folder
            must exist.
% Optional Arguments
 args.pairtype
         -- single-dimension array of integers whose length matches the
            length of 'mapping'. Allows user to tag each row in 'mapping' to a type.
 
 The following arguments control many to many mapping
 Consider the following many to many mapping from cev1 and cev2
 10, 15
 11, 15
 11, 16
 11, 17
 To force 1 to 1 mapping, set either first_n_cev1 or last_n_cev1 to 1
 args.first_n_cev1
         -- integer indicating to only output first N pairings of cev 1
 args.first_n_cev2
         -- integer indicating to only output first N pairings of cev 2
 args.last_n_cev1
         -- integer indicating to only output last N pairings of cev 1
 args.last_n_cev2
         -- integer indicating to only output last N pairings of cev 2

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SOURCE CODE ^

0001 function demo_extract_pairs_multiwork(option)
0002 %% Overview
0003 % Finds moments from two cevents that match a specified temporal relation
0004 %
0005 % Will loop through all events in cev1 and find those events in cev2 that
0006 % match the temporal relation given in the threshold parameter. These
0007 % matches (or pairs) are output in a resulting CSV file.
0008 % author: sbf@umail.iu.edu
0009 %% Required Arguments
0010 % subexpIDs
0011 %         -- integer array, list of subjects or experiments
0012 % cev1
0013 %         -- string, cevent variable name
0014 % cev2
0015 %         -- string, cevent variable name
0016 % timing_relation
0017 %         -- string of characters that indicate the temporal relations
0018 %
0019 %         on1 and off1 correspond to cev1 onset and offset, respectively.
0020 %         on2 and off2 correspond to cev2 onset and offset, respectively.
0021 %
0022 %         'more(A,B,T)' means A comes before B with a gap more than T seconds.
0023 %         'less(A,B,T)' means A comes before B with a gap less than T seconds.
0024 %         A and B are to be replaced with any combination of on1, off1, on2,
0025 %         and off2. T is optional, and if it is not provided, will not
0026 %         consider the gap between A and B.
0027 %
0028 %         e.g.
0029 %         timing_relation = 'more(on1, on2, 4)' means on1 must come before on2 in time,
0030 %         with a gap of more than 4 seconds.
0031 %         timing_relation = 'less(off2, on1, 2)' means off2 must come before on1 in time, with a
0032 %         gap of less than 2 seconds.
0033 %
0034 %         Note, you can chain multiple timing relations together using '&' or '|'. This
0035 %         means AND and OR, respectively. Use parentheses to indicate
0036 %         more complex timings.
0037 %
0038 %         e.g.
0039 %         timing_relation = 'more(on1, off1, 4) & less(on1, on2, 2)' means events in
0040 %         cev1 must be greater than 4 seconds long, and must start at most
0041 %         2 seconds before the events in cev2
0042 %
0043 % mapping
0044 %         -- Nx2 array that indicates which categories are to be matched
0045 %            together.
0046 % savefilename
0047 %         -- string indicating where to save the CSV file. The folder
0048 %            must exist.
0049 %% Optional Arguments
0050 % args.pairtype
0051 %         -- single-dimension array of integers whose length matches the
0052 %            length of 'mapping'. Allows user to tag each row in 'mapping' to a type.
0053 %
0054 % The following arguments control many to many mapping
0055 % Consider the following many to many mapping from cev1 and cev2
0056 % 10, 15
0057 % 11, 15
0058 % 11, 16
0059 % 11, 17
0060 % To force 1 to 1 mapping, set either first_n_cev1 or last_n_cev1 to 1
0061 % args.first_n_cev1
0062 %         -- integer indicating to only output first N pairings of cev 1
0063 % args.first_n_cev2
0064 %         -- integer indicating to only output first N pairings of cev 2
0065 % args.last_n_cev1
0066 %         -- integer indicating to only output last N pairings of cev 1
0067 % args.last_n_cev2
0068 %         -- integer indicating to only output last N pairings of cev 2
0069 
0070 % Output is a CSV with each row respresenting a pair. The pairs can be
0071 % many-to-many.
0072 %
0073 % Two additional CSV files (_cev1wo.csv and _cev2wo.csv) are generated indicating which cevents from cev1
0074 % and cev2 were not paired.
0075 %
0076 % Only in-trial data will be considered, and cevents from one trial cannot
0077 % be paired with cevents from another trial (even if the timing holds true).
0078 %%
0079 
0080 switch option
0081     case 1
0082         %% pair inhand and eye from child, with one temporal constraint
0083         
0084         cev1 = 'cevent_inhand_child'; % [on1 off1]
0085         cev2 = 'cevent_eye_roi_child'; % [on2 off2]
0086         subexpIDs = [7106 7107 7108]; % can be a list of subjects or a list of experiments
0087         timing_relation = 'less(on1, on2, 2)'; % this means on1 must be less than on2,
0088         % and the their difference is LESS than 2 seconds.
0089         mapping = [
0090             1 1; % pair categories 1 and 1
0091             2 2; % pair categories 2 and 2
0092             3 3; % pair categories 3 and 3
0093             1 4; % pair categories 1 and 4
0094             2 4; % ...
0095             3 4;]; 
0096         args.pairtype = [1 1 1 2 2 2]; % one number per row in mapping. In this
0097         % case, when the categories match, it is type 1. If it matches with
0098         % face, it is type 2.
0099         savefilename = '/scratch/multimaster/demo_results/extract_pairs_multiwork/case1/example1.csv';
0100         extract_pairs_multiwork(subexpIDs, cev1, cev2, timing_relation, mapping, savefilename, args)
0101         
0102     case 2
0103         %% use more than one temporal constraint
0104         
0105         cev1 = 'cevent_inhand_child'; % [on1 off1]
0106         cev2 = 'cevent_eye_roi_child'; % [on2 off2]
0107         subexpIDs = [7106 7107 7108]; % can be a list of subjects or a list of experiments
0108         timing_relation = 'less(on1, on2, 2) & less(off2, off1, 3)';
0109         % Timing_relations can be strung together using '&' or '|'. This example has two temporal
0110         % constraints -- on1 must be less than on2, and the their difference is
0111         % less than 2 seconds. Also, off1 must be greater than off2, and their
0112         % difference must be less than 3 seconds. Note, the threshold
0113         % amount, 2 and 3, are upper bounds always. Meaning, the difference
0114         % of the preceeding timestamps must be LESS than the threshold
0115         % amount. '&' means only events that have both temporal conditions
0116         % will be accepted.
0117         mapping = [
0118             1 1; % pair categories 1 and 1
0119             2 2; % pair categories 2 and 2
0120             3 3; % pair categories 3 and 3
0121             1 4; % pair categories 1 and 4
0122             2 4; % ...
0123             3 4;]; 
0124         args.pairtype = [1 1 1 2 2 2]; % one number per row in mapping. In this
0125         % case, when the categories match, it is type 1. If it matches with
0126         % face, it is type 2.
0127         savefilename = '/scratch/multimaster/demo_results/extract_pairs_multiwork/case2/example2.csv';
0128         extract_pairs_multiwork(subexpIDs, cev1, cev2, timing_relation, mapping, savefilename, args)
0129         
0130         
0131     case 3
0132         %% threshold amount is optional
0133         
0134         cev1 = 'cevent_inhand_child'; % [on1 off1]
0135         cev2 = 'cevent_eye_roi_child'; % [on2 off2]
0136         subexpIDs = [7106 7107 7108]; % can be a list of subjects or a list of experiments
0137         timing_relation = 'less(on1, on2, 2) & less(off2,off1)';
0138         % on1 must be less than on2, with a difference of 2. Also, off1 must be
0139         % greater than off2, by any margin. There is no upper bound.
0140         mapping = [
0141             1 1; % pair categories 1 and 1
0142             2 2; % pair categories 2 and 2
0143             3 3; % pair categories 3 and 3
0144             1 4; % pair categories 1 and 4
0145             2 4; % ...
0146             3 4;]; 
0147         args.pairtype = [1 1 1 2 2 2]; % one number per row in mapping. In this
0148         % case, when the categories match, it is type 1. If it matches with
0149         % face, it is type 2.
0150         savefilename = '/scratch/multimaster/demo_results/extract_pairs_multiwork/case3/example3.csv';
0151         extract_pairs_multiwork(subexpIDs, cev1, cev2, timing_relation, mapping, savefilename, args)
0152         
0153         
0154     case 4
0155         %% control for many to many mapping
0156         
0157         % e.g. event # 10 in cev1 is paired with event # 12, 13, 14 in cev2
0158         % the index columns in the output file would look like
0159         % 10, 12
0160         % 10, 13
0161         % 10, 14
0162         % use first_n_cev1 to only grab the first pairing, leaving the
0163         % others out
0164         
0165         cev1 = 'cevent_inhand_child'; % [on1 off1]
0166         cev2 = 'cevent_eye_roi_child'; % [on2 off2]
0167         subexpIDs = [7106 7107 7108]; % can be a list of subjects or a list of experiments
0168         timing_relation = 'less(on1, on2, 5)';
0169         % on1 must be less than on2, with a difference of 5.
0170         mapping = [
0171             1 1; % pair categories 1 and 1
0172             2 2; % pair categories 2 and 2
0173             3 3; % pair categories 3 and 3
0174             1 4; % pair categories 1 and 4
0175             2 4; % ...
0176             3 4;]; 
0177         args.pairtype = [1 1 1 2 2 2]; % one number per row in mapping. In this
0178         % case, when the categories match, it is type 1. If it matches with
0179         % face, it is type 2.
0180         
0181         % in case of duplicate events, filter everything except the first n
0182         % events in cev1
0183         args.first_n_cev1 = 1; % only grab the first cev1 that is paired
0184         args.first_n_cev2 = 1; % only grab the first cev2 that is paired
0185         
0186         % can also specify args.last_n_cev1 and last_n_cev2 to grab the
0187         % last events that are paired. These can be combined with
0188         % args.first_n_cev1 and args.first_n_cev2 to grab the first and the
0189         % last events in the pairings
0190         
0191         savefilename = '/scratch/multimaster/demo_results/extract_pairs_multiwork/case4/example4.csv';
0192         extract_pairs_multiwork(subexpIDs, cev1, cev2, timing_relation, mapping, savefilename, args)
0193         
0194 end
0195 end

Generated on Tue 23-May-2017 20:00:55 by m2html © 2005