%>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
%
% README FILE FOR SRD SCRIPTS
%
%>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
%
% Note fusion of rows down columns, as described in Peter Willett, 
% Combination of Similarity Rankings Using Data Fusion
% J. Chem. Inf. Model. 2013, 53, 1-10, are always performed. Fusion processes are
% sum, min, max, median, l2 norm, and std. For each fusion process,
% there are four outputs. Two are when the rows of A are ranked from 1:ncol
% and the other two work with the raw values in A as entered in the
% function statement. For the two outputs with A ranked, one is the
% resultant fusion process (*Fusion) and the other is where the resultant fusion
% process has been re-ranked from 1:ncol (*Rank). The same is true for fusion of the
% the raw A.


%--------------------------------------------------------------------------
% srdPack.m
%--------------------------------------------------------------------------
% PURPOSE:
% Packages input arguments into two data structs: data and options.
%
% INPUT:
% [1] A: Input matrices. 
%     The variable A is a p x 1 cell array where each component 
%     corresponds to an input matrix where each row correspond to a 
%     sample and each column corrresponds to a metaparameter such as 
%     latent dimension, lambda value, etc.   
% 
% [2] T: Target information.
%     The input format for the variable T can be different:  
%     a) T is cell array of numeric values (target vector values) or strings
%        (e.g., {'min','max'})
%     b) T is a string, e.g., T='min'.  In this, T will be made into a 
%        cell array, i.e., T=repmat( {T}, p, 1);
% 
% [3] cv
%     String variable indicating the type of cross validation (CV) type:
%     a) 'none': No CV is performed
%     b) 'classic': This corresponds to classic N-fold CV.  The samples in 
%        each input matrix A{i} is grouped into N sets of sample ids.  
%        Samples having the same id number belong to the same withheld 
%        fold.  The withheld samples are set aside and the remaining 
%        samples are used to create the SRDs.
%     c) 'lmo': Leave-multiple-out CV.  A percentage of samples in each 
%        input matrix A{i} are set aside and the remaining samples are 
%        used to construct the SRDs.
% 
% [4] exact: 
%     true or false
%     a) If true, then the exact SRD distribution will be computed.  
%        This is applicable is the number of samples are 10 or less.  
%        If the number of samples are greater than 10, then exact will 
%        be set to false.
%     b) If false, then the normal approximation to the SRD distribuition 
%        will be used.
%
% [5] niter: 
%     Positive integer
%     a) If cv='classic', then niter corresponds to the number of folds.
%     b) If cv='lmo', then niter corresponds to the number of iterations, 
%        i.e., how many times LMOCV is performed.
%     Not applicable to cv='none' case.
%
% [6] percent:
%     Number between 0 and 100.  This is applicable only to the 
%     cv='lmo' case.  This variable specifies the percentage of samples 
%     in the input matrix A{i} that are the kept.
% 
% [7] allmix:
%     true or false.  
%     This is applicable only to the cv='lmo' case.  
%     a) If true, then the sample indices used for each input matrix 
%        (specifying which samples are to be kept) will be the different, 
%        i.e., mixed.
%     b) If false, then the sample indices used used for each input 
%        matrix will be the same.  This only applicable if the number of 
%        samples for the input matrices are the same.
%
%
% OUTPUT
% [1] data:
%     This is a struct containing two fields: A and T.
%     > A: Single matrix that has been collated from the individual
%       input matrices A{i}, i.r., A = cell2mat(A).
%     > T: Target vector that has been collated from individual target
%       information T{i}.  See srdPack.m for details of the collating.
%     Below is an example for k=1 in srdDemo(k):
%     >> disp(data)
%      A: [100x60 double]
%      T: [100x1 double]
% [2] options:
%     This is a struct containing the option and "knob" settings for the 
%     SRD suite of scripts.  Below is an example for k=1 in srdDemo(k):     
%     >> disp(options)
%         nblock: 1
%        nsample: 100
%          exact: 0
%             cv: 'none'
%          niter: 'none'
%        percent: 50
%         allmix: 1
%     fusionRule: {'sum'  'min'  'max'  'med'  'l2'  'std'}
%     targetRule: {'min'}
%
% [3] srd: results struct consisting of the following fields where N =1 if
% no cross validation (CV), otherwise N =  number of splits of A for the
% CV
%     .raw:      N x ncol matrix of raw SRD values
%     .norm:     N x ncol matrix of normalized SRD values
%     .srdRank:     N x ncol matrix of rankings (1:ncol) associated with srd.raw
%     .x:        N x p matrix of raw SRD values corresponding to the 
%                x-coordinates of the probability density function (PDF) 
%                curves in Figure 1
%     .relFreq:  N x p matrix of PDF values corresponding to the 
%                y-coordinates PDF curves in Figure 1
%     .prob:     N x ncol matrix of probabilities associated with srd.raw
%     .max:      N x 1 vector, e.g. srd.max(i) is the largest SRD values 
%                possible for the ith fold.
%     .nrow:     N x 1 vector, e.g. srd.nrow(i) is the number of rows used
%                in the ith fold.
%     .display:  srd.display is a struct containing four fields.
%                .x: x-axis of Figure 1
%                .relFreq: y-axis of Figure 1
%                .norm: x-axis of Figure 2
%                .prob: y-axis of Figure 2
%     .data:     struct returned by srdPreProcess.m
%
%     .sumFusion: N x ncol matrix of sum of rankings in each col of A
%                 where each row of A has been ranked 1:ncol
%     .sumRank:   N x ncol matrix of rankings of sumFusion 
%                 where each row of sumFusion has been ranked 1:ncol 
%     .sumRawFusion: N x ncol matrix of sum of raw values in each col of A
%     .sumRawRank: N x ncol matrix of rankings of sumRawFusion 
%                  where each row of sumRawFusion has been ranked 1:ncol 
%     .minFusion: N x ncol matrix of min ranking in each col of A
%                 where each row of A has been ranked 1:ncol
%     .minRank: N x ncol matrix of rankings of minFusion
%               where each row of minFusion has been ranked 1:ncol 
%     .minRawFusion: N x ncol matrix of min raw value in each col of A
%     .minRawRank: N x ncol matrix of rankings of minRawFusion
%                  where each row of minRawFusion has been ranked 1:ncol 
%     .maxFusion: N x ncol matrix of max ranking in each col of A
%                 where each row of A has been ranked 1:ncol
%     .maxRank: N x ncol matrix of rankings of maxFusion
%               where each row of maxFusion has been ranked 1:ncol 
%     .maxRawFusion: N x ncol matrix of max raw value in each col of A
%     .maxRawRank: N x ncol matrix of rankings of maxRawFusion
%                  where each row of maxRawFusion has been ranked 1:ncol 
%     .medFusion: N x ncol matrix of median ranking in each col of A
%                 where each row of A has been ranked 1:ncol
%     .medRank: N x ncol matrix of rankings of medFusion
%               where each row of medFusion has been ranked 1:ncol 
%     .medRawFusion: N x ncol matrix of median raw value in each col of A
%     .medRawRank: N x ncol matrix of rankings of medRawFusion
%                  where each row of medRawFusion has been ranked 1:ncol 
%     .l2Fusion: N x ncol matrix of Euclidean vector length of rankings 
%                in each col of A where each row of A has been 
%                ranked 1:ncol
%     .l2Rank: N x ncol matrix of rankings of l2Fusion
%              where each row of l2Fusion has been ranked 1:ncol 
%     .l2RawFusion: N x ncol matrix of Euclidean vector length of raw 
%                   values in each col of A
%     .l2RawRank: N x ncol matrix of rankings of l2RawFusion
%                 where each row of l2RawFusion has been ranked 1:ncol 
%     .stdFusion: N x ncol matrix of the std dev of rankings 
%                in each col of A where each row of A has been 
%                ranked 1:ncol
%     .stdRank: N x ncol matrix of rankings of stdFusion
%              where each row of stdFusion has been ranked 1:ncol 
%     .stdRawFusion: N x ncol matrix of th std dev of raw 
%                   values in each col of A
%     .stdRawRank: N x ncol matrix of rankings of stdRawFusion
%                 where each row of stdRawFusion has been ranked 1:ncol 


% 
%--------------------------------------------------------------------------
% srdMaster.m
%--------------------------------------------------------------------------
% PURPOSE:
% Compute the SRDs and fusion rankings, conditional on the type of cross
% validation type is chosen.  This output is then subsequently repackaged
% from a array of structs into one struct.
% 
% USAGE: 
% > srd = srdMaster(data, options)

