Add --skiptop flag to prevent writing top level bids files

This is useful in batch processing to prevent potential race
conditions. The batch processing example has also been
modified to use this flag.

Author: Steven Tilley

docs/usage.rst

@@ -43,6 +43,12 @@ DICOMs as an independent ``heudiconv`` execution.
 The first script aggregates the DICOM directories and submits them to
 ``run_heudiconv.sh`` with SLURM as a job array.
 
+If using bids, the ``--skiptop`` flag suppresses creation of top-level
+files in the bids directory (e.g., ``dataset_description.json``) to
+avoid possible race conditions.  These files may be generated later
+with ``populate_templates.sh`` below (except for ``participants.tsv``,
+which must be create manually).
+
 .. code:: shell
 
     #!/bin/bash
@@ -76,7 +82,22 @@ The second script processes a DICOM directory with ``heudiconv`` using the built
     echo Submitted directory: ${DCMDIR}
 
     IMG="/singularity-images/heudiconv-0.5.4-dev.sif"
-    CMD="singularity run -B ${DCMDIR}:/dicoms:ro -B ${OUTDIR}:/output -e ${IMG} --files /dicoms/ -o /output -f reproin -c dcm2niix -b --minmeta -l ."
+    CMD="singularity run -B ${DCMDIR}:/dicoms:ro -B ${OUTDIR}:/output -e ${IMG} --files /dicoms/ -o /output -f reproin -c dcm2niix -b --minmeta -l . --skiptop"
+
+    printf "Command:\n${CMD}\n"
+    ${CMD}
+    echo "Successful process"
+
+This script creates the top-level bids files (e.g.,
+``dataset_description.json``)
+
+..code:: shell
+    #!/bin/bash
+    set -eu
+
+    OUTDIR=${1}
+    IMG="/singularity-images/heudiconv-0.5.4-dev.sif"
+    CMD="singularity run -B ${OUTDIR}:/output -e ${IMG} --files /output -f reproin --command populate-templates"
 
     printf "Command:\n${CMD}\n"
     ${CMD}

heudiconv/cli/run.py

@@ -222,6 +222,10 @@ def get_parser():
                             help='Additional queue arguments passed as '
                             'single string of Argument=Value pairs space '
                             'separated.')
+    parser.add_argument('--skiptop', action='store_true',
+                        help='Skip creating of top-level bids files. '
+                        'Useful when running in batch mode to prevent '
+                        'possible race conditions.')
     return parser
 
 
@@ -320,7 +324,8 @@ def process_args(args):
                         seqinfo=seqinfo,
                         min_meta=args.minmeta,
                         overwrite=args.overwrite,
-                        dcmconfig=args.dcmconfig,)
+                        dcmconfig=args.dcmconfig,
+                        skiptop=args.skiptop,)
 
         lgr.info("PROCESSING DONE: {0}".format(
             str(dict(subject=sid, outdir=study_outdir, session=session))))

heudiconv/convert.py

@@ -80,7 +80,7 @@ def conversion_info(subject, outdir, info, filegroup, ses):
 
 def prep_conversion(sid, dicoms, outdir, heuristic, converter, anon_sid,
                    anon_outdir, with_prov, ses, bids, seqinfo, min_meta,
-                   overwrite, dcmconfig):
+                   overwrite, dcmconfig, skiptop):
     if dicoms:
         lgr.info("Processing %d dicoms", len(dicoms))
     elif seqinfo:
@@ -201,7 +201,7 @@ def prep_conversion(sid, dicoms, outdir, heuristic, converter, anon_sid,
     for item_dicoms in filegroup.values():
         clear_temp_dicoms(item_dicoms)
 
-    if bids:
+    if bids and not skiptop:
         if seqinfo:
             keys = list(seqinfo)
             add_participant_record(anon_outdir,