
***********************
** BRIEF USER MANUAL **
***********************


REQUIREMENTS

In the following, we assume that the required software (ANTS, fsl) and library (openCV-python, numpy) are already installed, and accessible via the command line.
Python 2 (not Python 3) enviroment is required.

Prior to running the codes, please download CUBIC-Atlas from our website (http://cubic-atlas.riken.jp/).

For clarity, we recommend to use separate folders for each type of data.
For instance, we usually have one external hard-drive for each dataset and use the following structure:
- the 'Nucleus' folder contains the TIFF files of nucleus stained images obtained from the microscope (one subfolder per stack).
The names of subfolders MUST BE the same as the names of subfolders in 'Nucleus' folder.
- the 'Coordinate' folder contains detected cell coordinate information. The names of csv files MUST BE the same as the names of subfolders in 'Nucleus' folder.
- the 'Compress' folder is used to store downsampled image data, which is required during image registration. 
- the 'Result' folder for the export of the results. 

We recommend using a similar structure, but this can be modified in the parameter files.


STEP 0: cell detection in your image

Before starting cell-mapping, you have to prepare the 3D coordinates of the cells of 'Nucleus' images. 

Currently, there are no universal cell-detection algorighm which allow robust detections regardless of the types of labels or qualities of images.
Therefore, the users must develop the cell-detection algorithm by tuning the existing algorithms or making user-defined customized algorithms.
As the reference, we prepared macro code of ImageJ (macro_detection.txt). The detail of detection algorithm is described in our previous paper (Tatsuki et al., 2016, Neuron).


You can also prepare coordinate data by manual detection or your own programs.
The coordinates should be expressed as pixel unit of original image, and must be stored as csv file with header information (e.g. x y z). 



STEP 1: image_downsampling.py

In this step, we downsample the images of 'Nucleus' for the registration to CUBIC-Atlas.

To run the script, type python image_downsampling.py <file>
 where <file> is the name of the file giving all required parameters

The script takes 4 parameters.
An example is given in image_downsampling_paramters.txt 
Lines starting with # are comments to help understand the file structure, and are ignored by the script.

For the "files" parameters, please note that:
- in Python, the first character is at position 0.
- the two values are separated by a comma (with no space).

We strongly recommend downscaling the samples within 500 x 500 x 500 given the computational cost during registration process.
Higher resolution does not guarantee more accurate result. Please modify xy-compression ratio and z-compression ratio depending on your image size. xy-scale and z-scale do not need to be isotropic.

The resulting compressed images and size information (txt file) are required at following step.



STEP 2: cell_mapping.py

In this step, we annotate the detected cells prepared in STEP 0 through registration to CUBIC-Atlas
The registration relies on ANTs.

To run the script, type: python cell_mapping.py <file>
 where <file> is the name of the file giving all the required parameters

An example of parameter file is given in cell_mapping_parameters.txt. 

The output returns 
registration result (registered.tif), annotated coordinates (result.csv), and summary information (regional_result.csv)
If your coordinate file includes additional information (e.g. intensity, area), the summary information also returns you
regionally averaged additional information.
