Update documentation

README.md

@@ -9,17 +9,13 @@
 
 ## Radiomics feature extraction in Python
 
-This is an open-source python package for the extraction of Radiomics features from 2D and 3D images and 
-segmentations.
+This is an open-source python package for the extraction of Radiomics features from medical imaging.
 
-Image loading and preprocessing (e.g. resampling and cropping) are first done using `SimpleITK`. 
-Then, loaded data are converted into numpy arrays for further calculation using feature classes
-outlined below.
+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.
 
-With this package we aim to establish a reference standard for Radiomic Analysis, and provide a tested and mantained
-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.
 
 **If you publish any work which uses this package, please cite the following publication:**\
 *Joost JM van Griethuysen, Andriy Fedorov, Chintan Parmar, Ahmed Hosny, Nicole Aucoin, Vivek Narayan, Regina GH 
@@ -67,8 +63,8 @@ Furthermore, an instruction video is available [here](http://radiomics.io/pyradi
 PyRadiomics is OS independent and compatible with both Python 2.7 and Python >=3.4.
 To install this package on unix like systems run the following commands from the root directory:
 
-    sudo python -m pip install -r requirements.txt
-    sudo python setup.py install
+    python -m pip install -r requirements.txt
+    python setup.py install
 
 Detailed installation instructions, as well as instructions for installing PyRadiomics on Windows are available in the 
 [documentation](http://pyradiomics.readthedocs.io/en/latest/installation.html).
@@ -99,8 +95,8 @@ extension for 3D Slicer, available [here](https://github.com/Radiomics/SlicerRad
 
 ### 3rd-party packages used in pyradiomics:
 
- - SimpleITK
- - numpy
+ - SimpleITK (Image loading and preprocessing)
+ - numpy (Feature calculation)
  - PyWavelets (Wavelet filter)
  - pykwalify (Enabling yaml parameters file checking)
  - tqdm (Progressbar)

data/README.md

@@ -0,0 +1,10 @@
+This folder contains the test cases and baseline used to ensure consistent results from features implemented in 
+PyRadioimcs.
+
+`baseline` contains calculated features in full-python mode for test cases brain1, brain2, breast1, lung1 and lung2 and
+was generated using `addClassToBaseline.py`, available in the `bin` folder of this repository.
+
+Settings used were hardcoded in the script to generate the baseline and apply no filters or resampling.
+Applied settings are contained within the general_info section included in the baseline. This
+section must be present, as the test code extracts the settings to apply from the baseline, enabling
+a baseline to have different settings if necessary.

data/baseline/baseline_glcm.csv

@@ -1,6 +1,6 @@
-Patient ID,general_info_BoundingBox,general_info_GeneralSettings,general_info_ImageHash,general_info_ImageSpacing,general_info_InputImages,general_info_MaskHash,general_info_Version,general_info_VolumeNum,general_info_VoxelNum,SumVariance,Homogeneity1,Homogeneity2,ClusterShade,MaximumProbability,Idmn,SumVariance2,Contrast,DifferenceEntropy,InverseVariance,Entropy,Dissimilarity,DifferenceVariance,Idn,Idm,Correlation,Autocorrelation,SumEntropy,AverageIntensity,Energy,SumSquares,ClusterProminence,SumAverage,Imc2,Imc1,DifferenceAverage,Id,ClusterTendency
-brain1,"(162, 84, 11, 47, 70, 7)","{'verbose': False, 'voxelArrayShift': 2000, 'binWidth': 25, 'label': 1, 'interpolator': None, 'symmetricalGLCM': False, 'resampledPixelSpacing': None, 'gldm_a': 0, 'weightingNorm': None, 'padDistance': 5}",5c9ce3ca174f0f8324aa4d277e0fef82dc5ac566,"(0.7812499999999999, 0.7812499999999999, 6.499999999999998)",{'original': {}},9dc2c3137b31fd872997d92c9a92d5178126d9d3,0.post403.dev0+gd611f07,2,4137,880.02035299177419,0.28722572382985151,0.20022255640475706,19.605083427287216,0.008193101942105081,0.961402169623227,108.73139325453903,47.492125114429797,3.7440609780664209,0.19881884197093194,8.6484091908787004,5.2844687898663176,16.655637050270975,0.87260521573971694,0.20022255640475706,0.39219743588570566,289.54369940172597,5.354241321485615,16.60808368859043,0.003151601429689756,40.55236483913805,27995.937591943148,33.107615448855022,0.79188798671101246,-0.12298081261731311,5.2844687898663176,0.28722572382985151,108.73139325453907
-brain2,"(205, 155, 8, 20, 15, 3)","{'verbose': False, 'voxelArrayShift': 2000, 'binWidth': 25, 'label': 1, 'interpolator': None, 'symmetricalGLCM': False, 'resampledPixelSpacing': None, 'gldm_a': 0, 'weightingNorm': None, 'padDistance': 5}",f2b8fbc4d5d1da08a1a70e79a301f8a830139438,"(0.7812499999999999, 0.7812499999999999, 6.499999999999998)",{'original': {}},b41049c71633e194bee4891750392b72eabd8800,0.post403.dev0+gd611f07,1,453,866.27781882935483,0.34588791642687811,0.26177848833510498,127.13809223840238,0.0597732663763283,0.97092709086072326,42.317452064295658,29.293839050702996,3.3390497846557254,0.25338046923906615,6.2202489517449395,3.9826729595606403,11.757829127963504,0.89204192659477488,0.26177848833510498,0.31298362781586209,276.9390375378519,4.3841213671951538,17.596367643690353,0.021296604313774989,16.074173100898356,7743.448102798925,33.084919329182931,0.94806637990321463,-0.30140675421432073,3.9826729595606398,0.34588791642687811,42.317452064295665
-breast1,"(21, 64, 8, 9, 12, 3)","{'verbose': False, 'voxelArrayShift': 2000, 'binWidth': 25, 'label': 1, 'interpolator': None, 'symmetricalGLCM': False, 'resampledPixelSpacing': None, 'gldm_a': 0, 'weightingNorm': None, 'padDistance': 5}",016951a8f9e8e5de21092d9d62b77262f92e04a5,"(0.664062, 0.664062, 2.1)",{'original': {}},5aa7d57fd57e83125b605c036c40f4a0d0cfd3e4,0.post403.dev0+gd611f07,1,143,4.6550986374338823,0.73109230839874451,0.72442214443357622,-0.016711211805404854,0.29665628002001326,0.93749593957145183,1.1696127286855562,0.67121866250587736,1.1846976792586774,0.48362030098551811,2.713185137166831,0.5711662030283523,0.32725642574315206,0.86221107221678805,0.72442214443357622,0.28882475722469503,3.9663379593499664,2.0621987981343954,2.0314251665935505,0.18015057742115115,0.45588441376750161,3.2994515259044608,3.9170802211991651,0.46586325566090836,-0.10371357440316083,0.5711662030283523,0.73109230839874451,1.1696127286855562
-lung1,"(206, 347, 32, 24, 26, 3)","{'verbose': False, 'voxelArrayShift': 2000, 'binWidth': 25, 'label': 1, 'interpolator': None, 'symmetricalGLCM': False, 'resampledPixelSpacing': None, 'gldm_a': 0, 'weightingNorm': None, 'padDistance': 5}",34dca4200809a5e76c702d6b9503d958093057a3,"(0.5703125, 0.5703125, 5.0)",{'original': {}},054d887740012177bd1f9031ddac2b67170af0f3,0.post403.dev0+gd611f07,1,837,1316.3407814632699,0.41736196376573204,0.34435017672215545,-345.71336725148899,0.08912560596848712,0.97258239381784684,58.74756668430426,20.713449304070664,3.1875245017550018,0.27869716669593048,6.6556227958601175,3.2166030915302346,9.38199581278284,0.89963070737626616,0.34435017672215545,0.4968957940703928,411.4164748228452,4.6355019464777119,19.570210424032926,0.019550376521576325,21.652368580855146,9732.6943959902492,40.09024968089912,0.89429023840987421,-0.22722644766515582,3.2166030915302346,0.41736196376573204,58.747566684304267
-lung2,"(318, 333, 15, 87, 66, 11)","{'verbose': False, 'voxelArrayShift': 2000, 'binWidth': 25, 'label': 1, 'interpolator': None, 'symmetricalGLCM': False, 'resampledPixelSpacing': None, 'gldm_a': 0, 'weightingNorm': None, 'padDistance': 5}",14f57fd04838eb8c9cca2a0dd871d29971585975,"(0.6269531, 0.6269531, 5.0)",{'original': {}},e284ff05593bc6cb2747261882e452d4efbccb3a,0.post403.dev0+gd611f07,1,24644,4576.1798551755619,0.67488828052808181,0.65209771741148159,-498.73190629686474,0.32422085412558954,0.99472500276765008,28.339974380216191,12.115468558259831,2.1805601671536725,0.35136435757987061,4.3065420577384446,1.5501077045805824,9.4711179692288354,0.97084505602500215,0.65209771741148159,0.36291098448004738,1250.7846278881173,3.1809315369280782,35.275329629029159,0.15022980791791918,10.631815040073569,13254.853382802215,70.617306920893128,0.57027092518828848,-0.13541543952656429,1.5501077045805824,0.67488828052808181,28.339974380216198
+Patient ID,general_info_BoundingBox,general_info_GeneralSettings,general_info_ImageHash,general_info_ImageSpacing,general_info_InputImages,general_info_MaskHash,general_info_Version,general_info_VolumeNum,general_info_VoxelNum,Homogeneity1,Homogeneity2,ClusterShade,MaximumProbability,Idmn,SumVariance,Contrast,DifferenceEntropy,InverseVariance,Entropy,Dissimilarity,DifferenceVariance,Idn,Idm,Correlation,Autocorrelation,SumEntropy,AverageIntensity,Energy,SumSquares,ClusterProminence,SumAverage,Imc2,Imc1,DifferenceAverage,Id,ClusterTendency
+brain1,"(162, 84, 11, 47, 70, 7)","{'verbose': False, 'voxelArrayShift': 2000, 'binWidth': 25, 'label': 1, 'interpolator': None, 'symmetricalGLCM': False, 'resampledPixelSpacing': None, 'gldm_a': 0, 'weightingNorm': None, 'padDistance': 5}",5c9ce3ca174f0f8324aa4d277e0fef82dc5ac566,"(0.7812499999999999, 0.7812499999999999, 6.499999999999998)",{'original': {}},9dc2c3137b31fd872997d92c9a92d5178126d9d3,0.post403.dev0+gd611f07,2,4137,0.28722572382985151,0.20022255640475706,19.605083427287216,0.008193101942105081,0.961402169623227,108.73139325453903,47.492125114429797,3.7440609780664209,0.19881884197093194,8.6484091908787004,5.2844687898663176,16.655637050270975,0.87260521573971694,0.20022255640475706,0.39219743588570566,289.54369940172597,5.354241321485615,16.60808368859043,0.003151601429689756,40.55236483913805,27995.937591943148,33.107615448855022,0.79188798671101246,-0.12298081261731311,5.2844687898663176,0.28722572382985151,108.73139325453907
+brain2,"(205, 155, 8, 20, 15, 3)","{'verbose': False, 'voxelArrayShift': 2000, 'binWidth': 25, 'label': 1, 'interpolator': None, 'symmetricalGLCM': False, 'resampledPixelSpacing': None, 'gldm_a': 0, 'weightingNorm': None, 'padDistance': 5}",f2b8fbc4d5d1da08a1a70e79a301f8a830139438,"(0.7812499999999999, 0.7812499999999999, 6.499999999999998)",{'original': {}},b41049c71633e194bee4891750392b72eabd8800,0.post403.dev0+gd611f07,1,453,0.34588791642687811,0.26177848833510498,127.13809223840238,0.0597732663763283,0.97092709086072326,42.317452064295658,29.293839050702996,3.3390497846557254,0.25338046923906615,6.2202489517449395,3.9826729595606403,11.757829127963504,0.89204192659477488,0.26177848833510498,0.31298362781586209,276.9390375378519,4.3841213671951538,17.596367643690353,0.021296604313774989,16.074173100898356,7743.448102798925,33.084919329182931,0.94806637990321463,-0.30140675421432073,3.9826729595606398,0.34588791642687811,42.317452064295665
+breast1,"(21, 64, 8, 9, 12, 3)","{'verbose': False, 'voxelArrayShift': 2000, 'binWidth': 25, 'label': 1, 'interpolator': None, 'symmetricalGLCM': False, 'resampledPixelSpacing': None, 'gldm_a': 0, 'weightingNorm': None, 'padDistance': 5}",016951a8f9e8e5de21092d9d62b77262f92e04a5,"(0.664062, 0.664062, 2.1)",{'original': {}},5aa7d57fd57e83125b605c036c40f4a0d0cfd3e4,0.post403.dev0+gd611f07,1,143,0.73109230839874451,0.72442214443357622,-0.016711211805404854,0.29665628002001326,0.93749593957145183,1.1696127286855562,0.67121866250587736,1.1846976792586774,0.48362030098551811,2.713185137166831,0.5711662030283523,0.32725642574315206,0.86221107221678805,0.72442214443357622,0.28882475722469503,3.9663379593499664,2.0621987981343954,2.0314251665935505,0.18015057742115115,0.45588441376750161,3.2994515259044608,3.9170802211991651,0.46586325566090836,-0.10371357440316083,0.5711662030283523,0.73109230839874451,1.1696127286855562
+lung1,"(206, 347, 32, 24, 26, 3)","{'verbose': False, 'voxelArrayShift': 2000, 'binWidth': 25, 'label': 1, 'interpolator': None, 'symmetricalGLCM': False, 'resampledPixelSpacing': None, 'gldm_a': 0, 'weightingNorm': None, 'padDistance': 5}",34dca4200809a5e76c702d6b9503d958093057a3,"(0.5703125, 0.5703125, 5.0)",{'original': {}},054d887740012177bd1f9031ddac2b67170af0f3,0.post403.dev0+gd611f07,1,837,0.41736196376573204,0.34435017672215545,-345.71336725148899,0.08912560596848712,0.97258239381784684,58.74756668430426,20.713449304070664,3.1875245017550018,0.27869716669593048,6.6556227958601175,3.2166030915302346,9.38199581278284,0.89963070737626616,0.34435017672215545,0.4968957940703928,411.4164748228452,4.6355019464777119,19.570210424032926,0.019550376521576325,21.652368580855146,9732.6943959902492,40.09024968089912,0.89429023840987421,-0.22722644766515582,3.2166030915302346,0.41736196376573204,58.747566684304267
+lung2,"(318, 333, 15, 87, 66, 11)","{'verbose': False, 'voxelArrayShift': 2000, 'binWidth': 25, 'label': 1, 'interpolator': None, 'symmetricalGLCM': False, 'resampledPixelSpacing': None, 'gldm_a': 0, 'weightingNorm': None, 'padDistance': 5}",14f57fd04838eb8c9cca2a0dd871d29971585975,"(0.6269531, 0.6269531, 5.0)",{'original': {}},e284ff05593bc6cb2747261882e452d4efbccb3a,0.post403.dev0+gd611f07,1,24644,0.67488828052808181,0.65209771741148159,-498.73190629686474,0.32422085412558954,0.99472500276765008,28.339974380216191,12.115468558259831,2.1805601671536725,0.35136435757987061,4.3065420577384446,1.5501077045805824,9.4711179692288354,0.97084505602500215,0.65209771741148159,0.36291098448004738,1250.7846278881173,3.1809315369280782,35.275329629029159,0.15022980791791918,10.631815040073569,13254.853382802215,70.617306920893128,0.57027092518828848,-0.13541543952656429,1.5501077045805824,0.67488828052808181,28.339974380216198

docs/faq.rst

@@ -10,6 +10,18 @@ Installation
 This can occur when no compiler is available for python. If you're installing on Windows, you can find free compilers
 for python `here <https://wiki.python.org/moin/WindowsCompilers>`_.
 
+**I installed PyRadiomics successfully from the repository, but when I run the notebook, I get** ``Error loading C
+extensions, switching to python calculation``
+
+When PyRadiomics is installed, the C extensions are compiled and copied to the installation folder, by default the
+``site-packages`` folder. However, when the notebook is run form the repository, it is possible that PyRadiomics uses
+the source code directly (i.e. runs in development mode). You can check this by checking the ``radiomics.__path__``
+field, which will be something like ``['radiomics']`` when it is running in development mode and
+``['path/to/python/Lib/site-packages']`` when running from the installed folder. If running in development mode, the C
+extensions are not available by default. To make them available in development mode, run ``python setup.py develop``
+from the commandline, which is similar to the ``install`` command, but installs pyradiomics to the source folder
+instead (i.e. does nothing to the python files, but compiles the C extensions and copies them to the source folder).
+
 **Which python versions is PyRadiomics compatible with?**
 
 PyRadiomics is compatible with both python 2 and python 3. The automated testing uses python versions 2.7, 3.4 and 3.5
@@ -27,6 +39,12 @@ custom settings and which features and input image types to enable. Possible gen
 types are documented :ref:`here <radiomics-featureextractor-label>`, with additional feature class specific settings
 documented at the start of the :ref:`feature class <radiomics-features-label>`.
 
+**When I try to load my own parameter file, I get error:"CoreError: Unable to load any data from source yaml file"**
+
+This error is thrown by PyKwalify when it is unable to read the parameter file. The most common cause is when the file
+is indented using tabs, which throws a "token ('\t') not recognized error". Instead, ensure that all indentations are
+made using 2 or 4 spaces.
+
 **What file types are supported by PyRadiomics for input image and mask?**
 
 PyRadiomics uses SimpleITK for image loading and handling. Therefore, all image types supported by SimpleITK can be

docs/features.rst

@@ -8,8 +8,8 @@ This section contains the definitions of the various features that can be extrac
 subdivided into the following classes:
 
 * :ref:`radiomics-firstorder-label` (19 features)
-* :ref:`radiomics-shape-label` (13 features)
-* :ref:`radiomics-glcm-label` (28 features)
+* :ref:`radiomics-shape-label` (16 features)
+* :ref:`radiomics-glcm-label` (27 features)
 * :ref:`radiomics-glszm-label` (16 features)
 * :ref:`radiomics-glrlm-label` (16 features)
 

docs/index.rst

@@ -50,7 +50,7 @@ Currently supports the following feature classes:
 * :ref:`Gray Level Run Length Matrix <radiomics-glrlm-label>` (GLRLM)
 * :ref:`Gray Level Size Zone Matrix <radiomics-glszm-label>` (GLSZM)
 
-On average, Pyradiomics extracts :math:`\approx 1300` features per image, which consist of the 13 shape descriptors and
+On average, Pyradiomics extracts :math:`\approx 1300` features per image, which consist of the 16 shape descriptors and
 features extracted from original and derived images (LoG with 5 sigma levels, 1 level of Wavelet decomposistions
 yielding 8 derived images and images derived using Square, Square Root, Logarithm and Exponential filters).
 
@@ -105,8 +105,8 @@ PyRadiomics is OS independent and compatible with both Python 2.7 and Python >=3
 * Install on your system (Linux, Mac OSX), with prerequisites:
 
   * ``cd pyradiomics``
-  * ``sudo python -m pip install -r requirements.txt``
-  * ``sudo python setup.py install``
+  * ``python -m pip install -r requirements.txt``
+  * ``python setup.py install``
 
 * For more detailed installation instructions and installation on Windows see
   :ref:`Installation Details<installation-label>`

docs/installation.rst

@@ -23,11 +23,11 @@ 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``
+  * ``python -m pip install -r requirements.txt``
+  * ``python setup.py install``
 
   To use your build for interactive use and development:
-  * ``sudo python setup.py develop``
+  * ``python setup.py develop``
 
   * 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::