Document libcommon functions in pupil bench exp

fmelinscak · Apr 15, 2020 · 97f84b7 · 97f84b7
1 parent 85e95e1
commit 97f84b7
Show file tree

Hide file tree

Showing 18 changed files with 181 additions and 8 deletions.
diff --git a/examples/pspm_pupil/exp1/fit.m b/examples/pspm_pupil/exp1/fit.m
@@ -27,5 +27,5 @@
     options.exclude_missing = struct('segment_length', exclude_segment_length, 'cutoff', exclude_cutoff);
 
     out = pspm_glm(model, options);
-    [out, stats] = exclude_and_average(out, csp, out.stats_exclude);
+    stats = exclude_and_average(out, csp, out.stats_exclude);
 end
diff --git a/examples/pspm_pupil/exp2/fit.m b/examples/pspm_pupil/exp2/fit.m
@@ -26,5 +26,5 @@
 
     out = pspm_glm(model, options);
     not_exclude = zeros(1, numel(cell2mat(csp)), 'uint8');
-    [out, stats] = exclude_and_average(out, csp, not_exclude);
+    stats = exclude_and_average(out, csp, not_exclude);
 end
diff --git a/examples/pspm_pupil/exp4/fit.m b/examples/pspm_pupil/exp4/fit.m
@@ -39,7 +39,7 @@
     options.exclude_missing = struct('segment_length', exclusion_seg_len, 'cutoff', trial_exclusion_threshold);
 
     out = pspm_glm(model, options);
-    [out, stats] = exclude_and_average(out, csp, out.stats_exclude);
+    stats = exclude_and_average(out, csp, out.stats_exclude);
 end
 
 function [out, stats] = condition_wise(inarg)

diff --git a/examples/pspm_pupil/libcommon/exclude_and_average.m b/examples/pspm_pupil/libcommon/exclude_and_average.m
@@ -1,4 +1,18 @@
-function [glm, stats] = exclude_and_average(glm, csp, exclude_arr)
+function [stats] = exclude_and_average(glm, csp, exclude_arr)
+    % Compute CS+ and CS- beta stat averages from a fitted single-trial GLM structure.
+    %
+    % Parameters
+    % ----------
+    % glm : Fitted single-trial GLM structure.
+    %
+    % csp : A logical array where csp(i) is 1 if ith trial is a CS+
+    %
+    % exclude_arr : A logical array where exclude_arr(i) is 1 if ith trial should be
+    %               excluded from the average.
+    %
+    % Returns
+    % -------
+    % stats : A 2-element array holding the CS+ and CS- beta averages.
     csp = cell2mat(csp);
     bfno = glm.bf.bfno;
     stats_csp = 0;

diff --git a/examples/pspm_pupil/libcommon/fit_all.m b/examples/pspm_pupil/libcommon/fit_all.m
@@ -1,4 +1,20 @@
 function stats = fit_all(inarg)
+    % Fit all the subjects in the dataset given in inarg structure using the currently
+    % loaded fit.m function.
+    %
+    % Before the dataset is fit, it is copied to a temporary location specified with
+    % inarg.tmp_out_path so that the original data is left unmodified.
+    %
+    % Parameters
+    % ----------
+    % inarg : Structure with the following fields:
+    %   .datapath : field holding the path to the dataset to fit.
+    %   .tmp_out_path : field holding the path to the temporary location to copy the dataset.
+    %   .subject_ids : Array of subject IDs to fit
+    %
+    % Returns
+    % -------
+    % stats : Array with shape [2, n_subj] holding CS+ and CS- beta fits for each subject.
     orig_datapath = inarg.datapath;
     ds_name = split(orig_datapath, '/');
     ds_name = ds_name{end};

diff --git a/examples/pspm_pupil/libcommon/get_conditions.m b/examples/pspm_pupil/libcommon/get_conditions.m
@@ -1,4 +1,18 @@
 function [pupil_fpath, conditions] = get_conditions(datapath, subj_id)
+    % Return the pupil paths and timing structure for a subject. The type of the
+    % dataset is inferred from datapath.
+    %
+    % Parameters
+    % ----------
+    % datapath : Path to the dataset.
+    % subj_id : ID of the subject
+    %
+    % Returns
+    % -------
+    % pupil_fpath : Path or cell array holding the paths to the pupil files (all sessions)
+    %               for the given subject.
+    % conditions : Struct or cell array holding the condition structures (all sessions)
+    %              for the given subject.
     fparts = split(datapath, filesep);
     if isempty(fparts{end})
         dataset_name = fparts{end-1};

diff --git a/examples/pspm_pupil/libcommon/get_conditions_doxmem2.m b/examples/pspm_pupil/libcommon/get_conditions_doxmem2.m
@@ -1,4 +1,17 @@
 function [pupil_fpath, conditions] = get_conditions_doxmem2(datapath, subj_id)
+    % Return the pupil paths and timing structure for a subject from DoxMem2 dataset.
+    %
+    % Parameters
+    % ----------
+    % datapath : Path to the doxmem2 dataset.
+    % subj_id : ID of the subject
+    %
+    % Returns
+    % -------
+    % pupil_fpath : Cell array holding the paths to the pupil files (all sessions) for the
+    %               given subject.
+    % conditions : Cell array holding the condition structures (all sessions) for the
+    %              given subject.
     cogent_fpath = {...
         fullfile(datapath, sprintf('DoxMem2_cogent_%.2d_sn1.mat', subj_id)),
         fullfile(datapath, sprintf('DoxMem2_cogent_%.2d_sn2.mat', subj_id)),

diff --git a/examples/pspm_pupil/libcommon/get_conditions_fer02.m b/examples/pspm_pupil/libcommon/get_conditions_fer02.m
@@ -1,4 +1,17 @@
 function [pupil_fpath, conditions] = get_conditions_fer02(datapath, subj_id)
+    % Return the pupil paths and timing structure for a subject from FER02 dataset.
+    %
+    % Parameters
+    % ----------
+    % datapath : Path to the FER02 dataset.
+    % subj_id : ID of the subject
+    %
+    % Returns
+    % -------
+    % pupil_fpath : Cell array holding the paths to the pupil files (all sessions) for the
+    %               given subject.
+    % conditions : Cell array holding the condition structures (all sessions) for the
+    %              given subject.
     cogent_fpath = {};
     cogent = {};
     try

diff --git a/examples/pspm_pupil/libcommon/get_conditions_fss6b.m b/examples/pspm_pupil/libcommon/get_conditions_fss6b.m
@@ -1,4 +1,15 @@
 function [pupil_fpath, conditions] = get_conditions_fss6b(datapath, subj_id)
+    % Return the pupil paths and timing structure for a subject from FSS6B dataset.
+    %
+    % Parameters
+    % ----------
+    % datapath : Path to the FSS6B dataset.
+    % subj_id : ID of the subject
+    %
+    % Returns
+    % -------
+    % pupil_fpath : Path to the pupil file for the given subject.
+    % conditions : Condition structure for the given subject.
     pupil_fpath = fullfile(datapath, sprintf('FSS6B_pupil_%.2d.mat', subj_id));
     psych_fpath = fullfile(datapath, sprintf('FSS6B_psych_%.2d.mat', subj_id));
     pupil = load(pupil_fpath);

diff --git a/examples/pspm_pupil/libcommon/get_conditions_li.m b/examples/pspm_pupil/libcommon/get_conditions_li.m
@@ -1,4 +1,17 @@
 function [pupil_fpath, conditions] = get_conditions_li(datapath, subj_id)
+    % Return the pupil paths and timing structure for a subject from LI dataset.
+    %
+    % Parameters
+    % ----------
+    % datapath : Path to the LI dataset.
+    % subj_id : ID of the subject
+    %
+    % Returns
+    % -------
+    % pupil_fpath : Cell array holding the paths to the pupil files (all sessions) for the
+    %               given subject.
+    % conditions : Cell array holding the condition structures (all sessions) for the
+    %              given subject.
     pupil_fpath = {...
         fullfile(datapath, sprintf('LI_pupil_%.2d_sn1.mat', subj_id)),...
         fullfile(datapath, sprintf('LI_pupil_%.2d_sn2.mat', subj_id)) ...

diff --git a/examples/pspm_pupil/libcommon/get_conditions_pubfe.m b/examples/pspm_pupil/libcommon/get_conditions_pubfe.m
@@ -1,4 +1,17 @@
 function [pupil_fpath, conditions] = get_conditions_pubfe(datapath, subj_id)
+    % Return the pupil paths and timing structure for a subject from PubFe dataset.
+    %
+    % Parameters
+    % ----------
+    % datapath : Path to the PubFe dataset.
+    % subj_id : ID of the subject
+    %
+    % Returns
+    % -------
+    % pupil_fpath : Cell array holding the paths to the pupil files (all sessions) for the
+    %               given subject.
+    % conditions : Cell array holding the condition structures (all sessions) for the
+    %              given subject.
     pupil_fpath = {...
         fullfile(datapath, sprintf('PubFe_pupil_%.2d_sn1.mat', subj_id)),...
         fullfile(datapath, sprintf('PubFe_pupil_%.2d_sn2.mat', subj_id)) ...

diff --git a/examples/pspm_pupil/libcommon/get_conditions_sc4b.m b/examples/pspm_pupil/libcommon/get_conditions_sc4b.m
@@ -1,4 +1,15 @@
 function [pupil_fpath, conditions] = get_conditions_sc4b(datapath, subj_id)
+    % Return the pupil paths and timing structure for a subject from SC4B dataset.
+    %
+    % Parameters
+    % ----------
+    % datapath : Path to the SC4B dataset.
+    % subj_id : ID of the subject
+    %
+    % Returns
+    % -------
+    % pupil_fpath : Path to the pupil file for the given subject.
+    % conditions : Condition structure for the given subject.
     pupil_fpath = fullfile(datapath, sprintf('SC4B_pupil_%.2d_sn1.mat', subj_id));
     cogent_fpath = fullfile(datapath, sprintf('SC4B_cogent_%.2d.mat', subj_id));
     pupil = load(pupil_fpath);

diff --git a/examples/pspm_pupil/libcommon/get_conditions_vc7b.m b/examples/pspm_pupil/libcommon/get_conditions_vc7b.m
@@ -1,4 +1,15 @@
 function [pupil_fpath, conditions] = get_conditions_vc7b(datapath, subj_id)
+    % Return the pupil paths and timing structure for a subject from VC7B dataset.
+    %
+    % Parameters
+    % ----------
+    % datapath : Path to the VC7B dataset.
+    % subj_id : ID of the subject
+    %
+    % Returns
+    % -------
+    % pupil_fpath : Path to the pupil file for the given subject.
+    % conditions : Condition structure for the given subject.
     pupil_fpath = fullfile(datapath, sprintf('VC7B_pupil_%.2d_sn1.mat', subj_id));
     psych_fpath = fullfile(datapath, sprintf('VC7B_psych_%.2d.mat', subj_id));
     pupil = load(pupil_fpath);

diff --git a/examples/pspm_pupil/libcommon/perc_miss_overall.m b/examples/pspm_pupil/libcommon/perc_miss_overall.m
@@ -1,4 +1,15 @@
 function perc = perc_miss_overall(fp, channel)
+    % Return the overall missing data percentage of the data of a subject in
+    % the given channel.
+    %
+    % Parameters
+    % ----------
+    % fp : Path or cell to the paths (all sessions) of a subject.
+    % channel : Channels on which miss percentage should be computed.
+    %
+    % Returns
+    % -------
+    % perc : Overall missing data percentage in the range [0, 100].
     if ~iscell(fp)
         fp = {fp};
     end

diff --git a/examples/pspm_pupil/libcommon/pp_pfe.m b/examples/pspm_pupil/libcommon/pp_pfe.m
@@ -1,6 +1,16 @@
 function sts = pp_pfe(pupil_fpath)
+    % Perform pupil foreshortening error correction on the data of a subject.
+    % If the gaze channels are in pixels, they are first converted to milimeters.
+    %
+    % Parameters
+    % ----------
+    % pupil_fpath : Path or cell of paths (all sessions) to pupil data of a subject.
+    %
+    % Returns
+    % -------
+    % sts : Status flag.
     opt.mode = 'auto';
-    opt.C_z = 525;
+    opt.C_z = 625;
     for i = 1:numel(pupil_fpath)
         fpath = pupil_fpath{i};
         try

diff --git a/examples/pspm_pupil/libcommon/pp_valid_fixations.m b/examples/pspm_pupil/libcommon/pp_valid_fixations.m
@@ -1,4 +1,14 @@
 function sts = pp_valid_fixations(pupil_fpath, fixation_angle)
+    % Perform valid fixations filtering on the data of a subject.
+    % If the gaze channels are in pixels, they are first converted to milimeters.
+    %
+    % Parameters
+    % ----------
+    % pupil_fpath : Path or cell of paths (all sessions) to pupil data of a subject.
+    %
+    % Returns
+    % -------
+    % sts : Status flag.
     for i = 1:numel(pupil_fpath)
         fpath = pupil_fpath{i};
         try

diff --git a/examples/pspm_pupil/libcommon/util.py b/examples/pspm_pupil/libcommon/util.py
@@ -8,14 +8,16 @@
 import numpy as np
 import pandas as pd
 
-Dataset = namedtuple("Dataset", "name subject_ids")
-
 DATA_PATH = "data"
 OUT_PATH = "output"
 LIB_PATHS = ["/home/eozd/bachlab/pspm/src", "libcommon"]
 
 
 class Dataset:
+    """
+    Simple class to represent a dataset (e.g. doxmem2)
+    """
+
     def __init__(self, *args, name, subject_ids):
         self.name = name
         self.subject_ids = subject_ids
@@ -34,6 +36,10 @@ def __init__(self, *args, name, subject_ids):
 
 
 def sm_to_pandas(sm):
+    """
+    Convert a score matrix that is the result of sciunit TestSuite
+    to a regular pandas dataframe.
+    """
     n_rows, n_cols = sm.shape
     arr = np.empty(shape=(n_rows, n_cols), dtype=np.float64)
     for i in range(n_rows):
@@ -44,6 +50,9 @@ def sm_to_pandas(sm):
 
 
 def get_obs_dict_list(exp_output_path):
+    """
+    Get the observation dictionary that can be used in cognibench framework.
+    """
     obs_dict_list = [
         {
             "stimuli": {
@@ -59,6 +68,10 @@ def get_obs_dict_list(exp_output_path):
 
 
 def get_test_suite(exp_output_path):
+    """
+    Construct a test suite for pupil benchmarking. Each dataset in DATASET_LIST
+    will be a separate test in the suite.
+    """
     # prepare tests
     obs_dict_list = get_obs_dict_list(exp_output_path)
     CohensD = partialclass(scores.CohensDScore, min_score=-5, max_score=5)

diff --git a/examples/pspm_pupil/run_all.sh b/examples/pspm_pupil/run_all.sh
@@ -2,7 +2,7 @@
 #
 # STEPS
 # 1. If there is no data folder, download datasets using download_datasets.sh
-# 2. Change PsPM src folder path in libcommon/util.py line 14
+# 2. Change PsPM src folder path in libcommon/util.py LIB_PATHS definition
 # 3. Run this script
 #
 # Outputs will be stored in output folder