%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