ENH: Add CLI scripts to setup

Rename the scripts to pyradiomics and pyradiomicsbatch (easy to remeber, but unique to package, for use in the commandline). Additionally, move them to separate folder in the package, and add them to the setup script so the CLI gets distributed with the installation, not just the git repo.
Additionally, add the use of these scripts to the `Usage` section of the documentation and adapt this section further to represent the more standard use of the toolbox, including interactive extraction using the `featureextractor` module.

Finally, adapt the examples in the bin folder to make use of the example data stored in the repository, this removes the need to install the example data when pyradiomics is installed.

Author: JoostJM

bin/Notebooks/helloFeatureClass.ipynb

@@ -38,6 +38,17 @@
     "## Getting the test case"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Testing data is contained in the pyradiomics/data folder, while this file is in the pyradiomics/bin/Notebooks folder. \n",
+    "\n",
+    "The next line of code gets the location of the current path and gets the location of the data as a relative path by going up two folders (os.path.sep + \"..\") and then move into the data folders (os.path.sep + \"data\").\n",
+    "\n",
+    "For this to work, the current active directory should be pyradiomics/bin/notebooks, which is the case if this file is run from the pyradiomics/bin/Notebooks folder."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 2,

bin/Notebooks/helloRadiomics.ipynb

@@ -77,6 +77,17 @@
     "## Getting the testcase"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Testing data is contained in the pyradiomics/data folder, while this file is in the pyradiomics/bin/Notebooks folder. \n",
+    "\n",
+    "The next line of code gets the location of the current path and gets the location of the data as a relative path by going up two folders (os.path.sep + \"..\") and then move into the data folders (os.path.sep + \"data\").\n",
+    "\n",
+    "For this to work, the current active directory should be pyradiomics/bin/notebooks, which is the case if this file is run from the pyradiomics/bin/Notebooks folder."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 3,
@@ -86,7 +97,7 @@
    "outputs": [],
    "source": [
     "testCase = 'brain1'\n",
-    "dataDir = os.path.abspath(radiomics.__path__[0] + os.path.sep + \"..\" + os.path.sep + \"data\")\n",
+    "dataDir = os.path.abspath(\"\") + os.path.sep + \"..\" + os.path.sep + \"..\" + os.path.sep + \"data\"\n",
     "imageName = str(dataDir + os.path.sep + testCase +'_image.nrrd')\n",
     "maskName = str(dataDir + os.path.sep + testCase + '_label.nrrd')\n",
     "\n",
@@ -421,7 +432,7 @@
       "Computed general_info_ImageSpacing: (0.7812499999999999; 0.7812499999999999; 6.499999999999998)\n",
       "Computed general_info_InputImages: {'original': {}}\n",
       "Computed general_info_MaskHash: 9dc2c3137b31fd872997d92c9a92d5178126d9d3\n",
-      "Computed general_info_Version: 0.post402.dev0+gb4e35ec\n",
+      "Computed general_info_Version: v1.0.post11.dev0+g610dffc\n",
       "Computed general_info_VolumeNum: 2\n",
       "Computed general_info_VoxelNum: 4137\n",
       "Computed original_firstorder_InterquartileRange: 253.0\n",
@@ -453,6 +464,17 @@
     "for featureName in featureVector.keys():\n",
     "  print \"Computed %s: %s\" % (featureName, featureVector[featureName])"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    ""
+   ]
   }
  ],
  "metadata": {

bin/helloFeatureClass.py

@@ -4,9 +4,9 @@
 from radiomics import firstorder, glcm, imageoperations, shape, glrlm, glszm
 
 # testBinWidth = 25 this is the default bin size
-# testResampledPixelSpacing = (3,3,3) no resampling for now.
+# testResampledPixelSpacing = [3,3,3] no resampling for now.
 
-dataDir = os.path.dirname(os.path.abspath(__file__)) + os.path.sep + ".." + os.path.sep + "data"
+dataDir = os.path.abspath("") + os.path.sep + ".." + os.path.sep + "data"  # assumes this file in in pyradiomics/bin
 # imageName = str(dataDir + os.path.sep + 'prostate_phantom_subvolume.nrrd')
 # maskName = str(dataDir + os.path.sep + 'prostate_phantom_subvolume-label.nrrd')
 imageName = str(dataDir + os.path.sep + 'breast1_image.nrrd')

bin/helloRadiomics.py

@@ -4,7 +4,7 @@
 from radiomics import featureextractor
 import radiomics
 
-dataDir = os.path.dirname(os.path.abspath(__file__)) + os.path.sep + ".." + os.path.sep + "data"
+dataDir = os.path.abspath("") + os.path.sep + ".." + os.path.sep + "data"  # assumes this file in in pyradiomics/bin
 # imageName = str(dataDir + os.path.sep + 'prostate_phantom_subvolume.nrrd')
 # maskName = str(dataDir + os.path.sep + 'prostate_phantom_subvolume-label.nrrd')
 imageName = str(dataDir + os.path.sep + 'brain1_image.nrrd')

docs/usage.rst

@@ -6,15 +6,95 @@ Usage
 Example
 -------
 
-* Run the helloRadiomics example, using sample data provided in ``pyradiomics/data``:
+* PyRadiomics example code and data is available in the `Github repository <https://github.com/Radiomics/pyradiomics>`_
+
+* The sample sample data is provided in ``pyradiomics/data``.
+
+* Use jupyter to run the helloRadiomics example, located in ``pyradiomics/bin/Notebooks``.
+
+* If jupyter is not installed, run the python script alternative (``pyradiomics/bin/helloRadiomics.py``):
+
+  * ``python helloRadiomics.py``
+
+----------------
+Command Line Use
+----------------
+
+* PyRadiomics has 2 commandline scripts, ``pyradiomics`` is for single image feature extraction and ``pyradiomicsbatch``
+  is for feature extraction from a batch of images and segmentations.
+
+* Both scripts can be run directly from a command line window, anywhere in your system.
+
+* To extract features from a single image and segmentation run::
+
+    pyradiomics <path/to/image> <path/to/segmentation>
+
+* To extract features from a batch run::
+
+    pyradiomicsbatch <path/to/input> <path/to/output>
+
+* The input file for batch processing is a CSV file where each row represents one combination of an image and a
+  segmentation and contains 5 elements: 1) patient ID, 2) sequence name (image identifier), 3) reader (segmentation
+  identifier), 4) path/to/image, 5) path/to/mask.
+
+* For more information on passing parameter files, setting up logging and controlling output format, run::
+
+    pyradiomics -h
+    pyradiomicsbatch -h
 
-  * ``python bin/helloRadiomics.py``
 
 ---------------
 Interactive Use
 ---------------
 
-* Add pyradiomics to the environment variable PYTHONPATH:
+* (LINUX) Add pyradiomics to the environment variable PYTHONPATH:
+
+  *  ``setenv PYTHONPATH /path/to/pyradiomics/radiomics``
+
+* Start the python interactive session:
+
+  * ``python``
+
+* Import the necessary classes::
+
+     from radiomics import featureextractor
+     import sys, os
+
+* Set up a pyradiomics directory variable::
+
+    dataDir = '/path/to/pyradiomics'
+
+* You will find sample data files brain1_image.nrrd and brain1_label.nrrd in that directory.
+
+* Store the path of your image and mask in two variables::
+
+    imageName = os.path.join(dataDir, "data", 'brain1_image.nrrd')
+    maskName = os.path.join(dataDir, "data",  'brain1_label.nrrd')
+
+* Also store the path to the file containing the extraction settings::
+
+    params = os.path.join(dataDir, "bin", "Params.yaml")
+
+* Instantiate the feature extractor class with the parameter file::
+
+    extractor = featureextractor.RadiomicsFeaturesExtractor(params)
+
+* Calculate the features::
+
+    result = extractor.execute(imageName, maskName)
+    for key, val in result.iteritems():
+      print "\t%s: %s" %(key, val)
+
+* See the :ref:`feature extractor class<radiomics-featureextractor-label>` for more information on using this core class.
+
+------------------------------
+Using feature classes directly
+------------------------------
+
+* This represents an example where feature classes are used directly, circumventing checks and preprocessing done by
+  the radiomics feature extractor class, and is not intended as standard use example.
+
+* (LINUX) Add pyradiomics to the environment variable PYTHONPATH:
 
   *  ``setenv PYTHONPATH /path/to/pyradiomics/radiomics``
 
@@ -46,6 +126,6 @@ Interactive Use
      firstOrderFeatures = firstorder.RadiomicsFirstOrder(image,mask)
      firstOrderFeatures.calculateFeatures()
      for (key,val) in firstOrderFeatures.featureValues.iteritems():
-       print '  ',key,':',val
+       print "\t%s: %s" % (key, val)
 
 * See the :ref:`radomics package<radiomics-firstorder-label>` for more features that you can calculate.

radiomics/scripts/__init__.py

@@ -1,3 +1,5 @@
+#!/usr/bin/env python
+
 import argparse
 import sys
 import os.path

bin/commandline.py radiomics/scripts/commandline.pybin/commandline.py renamed to radiomics/scripts/commandline.py

@@ -1,3 +1,5 @@
+#!/usr/bin/env python
+
 import argparse
 import sys
 import os.path
@@ -73,6 +75,7 @@ def main():
   # Extract features
   logging.info('Extracting features with kwarg settings: %s', str(extractor.kwargs))
 
+  headers = False
   for idx, entry in enumerate(flists, start=1):
 
     logging.info("(%d/%d) Processing Patient: %s, Study: %s, Reader: %s", idx, len(flists), entry[0], entry[1],
@@ -94,7 +97,9 @@ def main():
 
         if args.format == 'csv':
           writer = csv.writer(args.outFile, lineterminator='\n')
-          if idx == 1: writer.writerow(featureVector.keys())
+          if not headers:
+            writer.writerow(featureVector.keys())
+            headers = True
           writer.writerow(featureVector.values())
         elif args.format == 'json':
           json.dump(featureVector, args.out)

bin/batchExamples/commandlinebatch.py radiomics/scripts/commandlinebatch.pybin/batchExamples/commandlinebatch.py renamed to radiomics/scripts/commandlinebatch.py

@@ -8,9 +8,11 @@
 setup(name='pyradiomics',
       version=versioneer.get_version(),
       cmdclass=versioneer.get_cmdclass(),
-      packages=['radiomics'],
+      packages=['radiomics', 'radiomics.scripts'],
+      entry_points={'console_scripts': ['pyradiomics=radiomics.scripts.commandline:main',
+                                        'pyradiomicsbatch=radiomics.scripts.commandlinebatch:main']},
       data_files=[
-        ('data', ['data/paramSchema.yaml', 'data/schemaFuncs.py', 'data/brain1_image.nrrd', 'data/brain1_label.nrrd'])],
+        ('data', ['data/paramSchema.yaml', 'data/schemaFuncs.py'])],
       description='Radiomics features library for python',
       url='http://github.com/Radiomics/pyradiomics',
       author='pyradiomics community',