====== Classifier functions ======
===== getInstances =====

**usage**: rois = getInstances(v,rois,stimvol)\\
**purpose**: compute instances by taking mean after stimulus occurrences\\


^ argument ^ value ^
| v | view variable |
| rois | rois returned by loadROITSeries |

^ Optional arguments ^ value ^
| startLag | Lag (in volumes) from stimulus occurrence from which to start computing mean responses (defaults to 3 seconds |
| blockLen | Length of block of data over which to average data to created instances. Defaults to using block length found by parsing stim files |
| n | Number of voxels to use in each ROI (in sort order dependent on getSortIndex output (defaults to 100) |
| minResponseLen | Throw out any instances in which less than this number of volumes was collected (for example at the end of a run). Defaults to half the blockLen |
| fieldName | The field name in the ROI to return the instances in. This can be set so that you can create multiple instances, for example, one set of instances for the left visual field and one set of instances for the right visual field. (default is classify) |

N.B. This routine returns slightly different instances from the ones returned by svmclassify. One big difference is that svmclassify subtracts out the block mean (in getInstances, we don't do that and assume that the filtering takes care of this for us). svmclassify may also require that all instance types have the same number of repeats - I didn't check that carefully, but it seems to be the case since it returns fewer numbers of instances than getInstances.

===== getSortIndex =====
**usage**: <code>rois = getSortIndex(v,rois,r2)
rois = getSortIndex(v,rois,r2Left,r2Right)
</code>
**purpose**: adds a sort index to the rois based on the r2 values passed in. If two r2 matrices are passed in then this is a split design with different sort values for ROIs that start with 'l' or start with 'r' the first r2 matrix will be used for ROIs that start with 'l' and the second will be used for ROIs that start with 'r'. The r2 matrices are of the dimensions of the scan.

^ argument ^ value ^
| v | view variable |
| rois | rois returned by loadROITSeries |
| r2 | map of r2 values should have dimesnions of the scan |
| r2Left / r2Right | Optionally two r2 maps, one for rois on the left and one for rois that are on the right |
===== leaveOneOut =====
**usage**: leaveOneOut(instances)\\
**purpose**: Do leaveOneOut cross-validated classification on the passed in instances. Instances is a cell array which has a kxn matrix for each class, where k = number of repetitions and n = number of dimensions (e.g. num voxels).

^ argument ^ value ^
| instances | instances as returned by getInstances |
 
Can also be called on ROIS that have instances computed.

<code>
rois = getInstances(v,rois,stimvol);
rois = leaveOneOut(rois);
</code>

Return structure (rois.classify.leaveOneOut) contains the following fields

^ return field ^ value ^
| type | Type of classifier ('Fisher','svm','mahalanobis')|
| classifierParams | Parameters used by classification algorithm |
| whichClass | Cell array that assigns a class to each instance |
| classifierOut | The output of the classifier for each instnace |
| confusionMatrix | The confusion matrix. A matrix that is classification type vs real type. Each element of the matrix reports the fraction of test instances predicted as a "classification type (col)" for a real type (row) across the leave-one-out train-tests. Values along the diagonal indicate accurate classification. e.g., an identity matrix for perfect classification|
| correct | Percent correct |
| correctSTE | Standard error of percent correct over leave one outs |

===== buildClassifier =====
**usage**: classifier = buildClassifier(instances,varargin)\\
**purpose**: Creates a classifier for later classification. 

^ arguments ^ value ^
| instances | Instances can be those returned from getInstances. It is a cell array for each category there is a cell with an nxk matrix in which n is the number of repeats and k is the number of dimensions (e.g. voxels). |

^ optional arguments ^ value ^
| type | Classifier type. Can be any one of 'fisher', 'svm' or 'mahalanobis' |
| kernelfun,C | For svm classification, see getsvm |

    
===== classifyInstances =====


**usage**: [class classifierOut] = classifyInstance(classifier,instance)\\
**purpose**: classify a novel instance using the classifier returned by buildClassifier.

^ argument ^ value ^
| classifier | Classifier is the structure returned by buildClassifier. |
| instance | A 1xk array which has k dimensions (e.g. num voxels) |
 
**Description** : perform multi-class classification as in Kamitani and Tong paper. A classifier is trained for each pair of classes. A given classifier projects each test instance
on the hyperplane orthogonal to the classifier's decision boundary. For each test instance, a pair of class is thus associated with a projection value. To get an idea of which class
the test instance is more likely to belong to, one can sum the projection values of all pairs of class that include the class. the test instance belongs to the class with the highest
sum of projection value. Note that this is an ad hoc and not analytically proven solution. (steeve: I wrote that and that seriously needs rewriting !)

===== computeCombinedCorrect =====

**usage**: combined = computeCombinedCorrect(v,rois,stimvol1,stimvol2,<startLag>,<blockLen>)\\
**purpose**: Computes the combined correct across hemispheres for l/r split designs.

^ input argument ^ value ^
| v | view variable |
| rois | rois returned by loadROITSeries |
| stimvol1 | cell array of stimulus occurrence volumes, returned by getStimvol. These should be valid for one hemisphere |
| stimvol2 | cell array of stimulus occurrence volumes, returned by getStimvol. These should be valid for the other hemisphere |
| startLag | Lag (in volumes) from stimulus occurrence from which to start computing mean responses (defaults to 3 seconds |
| blockLen | Length of block of data over which to average data to created instances |

===== displayCombinedCorrect =====

**usage**: displayCombinedCorrect(v,combined,<combinedTitle>,saveEPS)\\
**purpose**: Computes the combined correct across hemispheres for l/r split designs.

^ input argument ^ vale ^
| v | view variable |
| combined | return argument from computeCombinedCorrect |
| combinedTitle | A string that can be used as a title |
| saveEPS | Set to 1 to save an eps image (default = 0 |
===== getClassifierWeightMap =====  
**usage**: [weightMaps weightMapNames] = getClassifierWeightMap(v,rois,stimvol);\\
**purpose**:  returns classifier weight maps that can be installed in MLR with mrDispOverlay

^ input argument ^ value ^
| v | view variable |
| rois | rois returned by loadROITSeries |
| stimvol | cell array of stimulus occurrence volumes, returned by getStimvol |

^ output argument ^ value ^
| weightMaps | Cell array of weight overlay maps |
| weightMapNames | Cell array of strings describing weight maps |

<code>
mrQuit;
v = newView;
rois = loadROITSeries(v,{'l_mt','r_mt'});
stimvol = getStimvol(v,'localdir');
[weightMaps weightMapNames] = getClassifierWeightMap(v,rois,stimvol);
v = loadAnat(v,'jg_left_occipital.hdr');
mrDispOverlay(weightMaps,rois{1}.scanNum,rois{1}.groupNum,v,weightMapNames,'colormapType','normal','cmap',splitcmap,'range=[-1 1]','clip=[-1 1]');
overlay = refreshMLRDisplay(viewGet(v,'viewNum'));
</code>
===== stackROIs =====  
**usage**: rois = stackROIs(rois1,rois2,varargin)\\
**purpose**: Stack two sets of ROIs. This will stack either the instances or the timecourses themselves dependent on the type.

^ argument ^ value ^
| rois1 | First set of ROIs returned by loadROITSeries |
| rois2 | Second set of ROIs returned by loadROITSeries |

^ optional arguments ^ value ^
| type | Set to 'stackInstances' to stack instances rather than timecourses. Default is 'stackTimecourse' |
| fieldName | An optional argument used when you stack instances. You can set the field name from where to grab the instances. Defaults to 'classify' |

===== checkMatchingVar =====  
**usage**: tf = checkMatchingVar(v,varname,scanNums,<'groupName=?'>,<'taskNum=?'>,<phaseNum=?'>,<'segmentNum=?'>)\\
**purpose**: Check that the variable varname had the same values in all scans listed in scanNums. This can be used if, for example, you have run your stimulus program with the same random seed and you want to make sure that the event times were the same.

^ argument ^ value ^
| v | view |
| varname | Name of variable to test |
| scanNums | Scan nums over which to test |

^ optional arguments ^ value ^
| groupName | Name of group to use, defaults to current group |
| taskNum | taskNum to grab variable from. Defaults to [] |
| phaseNum | phaseNum to grab variables from. Defaults to [] |
| segmentNum | segmentNum to grab volume number from. Defaults to [] |

===== preprocessInstances =====

Can do 

  *z-scoring
  *pca


Need to fill this function section up ..

===== getsvm =====

can do classification with 

  *Fisher
  *svm


get solution via optimization toolbox (quadratic programming solver)
Need to fill this function section up ..