Merge pull request #51 from reghbali/reghbali_readme_docs

Reghbali readme docs

README.md

@@ -14,22 +14,29 @@ To use Greedy and Convert3d, these command line tools should be installed on you
 
 ## Installation
 
-Clone the repo
+We recommend upgrading pip and installing pyalfe in a virtualenv.
 ```bash
-git clone https://github.com/reghbali/pyalfe.git
-cd pyalfe
+python3 -m venv venv
+source venv/bin/activate
+pip install --upgrade pip
 ```
 
-Then run (we recommend using a python virtual environment)
+### Option 1: PyPI
 
+To install, run
 ```bash
-pip install --upgrade pip
+pip install pyalfe
 ```
 
-You can either install pyalfe in [development mode](#development-mode-installation) or [build and install](#build-and-install).
-### Option 1: Development mode installation
 
-First update the setuptools
+### Option 2: Development mode
+If you want to have the latest development version, you can clone the repo
+```bash
+git clone https://github.com/reghbali/pyalfe.git
+cd pyalfe
+```
+
+update the setuptools
 ```bash
 pip install --upgrade setuptools
 ```
@@ -40,9 +47,13 @@ Run the following command in the parent pyalfe directory:
 pip install -e .
 ```
 
-### Option 2: Build and install
+### Option 3: Build and install
+```bash
+git clone https://github.com/reghbali/pyalfe.git
+cd pyalfe
+```
 
-First update the build tool
+update the build tool
 ```bash
 pip install --upgrade build
 ```
@@ -58,16 +69,31 @@ To download deep learning models, run
 ```bash
 pyalfe download models
 ```
-### Pyradiomics support
-To install pyalfe with pyradiomics support, run
+### Extras
+If you want pyalfe to generate pyradiomics features alongside its default features
+you can install pyalfe with pyradiomics support. To do so, run:
+```bash
+pip install 'pyalfe[radiomics]'
+```
+for development installation
 ```bash
 pip install -e  '.[radiomics]'
 ```
-for development installation or
+when performing a build and install
 ```bash
 pip install 'dist/pyalfe-0.0.1-py3-none-any.whl[radiomics]'
 ```
-when performing a build and install.
+
+If you want to use ant registration tool, you can install pyalfe with ants support:
+```bash
+pip install 'pyalfe[ants]'
+```
+
+If you want to build the docs, install pyalfe with docs support:
+```bash
+pip install 'pyalfe[docs]'
+```
+
 ## Usage
 
 ### Configuration
@@ -187,21 +213,22 @@ This config value can be overwritten when calling `pyalfe run` via `-dt` or `--d
 
 #### Image processor
 ```bash
-image processor to use (c3d, nilearn) [c3d]:
+image processor to use (nilearn, c3d) [nilearn]:
 ```
-Currently, pyalfe can be configures to use either Convert3D (a.k.a. c3d) or Nilearn for image processing tasks.
-The default is Convert3d aka c3d. In other to use c3d,
-you have to download it using the [download command](#download-models).
-To use Nilearn, you do not need to run any extra command since it is already installed when you install pyalfe.
+Currently, pyalfe can be configured to use either Nilearn, Convert3D (a.k.a. c3d) for image processing tasks.
+The default is Nilearn which is a python native library and is installed during installation of pyalfe.
+To use c3d, you have to download and install it (https://sourceforge.net/projects/c3d/) on your machine.
+
 This config value can be overwritten when calling `pyalfe run` via `-ip` or `--image_processing` option.
 
 #### Image Registration
 ```bash
 image registration to use (greedy, ants) [greedy]:
 ```
-Currently, pyalfe can be configures to use either greedy or ants for image registration tasks. The default is greedy.
-In other to use greedy, you have to download it using the [download command](#download-models). To use ants,
+Currently, pyalfe can be configured to use either greedy or ants for image registration tasks. The default is greedy.
+In other to use greedy, you have to download and install greedy (https://sourceforge.net/projects/greedy-reg/). To use ants,
 install pyalfe with ants support ``pip install pyalfe[ants]``.
+
 This config value can be overwritten when calling `pyalfe run` via `-ir` or `--image-registration` option.
 
 #### Dierctory Data Structure

pyalfe/image_processing.py

@@ -429,6 +429,12 @@ def label_mask_comp(binary_image, output):
 
 
 class NilearnProcessor(ImageProcessor):
+    @staticmethod
+    def save(nib_image, file):
+        # np.int32 is problematic. 1s can turn into 0.9999999
+        nib_image.set_data_dtype(np.float32)
+        nib.save(nib_image, file)
+
     @staticmethod
     def _crop_img_to(image, slices, copy=True):
 
@@ -484,23 +490,21 @@ def threshold(
             (data >= lower_bound) & (data <= upper_bound), inside_target, outside_target
         ).astype(np.int16)
         threshold_image = nib.Nifti1Image(threshold_data, nib_image.affine)
-        nib.save(threshold_image, output)
+        NilearnProcessor.save(threshold_image, output)
 
     @staticmethod
     def binarize(image, output):
         nib_image = nilearn.image.load_img(image)
-        nib.save(nilearn.image.binarize_img(nib_image), output)
+        NilearnProcessor.save(nilearn.image.binarize_img(nib_image), output)
 
     @staticmethod
     def mask(image, mask, output):
         nib_image = nilearn.image.load_img(image)
         nib_mask = nilearn.image.load_img(mask)
         masked_image = nib.Nifti1Image(
-            nib_image.get_fdata() * nib_mask.get_fdata(),
-            nib_image.affine,
-            dtype=np.int16,
+            nib_image.get_fdata() * nib_mask.get_fdata(), nib_image.affine
         )
-        nib.save(masked_image, output)
+        NilearnProcessor.save(masked_image, output)
 
     @staticmethod
     def largest_mask_comp(image, output):
@@ -516,9 +520,9 @@ def largest_mask_comp(image, output):
     def holefill(binary_image, output):
         nib_image = nilearn.image.load_img(binary_image)
         data = nib_image.get_fdata()
-        holefilled_data = scipy.ndimage.binary_fill_holes(data).astype('int16')
+        holefilled_data = scipy.ndimage.binary_fill_holes(data).astype('int32')
         holefilled_image = nib.Nifti1Image(holefilled_data, nib_image.affine)
-        nib.save(holefilled_image, output)
+        NilearnProcessor.save(holefilled_image, output)
 
     @staticmethod
     def reslice_to_ref(ref_image, moving_image, output):
@@ -544,7 +548,7 @@ def resample_new_dim(image, output, dim1, dim2, dim3, percent=True):
             target_shape=new_dims,
             interpolation='nearest',
         )
-        nib.save(resampled_image, output)
+        NilearnProcessor.save(resampled_image, output)
 
     @staticmethod
     def get_dims(image):
@@ -563,7 +567,7 @@ def trim_largest_comp(image, output, trim_margin_vec):
         trimmed_largest_comp_image = NilearnProcessor.crop_img(
             largest_comp_image, pad=trim_margin_vec
         )
-        nib.save(trimmed_largest_comp_image, output)
+        NilearnProcessor.save(trimmed_largest_comp_image, output)
 
     @staticmethod
     def set_subtract(binary_image_1, binary_image_2, output):
@@ -587,7 +591,7 @@ def dilate(binary_image, rad, output):
                 data, structure=np.ones(3 * (-2 * rad + 1,))
             ).astype(data.dtype)
         dilated_image = nib.Nifti1Image(dilated_data, nib_image.affine)
-        nib.save(dilated_image, output)
+        NilearnProcessor.save(dilated_image, output)
 
     @staticmethod
     def union(binary_image_1, binary_image_2, output):

pyalfe/main.py

@@ -200,8 +200,8 @@ def configure():
     )
     image_processor = click.prompt(
         'image processor to use (press enter for default)',
-        type=click.Choice(['c3d', 'nilearn']),
-        default='c3d',
+        type=click.Choice(['nilearn', 'c3d']),
+        default='nilearn',
     )
     image_registration = click.prompt(
         'image registration to use (press enter for default)',