Merge pull request #130 from dartmouth-pbs/rf-heuristics-inside

RF+ENH: Move heuristics/ to become a heudiconv.heuristics submodule

Author: yarikoptic

.travis.yml

@@ -36,7 +36,7 @@ install:
   - git config --global user.name "Travis Almighty"
 
 script:
-  - coverage run `which py.test` -s -v tests heuristics/*.py
+  - coverage run `which py.test` -s -v tests heudiconv/heuristics/*.py
 
 after_success:
   - codecov

CHANGELOG.md

@@ -14,6 +14,7 @@ First release after major refactor
 - `Dockerfile` is generated by [neurodocker](https://github.com/kaczmarj/neurodocker)
 - Logging verbosity reduced
 - Increased leniency with missing DICOM fields
+- dbic_bids heuristic renamed into reproin
 ### Removed
 ### Deprecated
 ### Fixed

Makefile

@@ -25,7 +25,7 @@ provided to address various use-cases
 
 - the [cmrr_heuristic](heuristics/cmrr_heuristic.py) provides an
   example for a conversion to [BIDS]
-- the [dbic_bids](heuristics/dbic_bids.py) could be used to establish
+- the [reproin](heuristics/reproin.py) could be used to establish
   a complete imaging center wide automation to convert all acquired
   data to [BIDS] following a simple naming
   [convention](https://goo.gl/o0YASC) for studies and sequences
@@ -35,19 +35,19 @@ provided to address various use-cases
 ### Released versions
 
 Released versions of HeuDiConv are available from PyPI so you could
-just `pip install heudiconv` but it would require manual installation
+just `pip install heudiconv[all]` for the most complete installation, 
+and it would require manual installation ony
 of the [dcm2niix](https://github.com/rordenlab/dcm2niix/).  On
 Debian-based systems we recommend to use
 [NeuroDebian](http://neuro.debian.net) providing
 [heudiconv Debian package](http://neuro.debian.net/pkgs/heudiconv.html).
 
 ### From source
 
-You can clone this directory and do a `make install`
+You can clone this directory and use `pip install .[all]` (with `--user`,
+`-e` and other flags appropriate for your case), or
 
-or `pip install https://github.com/nipy/heudiconv/archive/master.zip`
-
-as long as the following dependencies are in your path you can use the package
+`pip install https://github.com/nipy/heudiconv/archive/master.zip`
 
 ## Dependencies
 
@@ -57,6 +57,10 @@ as long as the following dependencies are in your path you can use the package
 - nibabel
 - dcm2niix
 
+and should be checked/installed during `pip install` call, all but `dcm2niix`
+which should be installed directly from upstream or using the distribution
+manager appropriate for your OS.
+
 ## Tutorial with example conversion to BIDS format using Docker
 Please read this tutorial to understand how heudiconv works in practice.
 

README.md

@@ -60,7 +60,7 @@ def process_extra_commands(outdir, args):
         for f in args.files:
             treat_infofile(f)
     elif args.command == 'ls':
-        heuristic = load_heuristic(op.realpath(args.heuristic_file))
+        heuristic = load_heuristic(args.heuristic)
         heuristic_ls = getattr(heuristic, 'ls', None)
         for f in args.files:
             study_sessions = get_study_sessions(
@@ -76,11 +76,21 @@ def process_extra_commands(outdir, args):
                     % (str(study_session), len(sequences), suf)
                 )
     elif args.command == 'populate-templates':
-        heuristic = load_heuristic(op.realpath(args.heuristic_file))
+        heuristic = load_heuristic(args.heuristic)
         for f in args.files:
             populate_bids_templates(f, getattr(heuristic, 'DEFAULT_FIELDS', {}))
     elif args.command == 'sanitize-jsons':
         tuneup_bids_json_files(args.files)
+    elif args.command == 'heuristics':
+        from ..utils import get_known_heuristics_with_descriptions
+        for name_desc in get_known_heuristics_with_descriptions().items():
+            print("- %s: %s" % name_desc)
+    elif args.command == 'heuristic-info':
+        from ..utils import get_heuristic_description, get_known_heuristic_names
+        if not args.heuristic:
+            raise ValueError("Specify heuristic using -f. Known are: %s"
+                             % ', '.join(get_known_heuristic_names()))
+        print(get_heuristic_description(args.heuristic, full=True))
     else:
         raise ValueError("Unknown command %s", args.command)
     return
@@ -149,9 +159,11 @@ def get_parser():
                         'DICOMs to anonymized IDs. Such command must take a '
                         'single argument and return a single anonymized ID. '
                         'Also see --conv-outdir')
-    parser.add_argument('-f', '--heuristic', dest='heuristic_file',
-                        required=True,
-                        help='python script containing heuristic')
+    parser.add_argument('-f', '--heuristic', dest='heuristic',
+                        # some commands might not need heuristic
+                        # required=True,
+                        help='Name of a known heuristic or path to the Python'
+                             'script containing heuristic')
     parser.add_argument('-p', '--with-prov', action='store_true',
                         help='Store additional provenance information. '
                         'Requires python-rdflib.')
@@ -174,8 +186,11 @@ def get_parser():
                         help='Do not catch exceptions and show exception '
                         'traceback')
     parser.add_argument('--command',
-                        choices=('ls', 'populate-templates',
-                                 'treat-jsons', 'sanitize-jsons'),
+                        choices=(
+                            'heuristics', 'heuristic-info',
+                            'ls', 'populate-templates',
+                            'sanitize-jsons', 'treat-jsons',
+                        ),
                         help='custom actions to be performed on provided '
                         'files instead of regular operation.')
     parser.add_argument('-g', '--grouping', default='studyUID',
@@ -203,19 +218,20 @@ def process_args(args):
     # pre-process provided list of files and possibly sort into groups/sessions
     # Group files per each study/sid/session
 
-    lgr.info(INIT_MSG(packname=__packagename__,
-                      version=__version__))
-
     outdir = op.abspath(args.outdir)
 
     if args.command:
         process_extra_commands(outdir, args)
         return
 
+    lgr.info(INIT_MSG(packname=__packagename__,
+                      version=__version__))
+
+
     #
     # Load heuristic -- better do it asap to make sure it loads correctly
     #
-    heuristic = load_heuristic(op.realpath(args.heuristic_file))
+    heuristic = load_heuristic(args.heuristic)
 
     study_sessions = get_study_sessions(args.dicom_dir_template, args.files,
                                         heuristic, outdir, args.session,