IdMapNode.m

classdef IdMapNode < DataTree.DefaultNode
  % Data Tree element which can be filtered by 'ids'
  %
  % The children branches of this data tree node are all tagged with one or
  % several "Id"s.
  %
  % The branches can then be accessed via the 'id' argument of the get_index()
  % method.
  %
  % Note: If one branch is tagged with a list of several "Id"s, any of these
  % "Id"s in the last can be used to access the tagged branch.

  properties (SetAccess = private)
    % cell array of "Id" strings
    idmap;
  end

  properties (Constant)
    % Data node type identifier
    data_node_type = 'IdMap';
  end

  properties (Access = private)
    % struct mapping between "Id"s and indices of children.
    invmap;
  end

  methods

    function ic = IdMapNode(idmap, initvalues, mergefun)
      % function ic = IdMapNode(idmap, initvalues, mergefun)
      % constructor for an IdMapNode mapping the children nodes with "Id" tags.
      %
      % This constructor can be run in two modes:
      %   -# @em Flat-mode: This creates exactly one IdMapNode, such that
      %      it is possible that one child is tagged with more than one "Id"
      %      string.
      %   -# @em Recursive-mode: This creates a tree of IdMapNode nodes,
      %      such that the leafs of this tree are tagges with exactly one "Id"
      %      string.
      %
      % The constructor runs in @em Flat-mode, if a 'mergefun' is given or if
      % 'initvalues' is a cell array. Otherwise, it runs in @em Recursive-mode.
      %
      % @sa test_indexed_node() for example usage of this constructor.
      %
      % @note that the values given by 'initvalues' are wrapped by a
      % DataTree.DummyLeafNode if they are not derived from a DataTree.INode.
      %
      % Parameters:
      %   idmap:      a cell array of "Id" strings that are tagged to the
      %               children of this node. These "Id"s can also be nested,
      %               which either leads to a child tagged with more than one
      %               "Id"s or a recursively build tree of IdMapNode nodes.
      %               See the explanation of @em Flat-mode and @em
      %               Recursive-Mode for details.
      %   initvalues: This can be
      %                  -# a scalar,
      %                  -# a cell array,
      %                  -# a struct or
      %                  -# an IdMapNode
      %                  .
      %                  - In the first case every child of this node is set to
      %                    this scalar.
      %                  - In the second case the 'i'-th child is set to
      %                    'initvalues{i}'.
      %                  - In the third and fourth case, a child tagged with
      %                    'id' is set to 'initvalues.(id)' respectively
      %                    'get(initvalues, get_index(initvalues, id, [], []))'.
      %                    In @em Flat-mode, the 'mergefun' might apply here,
      %                    too.
      %                  .
      %   mergefun: This is a function pointer to a function expecting a cell
      %             array of values as an argument and returning an arbitrary
      %             value.
      %             This function pointer is used, in case the constructor runs
      %             in @em Flat-mode and the initvalues are given as an
      %             IdMapNode or a struct. For children tagged with several
      %             "Id"s 'id1, ..., idn', mergefun can be used to compute a
      %             value for this child from the cell array
      %             '{initvalues.id1,..., initvalues.idn}'.
      %             If 'mergefun' is set to '[]', a default function
      %             @code @(x) x{1}; @endcode is used.

      ic.idmap = idmap;
      ic.values = cell(1, length(idmap));

      if nargin == 2 && ~iscell(initvalues)
        might_be_recursive = true;
      else
        might_be_recursive = false;
      end
      recursive = false;

      ic.invmap = [];

      for i = 1:length(idmap)
        if iscell(idmap{i})
          if might_be_recursive
            ic.values{i} = DataTree.IdMapNode(idmap{i}, initvalues);
            recursive = true;
          end

          idmapi = DataTree.IdMapNode.flatten_cell_array(idmap{i});
          for j = 1:length(idmapi)
            ic.invmap.(idmapi{j}) = i;
          end
        else
          ic.invmap.(idmap{i}) = i;
        end
      end

      % do we have initial values?
      if nargin >= 2
        if ~recursive
          if iscell(initvalues)
            assert(length(initvalues) == length(ic.values));
            for i = 1:length(initvalues)
              if isa(initvalues{i}, 'DataTree.INode')
                ic.values{i} = initvalues{i};
              else
                ic.values{i} = DataTree.DummyLeafNode(initvalues{i});
              end
            end
          else
            if nargin <= 2
              mergefun = [];
            end
            if ~isempty(initvalues)
              set_values(ic, initvalues, mergefun);
            end
          end
        else
          set_values(ic, initvalues);
        end
      end

    end

    function data     = get(this, index)
      % function data     = get(this, index)
      % @copybrief DataTreeINode.get()
      %
      % @copydetails DataTreeINode.get()
      if length(index) > 1
        data = get(this.values{index(1)}, index(2:end));
      elseif length(index) == 1
        if isa(this.values{index}, 'DataTree.DummyLeafNode')
          data = get(this.values{index}, 1);
        else
          data = this.values{index};
        end
      else
        data = [];
      end
    end

    % Interface methods

    function index = get_index(this, id, mu, nt)
      % function index = get_index(this, id, mu, nt)
      % @copybrief DataTree.INode.get_index()
      %
      % Parameters:
      %   id: id string filtered by this node or another IdMapNode instance.
      %   mu: a parameter vector filtered through a DataTree.PpartNode instance in
      %       the tree hierarchy.
      %   nt: an integer corresponding to a time step index filtered through a
      %       DataTree.TpartNode instance in the tree hierarchy.
      %
      % Return values:
      %   index: index vector for the element which is filter by the argument
      %          triple. If none such element exists, empty vector.
      if nargin <=1
        id = [];
      end
      if nargin <=2
        mu = [];
      end
      if nargin <=3
        nt = [];
      end
      if isfield(this.invmap, id)
        invid = this.invmap.(id);
        index = [invid, get_index(this.values{invid}, id, mu, nt)];
      else
        index = [];
      end
    end

%    function path = get_path_index(this, id, mu, nt)
%      % function path = get_path_index(this, id, mu, nt)
%      %
%      path = get_index(this, id, mu, nt);
%      if ~this.recursive || iscell(this.idmap{path})
%        path = [ path, get_path_index(this.values{path}, id, mu, nt) ];
%      end
%    end

    function tree = create_tree(this, creator, ids, mu_cube, tslice, basepath)
      % function tree = create_tree(this, creator, ids, mu_cube, tslice, basepath)
      % @copybrief DataTree.INode.create_tree()
      %
      % @copydetails DataTree.INode.create_tree()
      %
      % Calls DataTree.Creator.create_idmap_node() to build new elements.

      if nargin < 3
        ids = [];
      end
      if nargin < 4
        mu_cube = [];
      end
      if nargin < 5
        tslice = [];
      end
      if nargin < 6
        basepath = [];
      end

      % get possible indices for traversal
      if isempty(ids)
        ids = fieldnames(this.invmap);
        indices = 1:length(this);
      else
        ids=intersect(fieldnames(this.invmap), ids);
        if isempty(ids)
          ids = fieldnames(this.invmap);
        end
        indices = unique(cellfun(@(x) this.invmap.(x), ids));
        %        indices = unique(cellfun(@(x) get_index(this, x, [], []), ids));
      end

      initvalues = cell(1, length(indices));
      id_map     = cell(1, length(indices));
      for i=1:length(indices)
        % compute id intersection
        new_id_extract = cellfun(@(x) this.invmap.(x)==indices(i), ids);
        new_ids        = ids(new_id_extract);
        id_map{i}      = new_ids;

        initvalues{i} = create_tree(get(this, indices(i)), creator, ...
                                    new_ids, mu_cube, tslice, ...
                                    [basepath, indices(i)]);
      end
      if length(indices) == 1
        tree = initvalues{1};
      elseif isempty(indices)
        throw('Merge of trees failed, because given id region was not found!');
      else
        tree = create_idmap_node(creator, id_map, initvalues);
      end
    end

    function this = set(this, i, value, mergefun)
      % function this = set(this, i, value[, mergefun])
      % sets a new value at a specific child branch
      %
      % @note only direct children can be set.
      %
      % Parameters:
      %   i:        scalar index of the child to be set or vector of indices.
      %             In the latter case, set() is called recursively.
      %   value:    a scalar, a struct or a tree of IdMapNode nodes as
      %             described in the constructor IdMapNode.IdMapNode().
      %   mergefun: (optional) If given, the function runs in @em Flat-mode as
      %             described in the constructor description IdMapNode.IdMapNode().
      %             Then 'value' needs to be a struct or a tree of IdMapNode
      %             nodes.
      %
      % Return values:
      %   this:     handle to the changed IdMapNode.
      if isempty(i)
        if nargin <= 3
          this = set_values(this, value);
        else
          this = set_values(this, value, mergefun);
        end
        return
      elseif length(i) > 1
        if nargin <= 3
          set(this.values{i(1)}, i(2:end), value)
        else
          set(this.values{i(1)}, i(2:end), value, mergefun)
        end
      elseif iscell(this.idmap{i})
        if nargin <= 3
          this = set_values(this.values{i}, value);
        else
          this = set_values(this.values{i}, value, mergefun);
        end
      else
         if isa(value, 'DataTree.INode')
           this.values{i} = value;
         else
           this.values{i} = DataTree.DummyLeafNode(value);
         end
      end
    end

    function scalar = scalar(this, mergefun)
      % function scalar = scalar(this, mergefun)
      % reduces the data tree values with help of the mergefun
      %
      % Parameters:
      %   mergefun: This is a function pointer to a function expecting a cell
      %             array of values as an argument and returning an arbitrary
      %             value.
      %             For children tagged with several "Id"s 'id1, ..., idn',
      %             mergefun can be used to compute a single value for all thes
      %             children values. It gathers the values
      %             '{ values1, ..., valuesn }' in a cell array and applies the
      %             'mergefun' on it. The result is returned. The algorithm is
      %             run recursively, such that the leaf-level is reduced first,
      %             and the upper level's values are reduced.
      %             If 'mergefun' is set to '[]', a default function
      %             @code @(x) x{1}; @endcode is used.
      if nargin == 1
        mergefun = @(x) x{1};
      end

      tmpcurvals = get_flat_struct(this);

      scalar = DataTree.IdMapNode.reduce(this.idmap, tmpcurvals, mergefun);
    end


    %% Other Methods

    function ids = get_all_ids(this)
      % function ids = get_all_ids(this)
      % returns all "Id" strings in this IdMapNode.
      %
      % @note that a flat cell array is returned, such that this might unequal
      % to the idmap.
      %
      % Return values:
      %   ids: a cell array of strings with the "Id"s in this data tree.
      ids = unique(DataTree.IdMapNode.flatten_cell_array(this.idmap));
    end

    function st = get_flat_struct(this)
      % function st = get_flat_struct(this)
      % makes a struct from the data tree with field names equal to the "Id"
      % names.
      %
      % Return values:
      %   st: flat struct as described above
      ids    = get_all_ids(this);

      vals   = cellfun(@(x) get(this, get_index(this, x, [], [])), ids, 'UniformOutput', false);

      stcell = reshape([ids;vals], 1, 2*length(ids));
      st     = struct(stcell{:});
    end

    function str = num2str(this)
      % function str = num2str(this)
      % converts the data tree into a string
      %
      % Return values:
      %   str: a string representation of the data tree
      fs = get_flat_struct(this);
      fns = fieldnames(fs);
      str = '[';
      for i = 1:length(fns)
        str = [ str, fns{i}, ': ', num2str(fs.(fns{i})) ];
        if i < length(fns)
          str = [ str, ', ' ];
        end
      end
      str = [ str, ']' ];
    end

    function this = minus(this, scalar)
      % function this = minus(this, scalar)
      % substracts a scalar from each of the values in the data tree.
      %
      % This function assumes, that the IdMapNode has only leaf children.
      %
      % Parameters:
      %   scalar:   The scalar to substract from the leaf values.
      %
      % Return values:
      %   this:     handle to the changed IdMapNode.
      for i = 1:length(this.values)
        assert(isa(this.values{i}, 'DataTree.ILeafNode'));
        this.values{i} = DataTree.DummyLeafNode(get(this.values{i},1) - scalar);
      end
    end


    function display(this)
      % function display(this)
      % prints out a string representation of the data tree.
      disp(get_flat_struct(this));
    end
  end

  methods(Access = private)
    function this = set_values(this, values, mergefun)
      % function this = set_values(this, values, mergefun)
      % sets new values in the data tree.
      %
      % Parameters:
      %   values: the new values. This can be either
      %     -# a scalar substituting all values by this scalar,
      %     -# another tree of IdMapNode nodes or a struct, indicating which
      %     "Id" mapped values shall be set.
      % Return values:
      %   this: handle to the current IdMapNode.
      if nargin == 3
        recursive = false;
        if isempty(mergefun)
          mergefun = @(x) x{1};
        end
      else
        recursive = true;
      end

      if isa(values, 'DataTree.IdMapNode')
        values = get_flat_struct(values);
      end
      if isstruct(values)
        for i = 1:length(this.idmap)
          fn = this.idmap{i};
          if iscell(this.idmap{i})
            if recursive
              set_values(this.values{i}, values);
            else
              try
                this.values{i} = DataTree.DummyLeafNode(...
                  DataTree.IdMapNode.reduce(this.idmap{i}, values, mergefun)...
                                                  );
              catch exception
                error(['Could not set values. Exception:, ' getReport(exception)]);
              end
            end
          elseif isfield(values, fn)
            val = values.(fn);
            if isa(val, 'DataTree.INode')
              this.values{i} = val;
            else
              this.values{i} = DataTree.DummyLeafNode(val);
            end
          end
        end
      elseif isscalar(values)
        for i = 1:length(this.values)
          this.values{i} = DataTree.DummyLeafNode(values);
        end
      elseif isempty(values)
        warning('RBmatlab:Logic', 'Assigned nothing, because values argument is empty!');
      else
        error('Invalid assignment argument in method ''set_values''.');
      end
    end
  end

  methods(Static, Access = public)

    function flatca = flatten_cell_array(ca)
      % function flatca = flatten_cell_array(ca)
      % flattens a cell array, i.e. returns a cell without cell entries which
      % are cell arrays by itself.
      %
      % Parameters:
      %   ca:  a cell array
      %
      % Return values:
      %   flatca: the flattended cell array
      for i = 1:length(ca)
        if iscell(ca{i})
          ca{i} = DataTree.IdMapNode.flatten_cell_array(ca{i});
        else
          ca{i} = ca(i);
        end
      end
      flatca = [ca{:}];
    end
  end

  methods(Static, Access = private)

    function value = reduce(idmap, values, mergefun)
      % function value = reduce(idmap, values, mergefun)
      % Recursively reduces the leaf values of the data tree to a scalar value
      %
      % This function recursively reduces the values.
      %
      % Parameters:
      %   values:   struct of values mapping "Id"s to values
      %   mergefun: function ptr assuming a cell of values as an argument.
      %             By default this is set to a function that returns the first
      %             cell argument.
      % Return values:
      %   value:    scalar return by the 'mergefun'
      if nargin == 2
        mergefun = @(x) x{1};
      end
      tmpvals = cell(1, length(idmap));
      for i = 1:length(idmap)
        if iscell(idmap{i})
          tmpvals{i} = DataTree.IdMapNode.reduce(idmap{i}, values, mergefun);
        else
          if ~isfield(values, idmap{i})
            throw(MException('RBmatlab:IdMapNode:internal',['Values are missing the field: ', idmap{i}]));
          end
          val = values.(idmap{i});
          if isa(val, 'DataTree.DummyLeafNode')
            val = get(val, 1);
          end
          tmpvals{i} = val;
        end
      end

      value = mergefun(tmpvals);

    end
  end
  methods(Static)
    function idname = name_from_idmap(idmap)
      % function idname = name_from_idmap(idmap)
      % creates a string representation of an "Id"-map
      %
      % Parameters:
      %   idmap: a cell array of strings
      %
      % Return values:
      %   idname: a string of all "Id"s concatenated with the '_' character.

      tmp    = unique(DataTree.IdMapNode.flatten_cell_array(idmap));
      idname = sprintf('%s_', tmp{:});
    end
  end
end