Home > demos > demo_extract_pairs_files.m

demo_extract_pairs_files

PURPOSE ^

% Overview

SYNOPSIS ^

function demo_extract_pairs_files(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
 filename1
       -- string, the full path or relative path to a
          .mat or .csv file
       -- data can either be cstream or cevent format
       -- if .mat, data should be saved under sdata.data structure, like
          in multiwork format
       -- for .csv files, one can specify the number of headers and
          columns, see the optional arguments below
 filename2
         -- see filename1
 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.
 args.cevent_trials
       -- string, the full path or relative path to a
          .mat or .csv file
       -- The timing information in this file is used to cut the data into
          trials. Ultimately this ensures that events from one trial
          cannot be paired with events from a second trial, even if the
          temporal relation holds.
 args.files_numheaders
       -- integer array of size 2, indicating how many
          headers are in filename1 and filename2, respectively
       -- e.g. [1 1] for means to skip 1 header file for both
 args.files_columns
       -- cell array of size 2, one cell for each filename, indicating which columns
          to grab from the .csv file
       -- e.g. {[3 4 5], [6 7 8]} for the two filenames
          [3 4 5] is for filename1, [6 7 8] is for filename2
       -- if empty, just grab all columns
 args.cevent_trials_numheaders
       -- integer array of size 2, indicating how many
          headers are in filename1 and filename2, respectively
       -- e.g. [1 1] for means to skip 1 header file for both
 args.cevent_trials_columns
       -- 1x3 integer array indicating which columns
          to grab from the .csv file
       -- if empty, just grab all columns

 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_files(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 % filename1
0011 %       -- string, the full path or relative path to a
0012 %          .mat or .csv file
0013 %       -- data can either be cstream or cevent format
0014 %       -- if .mat, data should be saved under sdata.data structure, like
0015 %          in multiwork format
0016 %       -- for .csv files, one can specify the number of headers and
0017 %          columns, see the optional arguments below
0018 % filename2
0019 %         -- see filename1
0020 % timing_relation
0021 %         -- string of characters that indicate the temporal relations
0022 %
0023 %         on1 and off1 correspond to cev1 onset and offset, respectively.
0024 %         on2 and off2 correspond to cev2 onset and offset, respectively.
0025 %
0026 %         'more(A,B,T)' means A comes before B with a gap more than T seconds.
0027 %         'less(A,B,T)' means A comes before B with a gap less than T seconds.
0028 %         A and B are to be replaced with any combination of on1, off1, on2,
0029 %         and off2. T is optional, and if it is not provided, will not
0030 %         consider the gap between A and B.
0031 %
0032 %         e.g.
0033 %         timing_relation = 'more(on1, on2, 4)' means on1 must come before on2 in time,
0034 %         with a gap of more than 4 seconds.
0035 %         timing_relation = 'less(off2, on1, 2)' means off2 must come before on1 in time, with a
0036 %         gap of less than 2 seconds.
0037 %
0038 %         Note, you can chain multiple timing relations together using '&' or '|'. This
0039 %         means AND and OR, respectively. Use parentheses to indicate
0040 %         more complex timings.
0041 %
0042 %         e.g.
0043 %         timing_relation = 'more(on1, off1, 4) & less(on1, on2, 2)' means events in
0044 %         cev1 must be greater than 4 seconds long, and must start at most
0045 %         2 seconds before the events in cev2
0046 %
0047 % mapping
0048 %         -- Nx2 array that indicates which categories are to be matched
0049 %            together.
0050 % savefilename
0051 %         -- string indicating where to save the CSV file. The folder
0052 %            must exist.
0053 %% Optional Arguments
0054 % args.pairtype
0055 %         -- single-dimension array of integers whose length matches the
0056 %            length of 'mapping'. Allows user to tag each row in 'mapping' to a type.
0057 % args.cevent_trials
0058 %       -- string, the full path or relative path to a
0059 %          .mat or .csv file
0060 %       -- The timing information in this file is used to cut the data into
0061 %          trials. Ultimately this ensures that events from one trial
0062 %          cannot be paired with events from a second trial, even if the
0063 %          temporal relation holds.
0064 % args.files_numheaders
0065 %       -- integer array of size 2, indicating how many
0066 %          headers are in filename1 and filename2, respectively
0067 %       -- e.g. [1 1] for means to skip 1 header file for both
0068 % args.files_columns
0069 %       -- cell array of size 2, one cell for each filename, indicating which columns
0070 %          to grab from the .csv file
0071 %       -- e.g. {[3 4 5], [6 7 8]} for the two filenames
0072 %          [3 4 5] is for filename1, [6 7 8] is for filename2
0073 %       -- if empty, just grab all columns
0074 % args.cevent_trials_numheaders
0075 %       -- integer array of size 2, indicating how many
0076 %          headers are in filename1 and filename2, respectively
0077 %       -- e.g. [1 1] for means to skip 1 header file for both
0078 % args.cevent_trials_columns
0079 %       -- 1x3 integer array indicating which columns
0080 %          to grab from the .csv file
0081 %       -- if empty, just grab all columns
0082 %
0083 % The following arguments control many to many mapping
0084 % Consider the following many to many mapping from cev1 and cev2
0085 % 10, 15
0086 % 11, 15
0087 % 11, 16
0088 % 11, 17
0089 % To force 1 to 1 mapping, set either first_n_cev1 or last_n_cev1 to 1
0090 % args.first_n_cev1
0091 %         -- integer indicating to only output first N pairings of cev 1
0092 % args.first_n_cev2
0093 %         -- integer indicating to only output first N pairings of cev 2
0094 % args.last_n_cev1
0095 %         -- integer indicating to only output last N pairings of cev 1
0096 % args.last_n_cev2
0097 %         -- integer indicating to only output last N pairings of cev 2
0098 
0099 % Output is a CSV with each row respresenting a pair. The pairs can be
0100 % many-to-many.
0101 %
0102 % Two additional CSV files (_cev1wo.csv and _cev2wo.csv) are generated indicating which cevents from cev1
0103 % and cev2 were not paired.
0104 %
0105 % Only in-trial data will be considered, and cevents from one trial cannot
0106 % be paired with cevents from another trial (even if the timing holds true).
0107 %%
0108 
0109 switch option
0110     case 1
0111         % basic usage
0112         filename1 = '/scratch/multimaster/demo_results/extract_pairs_files/case1/cevent_data1.csv';
0113         filename2 = '/scratch/multimaster/demo_results/extract_pairs_files/case1/cevent_data2.csv';
0114         timing_relation = 'more(on1, on2, 2) & less(on1, on2, 5)';
0115         mapping = [1 1; 2 2 ; 3 3; 1 4; 2 4; 3 4; 4 4; 4 1; 4 2; 4 3];
0116         savefilename = '/scratch/multimaster/demo_results/extract_pairs_files/case1/case1_pairs.csv';
0117         extract_pairs_files(filename1, filename2, timing_relation, mapping, savefilename);
0118         
0119     case 2
0120         % some of these may be option, see above for details
0121         
0122         filename1 = '/scratch/multimaster/demo_results/extract_pairs_files/case2/cevent_data1.csv';
0123         filename2 = '/scratch/multimaster/demo_results/extract_pairs_files/case2/cevent_data2.csv';
0124         args.cevent_trials = '/scratch/multimaster/demo_results/extract_pairs_files/case2/cevent_trials.csv';
0125         args.files_numheaders = [0 0]; % zero headers in filename1 and filename2
0126         args.files_columns = {[1 2 3], [1 2 3]}; % grab first 3 columns of filename1 and filename2
0127         args.cevent_trials_numheaders = 0;
0128         args.cevent_trials_columns = [1 2 3];
0129         timing_relation = 'more(on1, on2, 2) & less(on1, on2, 5)';
0130         mapping = [1 1; 2 2 ; 3 3; 1 4; 2 4; 3 4; 4 4; 4 1; 4 2; 4 3];
0131         args.pairtype = [1 1 1 2 2 2 4 3 3 3];
0132         % for duplicate events, only grab first 1 and last 1 to be paired
0133         args.first_n_cev1 = 1;
0134         args.first_n_cev2 = 1;
0135         args.last_n_cev1 = 1;
0136         args.last_n_cev2 = 1;
0137         savefilename = '/scratch/multimaster/demo_results/extract_pairs_files/case2/case2_pairs.csv';
0138         extract_pairs_files(filename1, filename2, timing_relation, mapping, savefilename, args);
0139 end
0140 end

Generated on Tue 23-May-2017 03:00:58 by m2html © 2005