Merge pull request #185 from JoostJM/references

Update documentation

Author: JoostJM

README.md

@@ -31,12 +31,6 @@ Aside from the feature classes, there are also some built-in optional filters:
 - Logarithm
 - Exponential
 
-Most of the provided features and filters are based on methods described in the following publications:
-
-HJWL Aerts, ER Velazquez, RTH Leijenaar, et al., "Decoding tumour phenotype by noninvasive imaging using a quantitative radiomics approach", vol. 5, Nat Communication, 2014. Available [here](http://www.nature.com/ncomms/2014/140603/ncomms5006/full/ncomms5006.html).
-
-Specifically, the formulation of the individual feature calculation is covered in this [supplement](http://www.nature.com/ncomms/2014/140603/ncomms5006/extref/ncomms5006-s1.pdf)
-
 ### Supporting reproducible extraction
 Aside from calculating features, the pyradiomics package includes provenance information in the
 output. This information contains information on used image and mask, as well as applied settings
@@ -59,6 +53,14 @@ To install this package run the following commands from the root directory:
     python -m pip install -r requirements.txt
     python setup.py install
 
+### Usage
+
+PyRadiomics can be easily used in a Python script through the `featureextractor`
+module. Furthermore, PyRadiomics provides two commandline scripts, `pyradiomics`
+and `pyradiomicsbatch`, for single image extraction and batchprocessing, respectively.
+Finally, a convenient front-end interface is provided as the 'Radiomics'
+extension for 3D Slicer, available [here](https://github.com/Radiomics/SlicerRadiomics).
+
 ### Citation 
 If you publish any work which uses this package, please cite the following publication:
 
@@ -102,3 +104,14 @@ This package is covered by the [3D Slicer License](LICENSE.txt).
 <sup>4</sup>GROW-School for Oncology and Developmental Biology, Maastricht University Medical Center, Maastricht, The Netherlands,
 <sup>5</sup>Kitware,
 <sup>6</sup>Isomics
+
+### General references
+
+- HJWL Aerts, ER Velazquez, RTH Leijenaar, et al., "Decoding tumour phenotype by noninvasive imaging using a 
+  quantitative radiomics approach", vol. 5, Nat Communication, 2014. 
+  Available [here](http://www.nature.com/ncomms/2014/140603/ncomms5006/full/ncomms5006.html).
+  Specifically, the formulation of the individual feature calculation is covered in this 
+  [supplement](http://www.nature.com/ncomms/2014/140603/ncomms5006/extref/ncomms5006-s1.pdf).
+- Zwanenburg A, Leger S, Vallières M, Löck S., "Image biomarker standardisation initiative - feature definitions", 
+  arXiv:161207003. 2016. Available [here](http://arxiv.org/abs/1612.07003).
+

bin/Notebooks/helloFeatureClass.ipynb

@@ -25,16 +25,10 @@
    "outputs": [],
    "source": [
     "import sys\n",
-    "stdout = sys.stdout  # This workaround is needed, as pykwalify reloads the sys package, resetting the stdout\n",
-    "stderr = sys.stderr\n",
-    "\n",
     "import os\n",
     "import logging\n",
     "from radiomics import featureextractor\n",
-    "import radiomics\n",
-    "\n",
-    "sys.stdout = stdout  # Force the output back to the jupyter console\n",
-    "sys.stderr = stderr"
+    "import radiomics"
    ]
   },
   {

bin/Notebooks/helloRadiomics.ipynb

@@ -28,7 +28,7 @@ setting:
 # Input images to use: original for unfiltered image and/or any other filters, see documentation of featureextractor.py
 # for possible values
 inputImage:
-  original: {} # for dictionaries / mappings, None values are not allowed, '{}' is interpreted as an empty dictionary
+  Original: {} # for dictionaries / mappings, None values are not allowed, '{}' is interpreted as an empty dictionary
 
 # Featureclasses, from which features must be calculated. If a featureclass is not mentioned, no features are calculated
 # for that class. Otherwise, the specified features are calculated, or, if none are specified, all are calculated.

bin/Params.yaml

@@ -39,7 +39,7 @@
 if kwargs['interpolator'] != None and kwargs['resampledPixelSpacing'] != None:
   image, mask = imageoperations.resampleImage(image, mask, kwargs['resampledPixelSpacing'], kwargs['interpolator'])
 else:
-  image, mask = imageoperations.cropToTumorMask(image, mask)
+  image, mask, bb = imageoperations.cropToTumorMask(image, mask)
 
 #
 # Show the first order feature calculations
@@ -143,35 +143,22 @@
 #
 if applyLog:
   sigmaValues = numpy.arange(5., 0., -.5)[::1]
-  for sigma in sigmaValues:
-    logImage = imageoperations.applyLoG(image, sigmaValue=sigma)
-    logFirstorderFeatures = firstorder.RadiomicsFirstOrder(logImage, mask, **kwargs)
+  for logImage, inputImageName, inputKwargs in imageoperations.applyFilterLoG(image, sigma=sigmaValues, verbose=True):
+    logFirstorderFeatures = firstorder.RadiomicsFirstOrder(logImage, mask, **inputKwargs)
     logFirstorderFeatures.enableAllFeatures()
     logFirstorderFeatures.calculateFeatures()
-    print 'Calculated firstorder features with LoG sigma ', sigma
     for (key, val) in logFirstorderFeatures.featureValues.iteritems():
-      laplacianFeatureName = 'LoG-sigma-%s_%s' % (str(sigma), key)
+      laplacianFeatureName = '%s_%s' % (inputImageName, key)
       print '  ', laplacianFeatureName, ':', val
 #
 # Show FirstOrder features, calculated on a wavelet filtered image
 #
 if applyWavelet:
-  ret, approx = imageoperations.swt3(image)
-
-  for idx, wl in enumerate(ret, start=1):
-    for decompositionName, decompositionImage in wl.items():
-      waveletFirstOrderFeaturs = firstorder.RadiomicsFirstOrder(decompositionImage, mask, **kwargs)
-      waveletFirstOrderFeaturs.enableAllFeatures()
-      waveletFirstOrderFeaturs.calculateFeatures()
-      print 'Calculated firstorder features with wavelet ', decompositionName
-      for (key, val) in waveletFirstOrderFeaturs.featureValues.iteritems():
-        waveletFeatureName = 'wavelet-%s_%s' % (str(decompositionName), key)
-        print '  ', waveletFeatureName, ':', val
-
-  waveletFirstOrderFeaturs = firstorder.RadiomicsFirstOrder(approx, mask, **kwargs)
-  waveletFirstOrderFeaturs.enableAllFeatures()
-  waveletFirstOrderFeaturs.calculateFeatures()
-  print 'Calculated firstorder features with approximation of wavelt (= LLL decomposition)'
-  for (key, val) in waveletFirstOrderFeaturs.featureValues.iteritems():
-    waveletFeatureName = 'wavelet-LLL_%s' % (key)
-    print '  ', waveletFeatureName, ':', val
+  for decompositionImage, decompositionName, inputKwargs in imageoperations.applyFilterWavelet(image):
+    waveletFirstOrderFeaturs = firstorder.RadiomicsFirstOrder(decompositionImage, mask, **inputKwargs)
+    waveletFirstOrderFeaturs.enableAllFeatures()
+    waveletFirstOrderFeaturs.calculateFeatures()
+    print 'Calculated firstorder features with wavelet ', decompositionName
+    for (key, val) in waveletFirstOrderFeaturs.featureValues.iteritems():
+      waveletFeatureName = 'wavelet-%s_%s' % (str(decompositionName), key)
+      print '  ', waveletFeatureName, ':', val

bin/helloFeatureClass.py

@@ -28,7 +28,7 @@
 extractor = featureextractor.RadiomicsFeaturesExtractor(**kwargs)
 
 # By default, only original is enabled. Optionally enable some filters:
-# extractor.enableInputImages(original={}, log={}, wavelet={})
+# extractor.enableInputImages(Original={}, LoG={}, Wavelet={})
 
 # Disable all classes except firstorder
 extractor.disableAllFeatures()

bin/helloRadiomics.py

@@ -64,11 +64,11 @@ mapping:
   inputImage:
     type: map
     mapping:
-      # possible image filters, it's value be adictionary that follows the rules in setting
-      original: *settings
-      log: *settings
-      wavelet: *settings
-      square: *settings
-      squareroot: *settings
-      logarithm: *settings
-      exponential: *settings
+      # possible image filters, it's value is a dictionary that follows the rules in setting
+      Original: *settings
+      LoG: *settings
+      Wavelet: *settings
+      Square: *settings
+      SquareRoot: *settings
+      Logarithm: *settings
+      Exponential: *settings

data/paramSchema.yaml

@@ -36,13 +36,6 @@ Aside from the feature classes, there are also some built-in optional filters:
 * Logarithm
 * Exponential
 
-Most of the provided features and filters are based on methods described in the following publications:
-
-HJWL Aerts, ER Velazquez, RTH Leijenaar, et al., "Decoding tumour phenotype by noninvasive imaging using a quantitative radiomics approach", vol. 5, Nat Communication, 2014. Available `here <http://www.nature.com/ncomms/2014/140603/ncomms5006/full/ncomms5006.html>`_.
-
-Specifically, the formulation of the individual feature calculation is covered in this `supplement <http://www.nature.com/ncomms/2014/140603/ncomms5006/extref/ncomms5006-s1.pdf>`_
-
-
 Supporting reproducible extraction
 ----------------------------------
 
@@ -124,3 +117,13 @@ Developers
 :sup:`4`\ GROW-School for Oncology and Developmental Biology, Maastricht University Medical Center, Maastricht, The Netherlands,
 :sup:`5`\ Kitware,
 :sup:`6`\ Isomics
+
+General references
+------------------
+* HJWL Aerts, ER Velazquez, RTH Leijenaar, et al., "Decoding tumour phenotype by noninvasive imaging using a
+  quantitative radiomics approach", vol. 5, Nat Communication, 2014.
+  Available `here <http://www.nature.com/ncomms/2014/140603/ncomms5006/full/ncomms5006.html>`_.
+  Specifically, the formulation of the individual feature calculation is covered in this
+  `supplement <http://www.nature.com/ncomms/2014/140603/ncomms5006/extref/ncomms5006-s1.pdf>`_.
+* Zwanenburg A, Leger S, Vallières M, Löck S., "Image biomarker standardisation initiative - feature definitions",
+  arXiv:161207003. 2016. Available `here <http://arxiv.org/abs/1612.07003>`_.

docs/index.rst

@@ -23,21 +23,17 @@ Installation on your system
 * For unix like systems (MacOSX, linux):
 
   * ``cd pyradiomics``
+  * ``sudo python -m pip install -r requirements.txt``
   * ``sudo python setup.py install``
 
-  * If you don't have sudo/admin rights on your machine, you need to locally install numpy, nose, tqdm, PyWavelets, SimpleITK. In a bash shell::
+  * If you don't have sudo/admin rights on your machine, you need to locally install numpy, nose, tqdm, PyWavelets, SimpleITK (specified in requirements.txt). In a bash shell::
 
       pip install --user --upgrade pip
       export PATH=$HOME/.local/bin:$PATH
-      pip install --user numpy
-      pip install --user nose
-      pip install --user nose-parameterized
-      pip install --user tqdm
+      pip install --user -r requirements.txt
       export PYTHONPATH=$HOME/.local/lib64/python2.7/site-packages
-      git clone https://github.com/nigma/pywt.git && cd pywt && python setup.py install --prefix=$HOME/.local && cd ..
-      pip install --user SimpleITK
 
-    * If the installation of SimpleITK fails (newer versions not available on the default servers, you can get it manually from `sourceforge <https://sourceforge.net/projects/simpleitk/files/SimpleITK/>`_
+    * If the installation of SimpleITK fails (newer versions not available on the default servers), you can get it manually from `sourceforge <https://sourceforge.net/projects/simpleitk/files/SimpleITK/>`_
 
       * For linux::
 
@@ -48,3 +44,13 @@ Installation on your system
 
           wget 'https://sourceforge.net/projects/simpleitk/files/SimpleITK/0.10.0/Python/SimpleITK-0.10.0-cp27-cp27m-macosx_10_6_intel.whl'
           pip install --user 'SimpleITK-0.10.0-cp27-cp27m-macosx_10_6_intel.whl'
+
+* For Windows:
+
+  * ``cd pyradiomics``
+  * ``python -m pip install -r requirements.txt``
+  * ``python setup.py install``
+
+  * If the installation of SimpleITK fails (newer versions not available on the default servers), you can install it manually::
+
+        pip install --trusted-host www.simpleitk.org -f https://sourceforge.net/projects/simpleitk/files/SimpleITK/0.10.0/Python/ SimpleITK==0.10.0

docs/installation.rst

@@ -87,6 +87,13 @@ Interactive Use
 
 * See the :ref:`feature extractor class<radiomics-featureextractor-label>` for more information on using this core class.
 
+------------------------
+PyRadiomics in 3D Slicer
+------------------------
+
+A convenient front-end interface is provided as the 'Radiomics' extension for 3D Slicer. It is available
+`here <https://github.com/Radiomics/SlicerRadiomics>`_.
+
 ------------------------------
 Using feature classes directly
 ------------------------------