Programming fixed mappings

Programming fixed mappings

A user supplied fixed mapping routine called mymapping may be called in one of the following ways:

    % mapping definition
    mymapping_def = mymapping([],parameters);

    % mapping definition with default parameters
    mymapping_def = mymapping

    % call as user would make it
    mydataset_out = mymapping(mydataset_in,parameters)

    % the way PRTools calls it
    mydataset_out = mymapping(mydataset_in,getdata(mymapping_def))

In these calls mydataset should be a proper PRTools dataset. The third line is what the user intuitively wants and the routine should be able to handle it. The fourth line is the way PRTools may call the routine using a previously supplied definition as in the first two lines. mymapping_def should be a proper PRTools mapping. The second line is just a shortcut of the first in case default parameters are used. By these calls the (default) parameters are stored in the data-field of mymapping_def.

Once a mapping is defined as described above it may be applied as

    mydataset_out = mydataset_in * mymapping_def

which is evaluated internally by PRTools using the routine map as

    mydataset_out = map(mydataset_in,mymapping_def)

which finally calls the user routine as defined above in the fourth line. So additional parameters can only be retrieved by a call like

    [mydataset_out,more_outputs] = mymapping(mydataset_in,parameters)

Here is the skeleton of a routine that users may use to program their own fixed mapping. It is based on a more advanced setup than followed by many of the existing, older PRTools routines.

%MYFIXEDMAPPING Skeleton for a user supplied mapping
%
%   W = MYFIXEDMAPPING([],PAR)
%   W = MYFIXEDMAPPING
%   B = A*MYFIXEDMAPPING
%   B = A*MYFIXEDMAPPING([],PAR)
%   B = MYFIXEDMAPPING(A,PAR)
%
% INPUT
%   A     Dataset
%   PAR   Parameter
%
% OUTPUT
%   W     Mapping definition
%   B     Dataset A mapped by MYFIXEDMAPPING
%
% DESCRIPTION
% This is an example routine just offering the skeleton of a user supplied
% fixed mapping. By changing the lines indicated in the source by %% and
% by renaming the routine users may create their own mapping. The routine
% as it is just selects the features (columns of A) as defined in PAR.
%
% SEE ALSO
% DATASETS, MAPPINGS, MYTRAINABLEMAPPING

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

function OUT = myfixedmapping(varargin)

% define here the default values for all parameters. Defaults might be
% empty ([]), but the routine should test on that if the parameter
% is actually used. Here we will use as a default PAR = 1
argin = setdefaults(varargin,[],1);

% determine the type (task) of the call
if mapping_task(argin,'definition')
  % we are here if the routine is called by W = myfixedmapping, or by
  % W = myfixedmapping([],PAR)
  % define the name of the mapping (just used for annotation).
  name = 'Fixed Mapping Skeleton';
  % define the mapping
  OUT = define_mapping(argin,'fixed','Fixed Mapping Skeleton');

else
  % now we have a normal call like OUT = myfixedmapping(A,[2 5]), or
  % OUT = A*myfixedmapping([],[2 5]) which is converted as such.

  % Retrieve the input parameters from argin
  % For readability, this should correspond to the description the help
  % block of this function
  [A,PAR] = deal(argin{:});                                             %%

  % Inputs may need checking
  isdataset(A); % returns an error if A is not a dataset                %%
  % checking parameter values depends on the mapping we want to
  % implement. In our fake example it should be in the range of feature
  % numbers.
  if any(PAR < 1) | any(PAR > size(A,2))                                %%
  % Features to be selected should be in a proper range                 %%
    error('Feature number out of range')                                %%
  end                                                                   %%

  % Next the mapping itself should be programmed. We can simply put
  % OUT = A(:,PAR);
  % but sometimes operations on the data stored in the dataset are needed
  % that cannot be done within PRTools. The following serves as an
  % example on how this might be done.
  data = getdata(A);  % isolate the data from the dataset               %%
  data = data(:,PAR); % do whatever is needed.                          %%
  OUT = setdata(A,data);                                                %%
  % This resubstitute the resulting data into the original data structure
  % of A. The resulting dataset has thereby the same name, user- and
  % ident-fields as the input dataset.

end
return

Programming fixed mappings