This file contains the instructions to build and run image registration project provided in itk_scripts folder. It applies affine and deformable image registration using ITK toolkit. It is assumed that input images are roughly pre-aligned using rigid transformation.

1. Install ITK 
You can find the installation instructions on the ITK webpage. (http://www.itk.org/Wiki/ITK/Getting_Started)

We also provide the installation guidelines that worked for us. We used version 3.20 of ITK. Versions starting from 4.0 are a bit different but the registration works as well. 

a) Download ITK version 3.20 (from http://www.itk.org/) to <source> folder
b) Create <bin> folder
c) Open command line and go to the <bin> folder:
	cd <bin>
d) Run the CMake executable:
	cmake <source>
e) Build the project:
	make


2. Build affine and deformable registration scripts

a) Create <scripts> folder
b) Copy all supplementary scripts into the <scripts> folder
c) Open command line
d) Define ITK_DIR variable:
	export ITK_DIR=<bin>
e) Run the CMake executable:
	cmake .
d) Build the project:
	make


3. Run registration. 
You can use the file register.sh provided in itk_scripts.zip that runs the registration project files in the correct order:
- AffineRegistration defines affine transform for registration using reference channel
- DeformableRegistration defines deformable transform for registration using reference channel
- ApplyAffineTransform applies affine transform to the gene expression channel
- ApplyDeformableTransform applies deformable transform to the affined gene expression channel

To run the script you need to provide the following parameters in the correct order:
- fixedFileName is a name of the file containing template (8 bit image with the reference channel only)
- movingFileName is a name of the file containing a sample image that will be registered to the template (8 bit image with the reference channel only)
- geneFileName is the name of the file containing the gene expression channel of a sample image (8 bit image containing gene expression signal only)
- outputFileMask is mask for the output file

Example:
	./register.sh template_dapi.tif sample_dapi.tif sample_red.tif ~/outputfolder/sample_registered 

The register scripts generates 8 output files:
Affine step:
- <outputFileMask>_mr_aff20_transform.txt contains affine transform parameters
- <outputFileMask>_mr_aff20.tiff contains moving image after affine transformation
- <outputFileMask>_dr7sam_before.tiff contains overlaid fixed and moving images after affine registration
- <outputFileMask>_ir20sam_red.tiff contains gene expression channel of the moving image after affine transformation

Deformable step:
- <outputFileMask>_dr7sam_field.mha contains deformable transform parameters
- <outputFileMask>_dr7sam.tiff contains sample image after deformable trasnformation
- <outputFileMask>_dr7sam_after.tiff contains overlaid fixed and moving images after deformable registration
- <outputFileMask>_dr7sopt_red.tiff contains gene expression channel of the sample image after affine transformation. This is a final registered gene expression channel

4. You can also register all images in a folder using the script register_folder.sh. The following parameters should be specified in the correct order:
- imageFolder is a folder containing both reference signal and gene expression images of a sample that will be registered to the template (8 bit images)
- referenceImage is a name of the file containing template (8 bit image with the reference channel only)
- outputFolder is a folder where output files will be stored
- refChannel is a string containing the ending of file containing reference channel (i.e. if you reference channel images end with _dapi.tif refChannel is 'dapi')

Example:
	./register_folder.sh ~/inputImages/ template_dapi.tif ~/outputFolder dapi

The script will register all the genes from the inputImages folder using dapi channel as reference signal.

5. Generate and average image
You can use the script NormalizeAndAverageFiles to normalize (using mean and deviation of the image intensities) and average several gene expression images for an individual gene. The format is:
NormalizeAndAverageFiles <input file list> <outputFile>
where <input file list> contains input gene expression images separated with space and <outputFile> is the output file for an average image.
 

