Add voxel cli

README.md

@@ -23,7 +23,10 @@ With this package we aim to establish a reference standard for Radiomic Analysis
 open-source platform for easy and reproducible Radiomic Feature extraction. By doing so, we hope to increase awareness
 of radiomic capabilities and expand the community.
 
-The platform supports both the feature extraction in 2D and 3D. **Not intended for clinical use.**
+The platform supports both the feature extraction in 2D and 3D and can be used to calculate single values per feature
+for a region of interest ("segment-based") or to generate feature maps ("voxel-based"). 
+
+**Not intended for clinical use.**
 
 **If you publish any work which uses this package, please cite the following publication:**
 *van Griethuysen, J. J. M., Fedorov, A., Parmar, C., Hosny, A., Aucoin, N., Narayan, V., Beets-Tan, R. G. H.,

docs/customization.rst

@@ -8,12 +8,13 @@ Customizing the Extraction
 Types of Customization
 ----------------------
 
-There are 3 ways in which the feature extraction can be customized in PyRadiomics:
+There are 4 ways in which the feature extraction can be customized in PyRadiomics:
 
 1. Specifying which image types (original/derived) to use to extract features from
 2. Specifying which feature(class) to extract
 3. Specifying settings, which control the pre processing and customize the behaviour of enabled filters and feature
    classes.
+4. Specifying the voxel-based specific settings, which are only needed when using PyRadiomics to generate feature maps
 
 .. warning::
     At initialization of the feature extractor or an individual feature class, settings can be provided as keyword
@@ -349,13 +350,34 @@ Feature Class Specific Settings
 - ``gldm_a`` [0]: float, :math:`\alpha` cutoff value for dependence. A neighbouring voxel with gray level :math:`j` is
   considered dependent on center voxel with gray level :math:`i` if :math:`|i-j|\le\alpha`
 
+.. _radiomics-voxel-settings-label:
+
+Voxel-based specific settings
+#############################
+
+When using PyRadiomics to generate feature maps, additional customization options exist. These control the neighborhood
+around each voxel that is used for calculation (kernel) and what the background value should be, i.e. the value of
+voxels for which there is no calculated value.
+
+- ``kernelRadius`` [1]: integer, specifies the size of the kernel to use as the radius from the center voxel. Therefore
+  the actual size is ``2 * kernelRadius + 1``. E.g. a value of 1 yields a 3x3x3 kernel, a value of 2 5x5x5, etc. In case
+  of 2D extraction, the generated kernel will also be a 2D shape (square instead of cube).
+
+- ``maskedKernel`` [True]: boolean, specifies whether to mask the kernel with the overall mask. If True, only voxels in
+  the kernel that are also segmented in the mask are used for calculation. Otherwise, all voxels inside the kernel are
+  used. Moreover, gray value discretization is performed over the ROI if the setting is set to True, and over the entire
+  image if False.
+
+- ``initValue`` [0]: float, value to use for voxels outside the ROI, or voxels where calculation failed. If set to
+  ``nan``, 3D slicer will treat them as transparent voxels
+
 .. _radiomics-parameter-file-label:
 
 --------------
 Parameter File
 --------------
 
-All 3 categories of customization can be provided in a single yaml or JSON structured text file, which can be provided
+All 4 categories of customization can be provided in a single yaml or JSON structured text file, which can be provided
 in an optional argument (``--param``) when running pyradiomics from the command line. In interactive mode, it can be
 provided during initialization of the :ref:`feature extractor <radiomics-featureextractor-label>`, or using
 :py:func:`~radiomics.featureextractor.RadiomicsFeaturesExtractor.loadParams` after initialization. This removes the need
@@ -399,6 +421,8 @@ The three setting types are named as follows:
    <value> is specified or <value> is an empty list ('[]'), all features for this class are enabled.
 3. **setting:** Setting to use for pre processing and class specific settings. if no <value> is specified, the value for
    this setting is set to None.
+4. **voxelSetting:** Settings used to control the voxel-based specific settings. E.g. the size of the kernel used and
+   the background value in the parameter maps.
 
 Example::
 

docs/index.rst

@@ -9,7 +9,9 @@ Welcome to pyradiomics documentation!
 This is an open-source python package for the extraction of Radiomics features from medical imaging.
 With this package we aim to establish a reference standard for Radiomic Analysis, and provide a tested and maintained
 open-source platform for easy and reproducible Radiomic Feature extraction. By doing so, we hope to increase awareness
-of radiomic capabilities and expand the community. The platform supports both the feature extraction in 2D and 3D.
+of radiomic capabilities and expand the community. The platform supports both the feature extraction in 2D and 3D and
+can be used to calculate single values per feature for a region of interest ("segment-based") or to generate feature
+maps ("voxel-based").
 
 **If you publish any work which uses this package, please cite the following publication:**
 *van Griethuysen, J. J. M., Fedorov, A., Parmar, C., Hosny, A., Aucoin, N., Narayan, V., Beets-Tan, R. G. H.,

docs/usage.rst

@@ -28,9 +28,20 @@ Example
 
   * The parameter file used in the instruction video is available in ``pyradiomics/examples/exampleSettings``
 
-* If jupyter is not installed, run the python script alternative (``pyradiomics/examples/helloRadiomics.py``):
+* If jupyter is not installed, run the python script alternatives contained in the folder (``pyradiomics/examples``):
 
-  * ``python helloRadiomics.py``
+  * ``python helloRadiomics.py`` (segment-based extraction)
+  * ``python helloVoxel.py`` (voxel-based extraction)
+
+----------------------
+Voxel-based extraction
+----------------------
+
+As of version 2.0, pyradiomics also implements a voxel-based extraction. It is both available from the command line and
+in the interactive use. See below for details.
+
+Important to know here is that this extraction takes longer (features have to be calculated for each voxel), and that
+the output is a SimpleITK image of the parameter map instead of a float value *for each feature*.
 
 ----------------
 Command Line Use
@@ -71,6 +82,12 @@ Command Line Use
   argument and/or by specifying override settings (only `type 3 customization <radiomics-settings-label>`) in the
   ``--setting`` argument. Multiple overrides can be used by specifying ``--setting`` multiple times.
 
+* To extract feature maps ("voxel-based" extraction), simply add the argument ``--mode voxel``. The calculated feature
+  maps are then stored as images (NRRD format) in the current working directory. The name convention used is
+  "Case-<idx>_<FeatureName>.nrrd". An alternative output directory can be provided in the ``--out-dir`` command line
+  switch. The results that are printed to the console window or the out file will still contain the diagnostic
+  information, and the value of the extracted features is set to the location the feature maps are stored.
+
 * For more information on the possible command line arguments, run::
 
     pyradiomics -h
@@ -91,9 +108,12 @@ Interactive Use
 
 * Import the necessary classes::
 
-     from radiomics import featureextractor, getTestCase
+     import os
+
+     import SimpleITK as sitk
      import six
-     import sys, os
+
+     from radiomics import featureextractor, getTestCase
 
 * Set up a pyradiomics directory variable::
 
@@ -113,44 +133,23 @@ Interactive Use
 
     extractor = featureextractor.RadiomicsFeaturesExtractor(params)
 
-* Calculate the features::
+* Calculate the features (segment-based)::
 
     result = extractor.execute(imageName, maskName)
     for key, val in six.iteritems(result):
       print("\t%s: %s" %(key, val))
 
-* See the :ref:`feature extractor class<radiomics-featureextractor-label>` for more information on using this core class.
-
-----------------------
-Voxel-based extraction
-----------------------
-
-As of version 2.0, pyradiomics also implements a voxel-based extraction.
-Currently, this is only available in the interactive mode, and is as simple as telling the feature extractor to
-extract a parameter map::
-
-    from radiomics import featureextractor, getTestCase
-    import six
-    import sys, os
-
-    import SimpleITK as sitk
-
-    dataDir = '/path/to/pyradiomics'
-
-    imageName, maskName = getTestCase('brain1', dataDir)
-    params = os.path.join(dataDir, "examples", "exampleSettings", "exampleVoxel.yaml")
-
-    extractor = featureextractor.RadiomicsFeaturesExtractor(params)
+* Calculate the features (voxel-based)::
 
     result = extractor.execute(imageName, maskName, voxelBased=True)
-
     for key, val in six.iteritems(result):
-      sitk.WriteImage(val, key + 'nrrd')
+      if isinstance(val, sitk.Image):  # Feature map
+        sitk.WriteImage(val, key + '.nrrd', True)
+        print("Stored feature %s in %s" % (key, key + ".nrrd")
+      else:  # Diagnostic information
+        print("\t%s: %s" %(key, val))
 
-Important to know here is that this extraction takes longer (features have to be calculated for each voxel), and that
-the output is a SimpleITK image of the parameter map instead of a float value *for each feature*.
-
-Be sure to also check out the ``helloVoxel.py`` example available in the repository (folder ``examples``).
+* See the :ref:`feature extractor class<radiomics-featureextractor-label>` for more information on using this core class.
 
 ------------------------
 PyRadiomics in 3D Slicer

radiomics/featureextractor.py

@@ -422,11 +422,11 @@ def execute(self, imageFilepath, maskFilepath, label=None, voxelBased=False):
     if resegmentShape and resegmentedMask is not None:
       mask = resegmentedMask
 
-    if not voxelBased:
-      # 3. Add the additional information if enabled
-      if self.generalInfo is not None:
-        featureVector.update(self.generalInfo.getGeneralInfo())
+    # 3. Add the additional information if enabled
+    if self.generalInfo is not None:
+      featureVector.update(self.generalInfo.getGeneralInfo())
 
+    if not voxelBased:
       # 4. If shape descriptors should be calculated, handle it separately here
       if 'shape' in self._enabledFeatures.keys():
         featureVector.update(self.computeShape(image, mask, boundingBox))