Merge pull request #836 from bachlab/822_pspm_pupil_pp_unit_check

822 pspm pupil pp unit check

Author: dominikbach

src/pspm_pupil_pp.m

@@ -1,10 +1,12 @@
 function [sts, outchannel] = pspm_pupil_pp (fn, options)
 % ● Description
-%   pspm_pupil_pp preprocesses pupil diameter signals given in any unit of
-%   measurement, with a possibility of combining left/right pupil. 
-%   It performs the steps described in [1]. This function uses
-%   a modified version of [2]. The modified version with a list of changes
-%   from the original is shipped with PsPM under pupil-size directory.
+%   pspm_pupil_pp preprocesses pupil diameter signals provided in
+%   millimeters (mm), with the option to combine left and right pupil data.
+%   If the measurement unit is not 'mm' but one of the supported units
+%   ('cm', 'dm', 'm', 'km', 'in', 'inches'), it will be automatically
+%   converted to mm. It performs the steps described in [1]. This function
+%   uses a modified version of [2]. The modified version with a list of
+%   changes from the original is shipped with PsPM under pupil-size directory.
 %   Pupil preprocessing is performed in three main steps:
 %   1.  In the first step, the "valid" samples are determined. Samples that 
 %       are not valid are not used in the second step. Determining valid 
@@ -153,11 +155,29 @@
 [sts_load, data,infos, pos_of_channel(1)] = pspm_load_channel(alldata, options.channel, 'pupil');
 if sts_load ~= 1, return, end
 
+% Check for invalid pupil data units in options.channel
+con_flag = 0;
+[stc1,data] = pspm_check_units(data);
+if stc1 < 1
+    warning('ID:invalid_unit', 'Unsupported pupil data unit: "%s" in "options.channel".', data.header.units);
+    return;
+elseif stc1 == 2, con_flag = 1 ; end
+
 if action_combine
     [sts_load, data_combine, infos, pos_of_channel(2)] = pspm_load_channel(alldata, options.channel_combine, 'pupil');
     if sts_load ~= 1
         return
     end
+    % Check for invalid pupil data units in options.channel
+    [stc2,data_combine] = pspm_check_units(data_combine);
+    if stc2 < 1
+        warning('ID:invalid_unit', 'Unsupported pupil data unit: "%s" in "options.channel".', data.header.units);
+        return
+    elseif stc2 == 2, con_flag = 1 ; end
+
+
+
+
     [sts1, eye1] = pspm_find_eye(data.header.chantype);
     [sts2, eye2] = pspm_find_eye(data_combine.header.chantype);
     if (sts1 < 1 || sts2 < 1), return, end
@@ -225,6 +245,8 @@
 [sts, out_id] = pspm_write_channel(fn, smooth_signal, options.channel_action, o);
 outchannel = out_id.channel;
 
+if con_flag == 1 , warning('At least one channel was converted to "mm". See details above.'); end
+
 %%  7 run second pass if required
 if ~flag_valid_combine
     [sts, out_id] = pspm_pupil_pp(fn, newoptions);
@@ -359,3 +381,31 @@
     end
   end
 end
+
+function [sts,data] = pspm_check_units(data)
+% sts will return 1 when units are "mm" and 2 when the data was converted
+% and -1 in all other cases
+sts = -1;
+convertable_units = { 'cm', 'dm', 'm', 'km', 'in', 'inches'};
+
+    if ~strcmp(data.header.units,'mm')
+        if ~ismember(data.header.units, convertable_units)
+            return;
+        else
+        % convert to 'mm'
+        [stc, converted] = pspm_convert_unit(data.data, data.header.units,'mm');
+            if stc == 1
+               % [~ , eye, new_chantype] = pspm_find_eye(data.header.chantype); % maybe?
+                warning(' "%s" channel data was converted from "%s" to "mm".',  data.header.chantype, data.header.units);
+                data.data = converted;
+                data.header.units = 'mm';
+                sts = 2;
+                return;
+            else
+                return;
+            end
+        end
+
+    end
+sts = 1;
+return

src/pspm_pupil_pp_options.m

@@ -15,10 +15,10 @@
 %   │ 
 %   │ // Allowable values criteria
 %   │ 
-%   ├─PupilDiameter_Min:  Minimum allowable pupil size. Pupil values less than 
-%   │                     this value will be marked as invalid. (Default: 1.5)
-%   ├─PupilDiameter_Max:  Maximum allowable pupil size. Pupil values greater than 
-%   │                     thin value will be marked as invalid. (Default: 9.0)
+%   ├─PupilDiameter_Min:  Minimum allowable pupil size in mm. Pupil values less than 
+%   │                     this value will be marked as invalid. (Default: 1.5 mm)
+%   ├─PupilDiameter_Max:  Maximum allowable pupil size in mm. Pupil values greater than 
+%   │                     thin value will be marked as invalid. (Default: 9.0 mm)
 %   │ 
 %   │ // Isolated sample filter criteria
 %   │ // 'Sample-islands' are clusters of samples that are temporally separated