%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 MAPPING. 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 an 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 an 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 MAP(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 = MAPPING(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 THE 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 = MAPPING(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 =%   MAPPING('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 = MAPPING(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 DATASET.% 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 DATASET.% 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 in the following ways:% 1. At the end of the MAPPING construction command by a set of% 	 {fieldname, value pairs}, e.g.% 	 W = MAPPING('affine','trained',DATA,LABELS,5,2,'NAME','PCA Mapping')% 2. For a given mapping W fields may be changed similarly by the SET command:% 	 W = SET(W,'NAME','PCA Mapping');% 3. By the commands SETMAPPING_FILE, SETMAPPING_TYPE, SETDATA, SETLABELS, % 	 SETSIZE, SETSIZE_IN, SETSIZE_OUT, SETSCALE, SETOUT_CONV, SETNAME and % 	 SETUSER.% 4. Using the dot extension as for structures, e.g. % 	 A.NAME = 'PCA MAPPING'%% The information stored in a mapping can be retrieved as follows:% 1. 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'. % 2. By the GET command, e.g: [name,user] = GET(W,'NAME','USER');% 3. By the commands GETMAPPING_FILE, GETMAPPING_TYPE, GETDATA, GETLABELS, % 	 SIZE, GETSIZE, GETSIZE_IN, GETSIZE_OUT, GETSCALE, GETCOST, GETOUT_CONV,%    GETNAME and GETUSER.% 4. Using the dot extension as for structures, e.g. NAME = W.NAME;% 5. 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 MAPPING. 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 MAP(A,W).%   V*W     Combines the mappings V and W sequentially. This is executed by% 			  	SEQUENTIAL(V,W).%   W+c 		Defined for affine mappings only. %   W(:,K)	Output selection. If W is a trained mapping, just the features % 		  		listed in K are returned.% Copyright: R.P.W. Duin, duin@ph.tn.tudelft.nl% Faculty of Applied Sciences, Delft University of Technology% P.O. Box 5046, 2600 GA Delft, The Netherlands