%MAPPINGS Info on the mapping class construction of PRTools
% 
% This is not a command, just an information file.
% 
% Mappings in PRTools are in the MATLAB language defined as objects of the
% class PRMAPPING. In the text below, the words 'object' and 'class' are used
% in the pattern recognition sense.
%
% In the Pattern Recognition Toolbox PRTools, there are many commands to
% define, train and use mappings between spaces of different (or equal)
% dimensionalities. Mappings operate mainly on datasets, i.e. variables of
% the type DATASET (see also DATASETS) and generate datasets and/or other
% mappings. For example:
%  
%  if    A  is a M x K dataset (M objects in  a K-dimensional space)
%  and   W  is a K x N mapping (a map from K to N dimensions)
%  then A*W is a M x N dataset (M objects in  a N-dimensional space)
%
% This is enabled by overloading the *-operator for the MAPPING variables.
% A*W is executed by PRMAP(A,W) and may also be called as such.
%
% Mappings can be linear (e.g. a rotation) as well as nonlinear (e.g. a
% neural network). Typically they are used to represent classifiers. In that
% case, a K x C mapping maps a K-feature data vector on the output space of
% a C-class classifier (an exception: some 2-class classifiers, like the
% discriminant functions may be implemented by a mapping onto a 1-dimensional 
% space determined by the distance to the discriminant).
% 
% Mappings are of the data-type MAPPING (CLASS(W) is a MAPPING), have a size
% of K x C if they map from K to C dimensions. Four types of mapping are 
% defined:
%
% untrained,  V = A*W.
%
%   Trains the untrained mapping W, resulting in the trained mapping V. W
%   has to be defined by W = PRMAPPING(MAPPING_FILE,{PAR1, PAR2}), in which
%   MAPPING_FILE is the name of the routine that executes the training and
%   PAR1, and PAR2 are two parameters that have to be included into the call
%   to MAPPING_FILE. Consequently, A*W is executed by PRTools as
%   MAPPING_FILE(A,PAR1,PAR2).
%
%   Example: train the 3-NN classifier on the generated data.
%
% 	  W = knnc([],3);         % untrained classifier
% 	  V = gendatd([50 50])*W; % trained classifier
% 	
% trained,  D = B*V	
%
%   Maps the dataset B on the trained mapping or classifier V, e.g. as
%   trained above. The resulting dataset D has as many objects (rows) as A,
%   but its feature size is now C if V is a K x C mapping. Typically, C is
%   the number of classes in the training set A or a reduced number of
%   features determined by the the training of V. V is defined by
%   V = PRMAPPING(MAPPING_FILE,'trained',DATA,LABELS,SIZE_IN,SIZE_OUT),
%   in which the MAPPING_FILE is the name of the routine that executes the
%   mapping, DATA is a field in which the parameters are stored (e.g.
%   weights) for the mapping execution, LABELS are the feature labels to be
%   assigned to the resulting dataset D = B*V (e.g. the class names) and
%   SIZE_IN and SIZE_OUT are the dimensionalities of the input and output
%   spaces. They are used for error checking only. D = B*V is executed by
%   PRTools as MAPPING_FILE(B,W). Example:
%
%     A = gendatd([50 50],10);	% generate random 10D datasets
%     B = gendatd([50 50],10);
%     W = klm([],0.9);          % untrained mapping, Karhunen-Loeve projection
%     V = A*W;                  % trained mapping V
%     D = B*V;                  % the result of the projection of B onto V
%
% fixed,  D = A*W 
%
%   Maps the dataset A by the fixed mapping W, resulting into a transformed
%   dataset D. Examples are scaling and normalization, e.g. W =
%   PRMAPPING('SIGM','fixed',S) defines a fixed mapping by the sigmoid function 
%   SIGM a scaling parameter S. A*W is executed by PRTools as SIGM(A,S). 
%
%   Example: normalize the distances of all objects in A such that their 
%   city block distances to the origin are one.
%
%     A = gendatb([50 50]);
%     W = normm;
% 	  D = A*W;
%
% combiner,  U = V*W 
%
%   Combines two mappings. The mapping W is able to combine itself with V
%   and produces a single mapping U. A combiner is defined by
%   W = PRMAPPING(MAPPING_FILE,'combiner',{PAR1,PAR2})
%   in which MAPPING_FILE is the name of the routine that executes the
%   combining and PAR1, and PAR2 are the parameters that have to be included
%   into the call to the MAPPING_FILE. Consequently, V*W is executed by
%   PRTools as MAPPING_FILE(V,PAR1,PAR2). In a call as D = A*V*W, first B =
%   A*V is resolved and may result in a dataset B. Consequently, W should be
%   able to handle datasets, and MAPPING_FILE is now called by
%   MAPPING_FILE(B,PAR1,PAR2) Remark: the combiner construction is not
%   necessary, since PRTools stores U = V*W as a SEQUENTIAL mapping (see
%   below) if W is not a combiner. The construction of combiners, however,
%   may increase the transparency for the user and efficiency in
%   computations. Example:
%
%     A = gendatd([50 50],10); % generate random 10D datasets
%     B = gendatd([50 50],10);
%     V = klm([],0.9);         % untrained Karhunen-Loeve (KL) projection
%     W = ldc;                 % untrained linear classifier LDC
%     U = V*W;                 % untrained combiner
%     T = A*U;                 % trained combiner
%     D = B*T;                 % apply the combiner (first KL projection, 
%                              %       then LDC) to B
%
% Differences between the four types of mappings are now summarized for
% a dataset A and a mapping W:
% A*W	  	-  untrained : results in a mapping
% 	  		-  trained   : results in a dataset, size checking
% 		  	-  fixed     : results in a dataset, no size checking
% 			  -  combiner  : treated as fixed      
%
% Suppose V is a fixed mapping, then for the various possibilities of
% the mapping W, the following holds:
% A*(V*W) -  untrained : evaluated as V*(A*V*W), resulting in a mapping
%         -  trained   : evaluated as A*V*W, resulting in a dataset
%         -  fixed     : evaluated as A*V*W, resulting in a dataset
%         -  combiner  : evaluated as A*(V*W), resulting in a dataset
%         
% Suppose V is an untrained mapping, then for the various possibilities of
% the mapping W holds:
% A*(V*W) -  untrained : evaluated as A*V*(A*(A*V)*W), resulting in a mapping
%         -  trained   : evaluated as A*V*W, resulting in a mapping
%         -  fixed     : evaluated as A*V*W, resulting in a mapping
%         -  combiner  : evaluated as A*(V*W), resulting in a mapping     
%
% Suppose V is a trained mapping, then for the various possibilities of
% the mapping W holds:
% A*(V*W) -  untrained : evaluated as V*(A*V*W), resulting in a mapping
%         -  trained   : evaluated as A*V*W, resulting in a dataset
%         -  fixed     : evaluated as A*V*W, resulting in a dataset
%         -  combiner  : evaluated as A*(V*W), resulting in a dataset
%
% The data fields stored in the MAPPING W = A*QDC can be found by
%
% 	STRUCT(W)
%
% which may display:
%
% 	MAPPING_FILE: 'normal_map'
% 	MAPPING_TYPE: 'trained'
%   DATA:          [1x1 struct]
%   LABELS:        [2x1 double]
%   SIZE_IN:       2
%   SIZE_OUT:      2
%   SCALE:         1
%   COST:          []
%   OUT_CONV:      0
%   NAME:          []
%   USER:          []
%   VERSION:       {1x2 cell  }
%
% These fields have the following meaning:
% MAPPING_FILE: Name of the m-file that executes the mapping.
% MAPPING_TYPE: Type of mapping: 'untrained','trained','fixed' or 'combiner'.
% DATA:         Parameters or data for handling or executing the mapping.
% LABELS:       Label list used as FEATLAB for labeling the features of the
%               output PRDATASET.
% SIZE_IN:      Expected input dimensionality of the data to be mapped.
%               If not set, it is neglected, otherwise it is used for the error
%               checking and display of the mapping size on the command line.
% SIZE_OUT:     Dimensionality of the output space. It should correspond to the
%               size of LABLIST. SIZE_OUT may be size vector, e.g. describing
%               the size of an image. See also the FEATSIZE field of PRDATASET.
% SCALE:        Output multiplication factor. If SCALE is a scalar all
%               multiplied by it. SCALE may also be a vector with size as
%               defined by SIZE_OUT to set separate scalings for each output.
% COST:         Classification costs in case the mapping defines a classifier.
% OUT_CONV:     Defines for trained and fixed mappings the output conversion:
%               - 0 : no conversion (to be used for mappings that output 
%               confidences or densities;
%               - 1 : sigmoid (for discriminants that output distances);
%               - 2 : normalisation (for converting densities and confidences
%               into posterior probability estimates;
%               - 3 : for performing sigmoid as well as normalisation.
% NAME:         Name of the mapping, used for informing the user on the 
%               command line, as well as for annotating plots.
% USER:         User field, not used by PRTools.
% VERSION:      Some information related to the version of PRTools used for
%               the mapping definition.
%
%
% The fields can be set by commands like SETMAPPING_FILE, SETDATA, SETLABELS, 
% SETSIZE, and may be retrieved by commands like GETMAPPING_FILE, GETDATA,
% GETLABELS and SETSIZE. Information stored in a mapping can be found
% as follows:
% - By DOUBLE(W) and by +W the content of the W.DATA is returned.
% - DISPLAY(W) writes the size of the mapping, the number of classes and the
% label type on the terminal screen.
% - SIZE(W) returns dimensionalities of input space and output space.
% - SCATTERD(A) makes a scatter-plot of a dataset.
% - SHOW(W) may be used to display images that are stored in mappings with 
% the MAPPING_FILE 'affine'. 
% - Using the dot extension as for structures, e.g. NAME = W.NAME;
% - The routines ISAFFINE, ISCLASSIFIER, ISCOMBINER, ISEMPTY, ISFIXED, 
% ISTRAINED and ISUNTRAINED test on some mapping types and states.
%
% Some standard MATLAB operations have been overloaded for variables of the 
% type PRMAPPING. They are defined as follows:
% W'      Defined for affine mappings only. It returns a transposed mapping.
% [W,V] 	Builds a combined classifier (see STACKED) operating in the same
%         feature space. A * [W V] = [A*W A*V].
% [W;V] 	Builds a combined classifier (see PARALLEL) operating in different
%         feature spaces: [A B] * [W;V] = [A*W B*V]. W and V should be 
%         mappings that correspond to the feature sizes of A and B.
% A*W     Maps a DATASET A by the MAPPING W. This is executed by PRMAP(A,W).
% V*W     Combines the mappings V and W sequentially. This is executed by
%         SEQUENTIAL(V,W).
% W+CON   Adding a constant is defined for affine mappings only. 
% W(:,K)	Output selection. If W is a trained mapping, just the features 
% 		    listed in K are returned.
%
%
% SEE ALSO (<a href="http://37steps.com/prtools">PRTools Guide</a>)
% PRMAPPING, CLASSC, CNORMC, LABELD, 
%
% - Classifiers
%   NMC, KNNC, UDC, LDC, QDC, MOGC, QUADRC, FISHERC, PARZENC, PARZENDC,
%   TREEC, LOGLC, NAIVEBC, SVC, RBSVC, NUSVC, LIBSVC, TREEC, PERLC, BPXNC, 
%   RBNC, LMNC, WEAKC, STUMPC, SUBSC, ADABOOSTC, BAGGINGC, FDSC, VPC, DRBMC
%
% - Classifier Combiners
%   STACKED, PARALLEL, SEQUENTIAL, MEANC, AVERAGEC, PRODC, MEDIANC, MINC,
%   MAXC, VOTEC, WVOTEC, MODSELC, DCSC, RSSCC, MLRC, NAIVEBCC, TRAINCC
%
% - Density Estimation
%   GAUSSM, PARZENM, KNNM, 
%   
% - Dimension Reduction
%   FEATSEL, FEATSELB, FEATSELF, FEATSELI, FEATSELLR, FEATSELM, FEATSELO, 
%   FEATSELP, FEATSELV, BHATM, FISHERM, CHERNOFFM, KLM, KLMS, NLFISHERM,
%   PCAM, REDUCM
%
% - Scaling
%   SCALEM, CMAPM, SIGM, INVSIGM, NORMM
% 
% - Set commands
%   SETBATCH, SETCOST, SETDATA, SETLABELS, SETMAPPING_FILE,SETMAPPING_TYPE,
%   SETNAME, SETOUT_CONV, SETPOSTPROC, SETSCALE, SETSIZE, SETSIZE_IN,
%   SETSIZE_OUT, SETUSER
%
% - Get commands
%   GETBATCH, GETCOST, GETDATA, GETLABELS, GETMAPPING_FILE,, GETMAPPING_TYPE,
%   GETNAME, GETOUT_CONV, GETSCALE, GETSIZE, GETSIZE_IN, GETSIZE_OUT, GETUSER
% 
% - Tests
%   ISAFFINE, ISCLASSIFIER, ISEMPTY, ISPARALLEL, ISSTACKED, ISSEQUENTIAL,
%   ISTRAINED, ISUNTRAINED, ISFIXED, ISCOMBINER, 

% 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