%BAGC Bag classifier for classifying sets of object instances
%
%		[WBAG,WOBJ] = BAGC(A,OBJCLASSF,BAGINDEX,BAGCOMBC,BAGCLASSF,BAGLAB)
%		 WBAG       = A*BAGC([],OBJCLASSF,BAGINDEX,BAGCOMBC,BAGCLASSF,BAGLAB)
%		 WBAG       = A*BAGC(OBJCLASSF,BAGINDEX,BAGCOMBC,BAGCLASSF,BAGLAB)
%		 D          = B*WBAG
%
% INPUT
%   A          Training dataset with object labels and bag indices 
%   B          Test Dataset with index list of bags, stored as label list 
%   OBJCLASSF  Trained or untrained object classifier, default QDC
%   BAGINDEX   String or a label_list_index defining in which label list
%              of A the bag indices are stored, default 2.
%   BAGCOMBC   Combiner for objects in a bag, default VOTEC
%   BAGCLASSF  Untrained classifier for bags, default FISHERC
%   BAGLAB     String or a label_list_index defining in which label list
%              of A the bag labels are stored. Objects with the same 
%              bag index should have the same bag label. 
%              Default is the current labeling of A
%
% OUTPUT
%   WBAG       Trained bag classifier
%   WOBJ       Trained object classifier
%   D          Classification matrix of bags in B
%
% DESCRIPTION
% This routine offers a classifier for bags (e.g. images) of objects
% (e.g. pixels) stored in a single dataset. The objects in the training 
% set A should have at least two labels: bag labels (the class of their bag)
% and bag indices, defining which objects belong to the same bag. These two
% label sets should be stored by the ADDLABELS command in the dataset A.
% Refer to the multi-labeling system (see MULTI_LABELING) offered by 
% PRTools. The current object labels of A can be the bag labels, but may
% also be different, e.g. true object labels.
%
% BAGINDEX should be a label_list_name or a label_list_index defining the 
% label list used for storing the bag indices that refer to the bag an 
% object belongs to. The same label_list_name or label_list_index should be
% used for defining the bags of the test objects in B.
%
% All objects in A are used to train the object classifier OBJCLASSF if it 
% is untrained. The current object labels are used for that. Classification 
% results of the objects in the same bag are combined by BAGCOMBC, which 
% can be any of the fixed combiners MEANC, PRODC, PERC, MAXC, etcetera.
% This results for every bag in a single confidence vector for the classes. 
%
% If an untrained bag classifier BAGCLASSF is supplied, the bag confidence
% vectors are used to train a bag classifier.
%
% New bags, organised in a dataset like B, with the proper bag indices per
% object stored in a label list with the same name or label_list_index as 
% used in A, can be classified by the bag classifier WBAG. 
%
% If no bag classifier BAGCLASSF was defined during training, just the
% results of the object classifier WOBJ are returned combined by BAGCOMBC
% over the objects in the same bag in B. In this case the final result is
% identical to B*(A*WOBJ)*BAGCC([],BAGCOMBC), provided that A has class
% labels and B is labeled by its bag indices.
%
% SEE ALSO (<a href="http://37steps.com/prtools">PRTools Guide</a>)
% DATASETS, MAPPINGS, MULTI_LABELING, BAGCC, LOSO,
% DATASET/ADDLABELS, DATASET/CHANGELABLIST

% Copyright: R.P.W. Duin, r.p.w.duin@37steps.com
% Faculty EWI, Delft University of Technology
% P.O. Box 5031, 2600 GA Delft, The Netherlands

function [out1,out2] = bagc(varargin)

	argin = shiftargin(varargin,'prmapping');
  argin = setdefaults(argin,[],qdc,2,votec,[],[]);
  if mapping_task(argin,'definition')
    out1 = define_mapping(argin,'untrained');
    out1 = setname(out1,'Set classifier');
  else
    [a,objclassf,bagindex,bagcombc,bagclassf,baglab] = deal(argin{:});
    if isuntrained(objclassf) | nargin > 2 | ~strcmp(getmapping_file(objclassf),mfilename)
      % train the mapping (classifier)

      % we need datasets with at least 1 object per class and 2 classes
      isvaldset(a,1,2);

      % if the object classifier is untrained, train it, else use it
      if isuntrained(objclassf)
        wobj = a*objclassf;
      else
        wobj = objclassf;
      end

      if ismapping(bagclassf) & isuntrained(bagclassf)

        % if the bag labels are not given, 
        % use the objcts labels for the bags too
        if isempty(setlab), setlab = curlablist(a); end

        % classifiy the dataset and change labeling to bag index
        x = changelablist(a*wobj,setindex);

        % avoid empty bags
        x = setlablist(x);

        % combine object results to bag results
        d = bagcc(x,bagcombc);

        % change to bag labels
        d = changelablist(d,baglab);

        % train bag classifier
        bagclassf = d*bagclassf;

        % get outputlabels
        labels_out = getlabels(bagclassf);

      else
        labels_out = getlabels(wobj);
      end

      % store all what is needed for execution in the mapping
      out1 = prmapping(mfilename,'trained',{wobj,bagcombc,bagclassf,bagindex,baglab}, ...
        labels_out, size(a,2),size(labels_out,1));

      % prevent batch execution
      out1 = setbatch(out1,0);

      % return the object classifier as well
      out2 = wobj;

    else % here we are for execution

      % the mapping is stored in objclassf
      w = getdata(objclassf);

      % save current lablist
      curlist = curlablist(a);

      % use the bag index for the test set if supplied
      if ~isempty(w{4}), testset = changelablist(a,w{4}); end

      % classify test set by the object classifier
      d = testset*w{1};

      % avoid empty bags
      d = setlablist(d);

      % combine objects in the same bag
      d = bagcc(d,w{2}); 

      % reset lablist for classification matrix
      d = changelablist(d,curlist);

      % apply the set classifier, if defined
      if ~isempty(w{3}), d = d*w{3}; end

      % that is it, define class labels as feature labels
      out1 = setfeatlab(d,getlabels(objclassf));

    end
    
  end