***** INFORMATION *****

Hippo-ATESC is (partially) presented in these published papers:

R. Ugolotti, P. Mesejo, S. Cagnoni, M. Giacobini, F. Di Cunto, "Automatic hippocampus localization in histological images using PSO-based deformable models" in Proceedings of the 13th annual conference companion on Genetic and evolutionary computation (Companion), Pag: 487-494, 2011

P. Mesejo, R. Ugolotti, F. Di Cunto, S. Cagnoni, M. Giacobini, "Automatic Segmentation of Hippocampus in Histological Images of Mouse Brains using Deformable Models and Random Forest" in Proceedings of the 25th IEEE International Symposium on Computer-Based Medical System, 2012

P. Mesejo, R. Ugolotti, F. Di Cunto, M. Giacobini, S. Cagnoni, "Automatic Hippocampus Localization in Histological Images using Differential Evolution-Based Deformable Models" in Pattern Recognition Letters, Vol: 34, Pag: 299–307, 2012

***** HOW TO RUN THE CODE *****

The easiest way to use Hippo-ATESC is to run 'runEntireExperiment.m' in the main folder. It runs the entire system for all genes in a user-defined training set, then extract the most significant features using a genetic algorithm, and finally it uses these information to rank all genes in the test set.

The user must set OUTPUT_FOLDER and the name of EXPERIMENT. Inside the folder localized by OUTPUT_FOLDER he needs to put three files:
EXPERIMENT.train contains the training set (for each gene, name and serie number in the ABA)
EXPERIMENT.test contains the test set (for each gene, name and serie number in the ABA)
EXPERIMENT.labels contains the labels of the training set (1 for your positive examples, any other number for the negative class)
See the examples given in the Experiments folder to see file format

The system automatically creates two folders: test and train. You can retrieve your results in OUTPUT_FOLDER/EXPERIMENT/test. Mostly, you should be interested in features.txt (which contains, for every gene in your test set, the values of all selected features) and rank.csv (euclidean distance and pearson correlation for every gene compared to the prototype vector). In OUTPUT_FOLDER/EXPERIMENT/train/ranking_variables.mat you can find useful information obtained by the genetic feature selection, like the selected features and the created prototype.

***** IMPORTANT VARIABLES *****

To take full advantage of the code, the user may set some variables (please note, usually default values are good enough).

In runEntireExperiment.m: as explained before, set OUTPUT_FOLDER and EXPERIMENT variables. Moreover, GFST_DIR must link to the folder containing the code of the GeneticFeatureSelectionToolbox. DELETE_FOLDERS is used to completely remove an experiment (including your previous results, so be careful!). To be sure about the complete removal of the folders, close and re-open Matlab.

In runExperiment:

USE_ALREADY_DOWNLOADED: if true, the tool will firstly look for already downloaded brain images before downloading them. Otherwise, it will ignore them and download all of them.
BIN_FOLDER: this is the path containing the LocalizationAndFeatureExtraction toolbox.

***** HOW THE CODE IS STRUCTURED *****

Look in the readme inside the folders (and comments at the beginning of each file, where provided) for deeper descriptions. 

- main: contains scripts to run batch experiments
- LocalizationAndFeatureExtraction: main function is getHippocampus, provided a brain image, localize the hippocampus, extract the features and rank the gene
- GeneticFeatureSelectionToolbox: main function is mainFeatureExtraction, provided a training set (and correspondent labels), returns the variables needed for ranking in a .mat file

The code has been developed and tested on Windows 7 64bit, OpenCv 2.2 and 2.3.1, Matlab 2009a. C++ files were compiled using Visual Studio 2008.

***** EXTERNAL MATLAB PACKAGES USED *****

PSO implementation is based on Particle Swarm Optimization Toolbox by Brain Birge (http://www.mathworks.com/matlabcentral/fileexchange/7506-particle-swarm-optimization-toolbox)
DE implementation is based on the work by Rainer Storn, Ken Price, Arnold Neumaier, Jim Van Zandt (http://www1.icsi.berkeley.edu/~storn/code.html)
Implementation of Affine Registration is based on "B-spline Grid, Image and Point based Registration" by Dirk-Jan Kroon (http://www.mathworks.com/matlabcentral/fileexchange/20057)
Random Forest Implementation has been downloaded from http://code.google.com/p/randomforest-matlab/ and the author is Abhishek Jaiantilal

***** EXTERNAL FILES, MEX FILES, OPENCV, COMPATIBILITY *****

To run this code is important to take into account the following particularities/characteristics:

- optimization of the reading of the images with OpenCV 2.X. To compile with mex the cvReadImage.cpp file:
mex cvReadImage.cpp -I"OPENCVFOLDER\include" -I"OPENCVFOLDER\include\opencv" -L"OPENCVFOLDER\lib" -lopencv_core2XX -lopencv_highgui2XX 
where OPENCVFOLDER is the folder containing your installation of OpenCV (tested with OpenCV 2.2 and 2.3.1).

- optimization of the median filtering during segmentation with C (mex fast_medfilt.cpp ctmf.c)
This implementation was extracted from "Median Filtering in Constant Time" (Perreault, S. and Hebert, P.; IEEE Transactions on Image Processing, 2007)

- optimization of the calculation of the target function with C (mex evaluate_model.cpp). 

- The executable Extract_External_Contours.exe is compiled with OpenCV 2.3.1 (also tested with OpenCV 1.1). 
This file, Extract_External_Contours.exe, only works properly with big images (with the original size). For using it: 
Extract_External_Contour.exe images\reference\reference50.jpg images\reference_cont\reference50_cont (reference50_cont is saved with png format). If a third input parameter is included this will be used as a filename for the output: 
Extract_External_Contour.exe (program) 
images/source/A030009H04Rik_117.jpg (original image in high resolution) 
images/elab_cont/A030009H04Rik_117_cont (output resized binarized image) 
images/elab/A030009H04Rik_117 (output original image resized in gray scale)

- All these compiled files (exe and mex) have to be located in the LocalizationAndFeatureExtraction folder if the user do not want to add paths or change the environment variables.

- In .\images\reference_cont are the external contours of the reference brains. They have to be there, the system doesn't binarize it automatically. If you want to try with the reference 40 and is not there, that will provoke an error.
