Merge Development into Master

+nla/+edge/+permutationMethods/+tree/PermutationNode.m

@@ -0,0 +1,68 @@
+classdef PermutationNode < handle
+    %PERMUTATIONNODE Node which defines one grouping of each permutatino tree
+    %
+    % node = permutationNode(level, input_data, permutation_groups)
+    % node = One grouping of data for each permutation group. Each group contains the data (functional connectivity)
+    %   along with the index (column) the data is located and the original column
+    % level = The level of the tree. 0 is the root, 1 the first column of permutation groups, 2 the next...
+    % input_data = The input data. Currently, this is the functional connectivity
+    % permutation_groups = the columns from the csv file that characterizes the permutation groupings
+    %   Each column of the data is 1 permutation grouping. 
+    %   Each row is one subject/data entry
+    %   Values should be positive integers. Groups must be independent in each column
+
+
+    properties
+        children = [] % Nodes that descend from the current node. The column to the right of the current level in permutation groups
+        level = 0 % 0 is root, initial_data
+        parent = false % if false, this is the root of the tree. If not, this is the node that came before
+        data_with_indexes = {} % The data. 3 cell object. {data (some big array), current index, original index}
+        permutation_groups = [] % The groups that descend off of this one
+    end
+
+    properties (SetAccess = immutable)
+        original_data % matrix of size input_data.length x 3 with each row [data_value, current_index, original_index]
+    end
+
+    methods
+        function obj = PermutationNode(level, input_data, permutation_groups)
+            % Inputs:
+            % input_data is the functional connectivity with each subject as a vector. Size: [edges(?) x subjects]
+            % permutation groups. This will be a matrix with each level of permutation a vector. Size: [subjects x levels of permutations]
+
+            if isequal(level, 0)
+                obj.permutation_groups = permutation_groups;
+                obj.original_data = {input_data, [1:size(input_data, 2)], [1:size(input_data, 2)]};
+                obj.data_with_indexes = obj.original_data;
+            else
+                size_permutation_groups = size(permutation_groups);
+                if size_permutation_groups(2) > 1
+                    obj.permutation_groups = permutation_groups(:, 2:end);
+                end
+                functional_connectivity = input_data{1};
+                index_length = size(input_data{2}, 2);
+                current_index = [1:index_length];
+                original_index = input_data{3};
+                obj.original_data = {functional_connectivity, current_index, original_index};
+                obj.data_with_indexes = obj.original_data;
+            end
+            if ~isempty(obj.permutation_groups)
+                group_numbers = unique(obj.permutation_groups(:, 1));
+                for group_number = 1:numel(group_numbers)
+                    group_indexes = (obj.permutation_groups(:, 1) == group_numbers(group_number));
+                    temp_permutation_groups = obj.permutation_groups(group_indexes, :);
+                    group_input_data = obj.data_with_indexes{1};
+                    group_current_indexes = obj.data_with_indexes{2};
+                    group_original_indexes = obj.data_with_indexes{3};
+                    group_data = {group_input_data(:, group_indexes), group_current_indexes(group_indexes), group_original_indexes(group_indexes)};
+                    obj.children = [obj.children obj.createNodes(obj.level + 1, temp_permutation_groups, group_data, obj)];
+                end
+            end
+        end
+
+        function node = createNodes(obj, level, group_permutations, input_group_data, parent_node)
+            node = nla.edge.permutationMethods.tree.PermutationNode(level, input_group_data, group_permutations);
+            node.parent = parent_node;
+        end
+    end
+end

+nla/+edge/+permutationMethods/+tree/PermutationTree.m

@@ -0,0 +1,31 @@
+classdef PermutationTree < handle
+    %PERMUTATIONTREE Base class for permutation groups. This just bundles all the permutation nodes
+    % together for ease. 
+    %
+    % tree = PermutationTree(input_data, permutation_groups)
+    % tree = The tree object. Consists of the raw permutation groups along with the raw data along
+    %   starting indexes
+    % 
+    % input_data = The data that is permuted. This is usually the functional connectivity (right now, that's all it works for)
+    % permutation_groups = the columns from the csv file that characterizes the permutation groupings
+    %   Each column of the data is 1 permutation grouping. 
+    %   Each row is one subject/data entry
+    %   Values should be positive integers. Groups must be independent in each column
+
+    properties
+        permutation_groups % Raw from the behavior table to define permutation grouping
+        root_node % The first "level 0" node of the tree
+    end
+
+    properties (SetAccess = immutable)
+        original_data = {} % This is going to be a matrix of input_data.length x 2 [data_value, original_index]
+    end
+
+    methods
+        function obj = PermutationTree(input_data, permutation_groups)
+            obj.original_data = {input_data, [1:size(input_data, 2)]'};
+            obj.permutation_groups = permutation_groups;
+            obj.root_node = nla.edge.permutationMethods.tree.PermutationNode(0, input_data, permutation_groups);
+        end
+    end
+end

+nla/+edge/+permutationMethods/MultiLevel.m

@@ -0,0 +1,81 @@
+classdef MultiLevel < nla.edge.permutationMethods.Base
+    %MULTILEVEL Multilevel permutation method
+    %
+    % multi-level strategy = multiLevel()
+    % multi-level strategy = the object which will be doing the permutations the data. The functional
+    %   connectivity is permuted
+    % 
+    % needed for methods:
+    % test_options = this is the options and data for the tests being run. Sometimes called 'input_struct'
+    %
+    % How this works: THe object controls the permutations. It can be instantiated without any data
+    % Before permutations can be run, a permutation tree needs to be created. This needs to be done with the
+    % "createPermutationTree(test_options)" method. This creates a permutation tree (with the nodes). It
+    % also will find all the "terminal nodes" - the nodes that have no children. These are the last groupings
+    % and the actual data to be permuted
+    %
+    % After the tree is created (this only is done once), the object is ready to do the permutations.
+    % This is done by taking each terminal node, getting the current indexes of the data, permuting them, 
+    % and then applying these indexes to the data.
+
+    properties
+        permutation_tree
+        terminal_nodes = []
+    end
+
+    methods
+        function obj = MultiLevel()
+        end
+
+        function obj = createPermutationTree(obj, input_struct)
+            if ~isfield(input_struct, "permutation_groups")
+                input_struct.permutation_groups = [];
+            end
+            obj.permutation_tree = nla.edge.permutationMethods.tree.PermutationTree(...
+                input_struct.func_conn.v, input_struct.permutation_groups...
+            );
+            tree_root = obj.permutation_tree.root_node;
+            obj = obj.depthFirstSearch(tree_root);
+        end
+
+        function permuted_input_struct = permute(obj, orig_input_struct)
+            permuted_input_struct = orig_input_struct;
+            permuted_transposed_functional_connectivity = zeros(size(orig_input_struct.func_conn.v'));
+
+            for node_index = 1:numel(obj.terminal_nodes)
+                node = obj.terminal_nodes(node_index);
+                current_indexes = node.data_with_indexes{2};
+                original_indexes = node.data_with_indexes{3};
+                data = node.data_with_indexes{1}'; % transpose to match dimensions of indexes
+
+                permuted_indexes = nla.helpers.permuteVector(current_indexes);
+                sorted_original_indexes = sort(original_indexes, 2);
+                original_indexes = original_indexes(permuted_indexes);
+                data = data(permuted_indexes, :);
+                node.data_with_indexes = {data', current_indexes, original_indexes};
+                permuted_transposed_functional_connectivity(sorted_original_indexes, :) = data;
+            end
+
+            permuted_input_struct.func_conn.v = permuted_transposed_functional_connectivity';
+        end
+
+        function obj = depthFirstSearch(obj, node_input)
+            node_queue = [node_input];
+            while ~isempty(node_queue)
+                node = node_queue(1);
+                if isempty(node.children)
+                    obj.terminal_nodes = [obj.terminal_nodes, node];
+                else
+                    for child = 1:numel(node.children)
+                        node_queue = [node_queue; node.children(child)];
+                    end
+                end
+                if size(node_queue, 1) > 1
+                    node_queue = node_queue(2:end, :);
+                else
+                    node_queue = [];
+                end
+            end
+        end
+    end
+end

+nla/+edge/+result/Base.m

@@ -44,6 +44,7 @@ function output(obj, net_atlas, flags, prob_label)
             if ~isfield(flags, 'display_sig')
                 flags.display_sig = true;
             end
+
             if flags.display_sig
                 if ~exist('prob_label', 'var')
                     prob_label = [sprintf('Edge-level Significance (P < %g)', obj.prob_max), prob_label_appended];

+nla/+edge/+result/SandwichEstimator.m

@@ -0,0 +1,102 @@
+classdef SandwichEstimator < nla.edge.result.Base
+
+    properties
+        % test result specific properties go here (things that are
+        % specific to a particular data input, ie: results of running the sandwich
+        % estimator on said data, or covariates which are specific to a
+        % particular data set)
+        regressCoeffs % numCovariates x numFcElems                             
+
+        stdError
+        tVals
+        pVals
+        contrasts 
+        contrastCalc
+        contrastSE
+        contrastTVal
+        contrastPVal
+    end
+
+    methods
+        function obj = SandwichEstimator(size, prob_max)
+            import nla.* % required due to matlab package system quirks
+
+            %MATLAB WEIRDNESS WARNING
+            %In parallel processing, this constructor is somehow called
+            %with zero arguments, not in any code I've written. Need to be
+            %able to get through zero argument case without erroring in
+            %order to run in parallel mode. Does not happen in non-parallel
+            %mode.
+            if nargin ~= 0
+                %want to call superclass constructor obj@nla.EdgeLevelResult(size, prob_max);
+                %but can't within any "if block" due to MATLABism
+                %copying here
+                obj.coeff = TriMatrix(size);
+                obj.prob = TriMatrix(size);
+                obj.prob_sig = TriMatrix(size, 'logical');
+                obj.prob_max = prob_max;
+                obj.coeff_name = 'contrast t-vals';
+
+            end            
+
+        end
+
+        function output(obj, net_atlas, display_sig)
+            import nla.* % required due to matlab package system quirks
+            output@nla.edge.result.Base(obj, net_atlas, display_sig);
+
+        end
+
+        % merged is a function which merges 2 results from the same test
+        function merge(obj, results)
+            import nla.* % required due to matlab package system quirks
+            merge@nla.edge.result.Base(obj, results);
+
+            %% TODO Code to merge multiple SandwichEstimatorResults goes here
+            % This function is called by TestPool, signature should not
+            % change. Results is a vector of other
+            % SandwhichEstimatorResults(one per process). This function is
+            % called to merge the results of said processes. If you are ex:
+            % calculating an average value, you should probably do it here:
+            % ex: sum([results.value]) / obj.perm_count would produce the
+            % average of 'value'
+        end
+
+        function setContrasts(obj, newContrasts)
+            %force contrasts to be row vector
+            if ~any(size(newContrasts)==1)
+                error('SandwichEstimatorResults: contrasts must be 1D vector');
+            else
+                newContrasts = reshape(newContrasts,1,numel(newContrasts));
+            end
+
+            %check that sizes of contrasts matches size of regression
+            %coefficients if they've already been fit
+            %if model has already been fit, confirm contrasts is proper
+            %size of existing results and modify result values to match new
+            %contrast setting
+            if ~isempty(obj.regressCoeff)
+                %confirm contrasts is proper size
+                if length(newContrasts) ~= size(obj.regressCoeffs,1)
+                    errMsg = sprintf(['SandwichEstimatorResult: ',...
+                                      'size of contrasts does not match number of current fitted regression coefficients',...
+                                      '%i contrasts vs %i regression coeffs'],...
+                                      length(newContrasts),size(obj.regressCoeffs,1));
+                    error(errMsg);
+                end
+
+                %update existing coeff and prob results with new contrasts
+                obj.coeff.v = (newContrasts * obj.regressCoeffs)';
+                obj.prob.v = (newContrasts * obj.betaCovarTvals)';
+            end
+
+            obj.contrasts = newContrasts;               
+
+
+        end
+
+
+
+    end
+end
+

+nla/+edge/+test/PairedT.m

@@ -49,6 +49,7 @@
             behavior_handle = nla.helpers.firstInstanceOfClass(inputs, 'nla.inputField.Behavior');
             behavior_handle.covariates_enabled = nla.inputField.CovariatesEnabled.ONLY_FC;
 
+            inputs{end + 1} = nla.inputField.Label("", "");
             inputs{end + 1} = nla.inputField.String('group1_name', 'Group 1 name:', 'Group1');
             inputs{end + 1} = nla.inputField.Number('group1_val', 'Group 1 behavior value:', -Inf, 1, Inf);
             inputs{end + 1} = nla.inputField.String('group2_name', 'Group 2 name:', 'Group2');