Merge remote-tracking branch 'refs/remotes/origin/master'

README.md

@@ -1,128 +1,79 @@
-# Description
-This repository contains the full data set for constructing the DAPI template, the full DAPI template creation pipeline and the automatic slice segmentation.
- 
-# Automatic slice segmentation  
+
+# Description of DAPI template
+This repository contains a three-dimensional population-based average atlas, the DAPI template, of the C57BL/6 mouse brain stained with the commonly employed fluorescence nuclear stain DAPI. The [DAPI template](./data/dapi_template.nii.gz), [accompanying segmentation](./data/dapi_template_segmentation_full.nii.gz), and a [simplified segmentation](./data/dapi_template_segmentation_simple.nii.gz) can be found as nifti files in ```data/```. Moreover, the repository contains all the raw data (```data/mice/```) and the full code base (```template_creation_pipieline/```) which was used in the construction of the teamplate.
+
+The DAPI template, is constructued from consecutive coronal brain slices of 12 male mice aged between 10-11 weeks. Each mouse brain is first reconstructed into a three-dimensional volume and then an iterative averaging process of these reconstructed brain volumes was employed to yield the final population-based average.
+
+The repository also includes an automatic segmentation/spatial normalization pipeline (```automatic_segmentation_program/```) for novel coronal slices described below. 
+
+# Automatic slice segmentation
 
 Program for automatic segmentation to a DAPI-stained coronal mouse brain slices.
 
+**Getting started**
+ - [Setup your environment](#how-to-setup-the-environment) with the correct python version, python packages, and Advanced Normalization Tools (ANTs).
+ -  Download the and unzip the [example folder](./Example_folder.zip).
+ - In a terminal window, navigate into the unzipped example folder.
+ - Run the runner_example.sh with the command ```bash runner_example.sh```
+ - The automatically created segmentation can be found in ```Brain_example/Segmentation.nii``` 
+
+For detailed parameter and output description go to the [automatic segmentation program](./automatic_segmentation_program).
 
-## How to setup the enviroment
-### Below is a quick guide to setup the enviroment on a UNIX (Mac and Linux) system
+## How to setup the environment
+Below is a quick guide to setup the enviroment on a UNIX (Mac and Linux) system
 
-* To run the program, Python 3.7+ is required. You can get the newest version of
-  python by installing Anaconda. To check the version of the python instalation
-  typing 
+* The program requires Python 3.7+. You can get the newest version of python by installing Anaconda (https://www.anaconda.com). To check your version of python, type
   ```sh
   python --version
   ```
-  
-* Install ANTs. This is done by adding a precompiled binaries to the libary
-  directory. The precompiled binaries for Mac/Linux is avaliable at  
+
+* Install or update all packages listed in `requirements.txt`. All packages can be installed/updated using `pip`. To install a package, e.g. nibabel:
+
+  ```sh
+  pip install nibabel
+  ```
+
+  To check the version of a package
+  ```sh
+  pip freeze | grep nibabel
+  ```
+* Install ANTs, preferably using precompiled binaries, available (for Mac/Linux) at  
   https://github.com/ANTsX/ANTs/releases/tag/v2.1.0
 
-* Make sure to add ANTs to the path. This is done by editing the config file for
-  the terminal shell. The config file would often be named
+* Create ANTSPATH and add it to your path. This is done by editing the config file for the terminal shell. The config-file is often named
   ```sh
   ~/.bashrc
   ```
-  In the configfile add the path. This can be done by inserting
+  or
   ```sh
-  export PATH=$PATH:usr/local/bin/ANTs:
+  ~/.bash_profile
   ```
-  Here the path to the ANTs registration was $/usr/local/bin/ANTs
-  
-  After adding this to the config file, restart the terminal and test if the
+
+  In the config-file add the following lines
+  ```sh
+  export ANTSPATH=usr/local/bin/ANTs
+  export PATH=$PATH:$ANTSPATH
+  ```
+  Here, ANTs was installed in `/usr/local/bin/ANTs`
+
+  After adding this to the config-file, restart the terminal and test if the
   path was added correctly by typing
   ```sh
   which antsRegistration
   ```
   The correct path should then be printed.
-  
-  
 
-* if permission denied, then the file needs to be made executable - this is done using the command
+
+* if permission is denied, the file needs to be made executable - this is done using the command
   ```sh
   chmod +x <...>/antsRegistration
   ```
-  
-* Make sure to have installed or updated all packages listed in
-  requirements.txt. All the packages can be updated using pip. It is espicially
-  crucial to have installed to have installed the non standard packages Nibabel
-  and nipype. To install a a package i.e. Nibabel 
-  
-  ```sh
-  pip install nibabel
-  ```
-  
-  To check the version of a package 
-  ```sh 
-  pip freeze | grep nibabel
-  ```
-  
+
   
 ## Prerequisites  
-* A high-resolution, DAPI modality TIFF image of a brain slice. Can have multiple channels.  
-* A template file (.nii or .nii.gz)  
-* A segmentation of the template file  (.nii or .nii.gz)  
+* A high-resolution, DAPI modality TIFF image of a coronal mouse brain slice. Can have multiple channels.  
+* The DAPI template file (.nii or .nii.gz)  
+* A segmentation of the DAPI template  (.nii or .nii.gz)  
   
 ## Usage  
-* Use runner.py to preprocess and output a sgementation registred to the slice
-  in a designated output folder
-* Use preprocess.py to prepare input slice for automatic registration  
- 
-## Example_folder.zip
-In the repository is included a zip file that contains all the files and scripts
-used in order to run an Example of the program. To run the example, download and
-unzip the folder and open the folder in a terminal window. Make sure that the
-enviroment is setup correct as descirbed above, and then run the shell fill by 
-```sh
-bash runner_example.sh
-```
-
-
-## Details
-Detailed parameter description.
-
-### runner.py
-**Usage**
-```sh  
-python3 runner.py sliceloc segloc templateloc bregma [coord] outputdir
-```  
-In the subfolder 'Example' a shell script is provided that runs the programs as
-intended with test brainslice.
-
-**Positional/Required Arguments**
-
-|||
-|--------------------------------|-----------------------------|
-|`sliceloc`            |Location of the slice you wish to register (.nii or.nii.gz) |
-|`segloc`            |Location of file containing segmentation of the template (.nii or.nii.gz)            |
-|`templateloc`|Location of template file (.nii or .nii.gz)|
-|`bregma [coord]`|Bregma coordinate of input slice |
-|`outputdir`| Location for the output of the registration files|
-**Optional arguments**
-
-| | |
-|---|---|
-|`--dapi [index]`   |Index of the DAPI channel in the slice, by default the DAPI channel is assumed to be the last channel|
-
-### preprocess.py  
-**Usage**
-```sh  
-python3 preprocess.py file dir -s Series --pdim [pixeldimensions]  
-```  
-**Positional/Required Arguments**
-
-|||
-|--------------------------------|-----------------------------|
-|`file`            |Location of the file to be preprocessed (.tiff or .nd2) |
-|`dir`            |Directory to output preprocessed files (will output .nii files)|
-|`-s`|The series to extract (If input file is single-series, use 0 for this argument)|
-
-**Optional arguments**
-
-|||
-|--------------------------------|-----------------------------|
-|`--pdim [pixeldimensions]`            |Dimensions of pixels, if not provided, these will be extracted from image metadata|# Description
-This repository contains the full data set for constructing the DAPI template, the full DAPI template creation pipeline and the automatic slice segmentation.
- 
+Use runner.py to preprocess and output a segmentation registred to the slice. For detailed parameter and output description go to the [automatic segmentation program](./automatic_segmentation_program).

automatic_segmentation_program/README.md

@@ -0,0 +1,33 @@
+# Output
+Running the runner.py will yield the following outputs.
+ - A nifti file of the pre-processed input slice, called ```[outputdir]/[name].nii```
+ - A directory with the same name as the input slice, ```[outputdir]/[name]/``` in which you will find the following outputs
+   - The different channels of the input slice ('im_c1.nii', 'im_c2.nii, ...')
+   - The segmentation of the input file in pre-processed space, called ```Segmentation.nii``` (Can be viewed in [ITK-SNAP](http://www.itksnap.org/pmwiki/pmwiki.php) by opening one of the channels as main image and the 'Segmentation.nii' as segmentation)
+   - The DAPI template slice registered to the input slice, called ```TemplateSlice__InverseWarped.nii.gz```
+   - The input slice registered registered to the DAPI template slice, called ```im_c[dapi_index]_template.nii```
+   - The composite transformation of the input slice to the corresponding template slice, called 'Transformation_Composite.h5'
+   - The inverse composite transformation, i.e. the transformation from the template slice to the input slice, called 'Transformation_InverseComposite.h5'
+
+# Parameters
+Detailed parameter description. For example see [```../Example/``` ](../Example)
+
+**Usage**
+```sh  
+python3 runner.py sliceloc segloc templateloc bregma outputdir
+```  
+
+**Positional/Required Arguments**
+
+|||
+|--------------------------------|-----------------------------|
+|`sliceloc`            |Location of the slice you wish to register (.nii or.nii.gz) |
+|`segloc`            |Location of file containing segmentation of the template (.nii or.nii.gz)            |
+|`templateloc`|Location of template file (.nii or .nii.gz)|
+|`bregma [coord]`|Bregma coordinate of input slice |
+|`outputdir`| Location for the output of the registration files|
+**Optional arguments**
+
+| | |
+|---|---|
+|`--dapi [index]`   |Index of the DAPI channel in the slice, by default the DAPI channel is assumed to be the last channel|

requirements.txt

@@ -2,7 +2,7 @@ xmltodict==0.12.0
 scipy==1.2.3
 nipype==1.4.2
 matplotlib==3.1.3
-nibabel==3.0.1
+nibabel==3.0.2
 numpy==1.18.1
 openpyxl==3.0.3
 scikit-image==0.16.2