heudiconv documentation

[Islast]

I'm looking for heudiconv documentation. I have been able to find only a slide show demonstration of using the heudiconv docker image (http://nipy.org/heudiconv), the explanation in the readme and the output of heudiconv -h.

Is there any better documentation for heudiconv?
For example is there somewhere I can find details about what the -q flag does? Or if and how the -bids flag adds a TaskName key to json files (mentioned in PR #50 )?

[mgxd]

@Islast there is also a video tutorial and a walkthrough!

• The -q flag is used to submit jobs through a job scheduler (initially just SLURM, but it can be ported for a variety of schedulers)
• The --bids flag adds TaskName to the sidecar JSON by parsing the bold path - it will extract whatever you specified in the task-<> field. This can later be edited and was added to avoid bids-validator failures IIRC.

[Islast]

Thank you @mgxd your help is appreciated 👍

Thank you for answering about the -q and -b options, although my question about the -q flag should have been better stated. It is clear from the command line help that the -q flag submits jobs to a job scheduler. What is unclear is what variable I am supposed to pass to -q. The name of my job scheduler? The name of my partition? I'm pretty sure that it is the latter (from queue.py and cli/run.py) but I can't find any documentation for this use case.

heudiconv/heudiconv/queue.py

Lines 9 to 35 in be86828

	def queue_conversion(progname, queue, outdir, heuristic, dicoms, sid,
	anon_cmd, converter, session,with_prov, bids):
	# Rework this...
	convertcmd = ' '.join(['python', progname,
	'-o', outdir,
	'-f', heuristic,
	'-s', sid,
	'--anon-cmd', anon_cmd,
	'-c', converter])
	if session:
	convertcmd += " --ses '%s'" % session
	if with_prov:
	convertcmd += " --with-prov"
	if bids:
	convertcmd += " --bids"
	if dicoms:
	convertcmd += " --files"
	convertcmd += [" '%s'" % f for f in dicoms]
	script_file = 'dicom-%s.sh' % sid
	with open(script_file, 'wt') as fp:
	fp.writelines(['#!/bin/bash\n', convertcmd])
	outcmd = 'sbatch -J dicom-%s -p %s -N1 -c2 --mem=20G %s' \
	% (sid, queue, script_file)
	os.system(outcmd)

heudiconv/heudiconv/cli/run.py

Lines 283 to 305 in be86828

	if args.queue:
	if seqinfo and not dicoms:
	# flatten them all and provide into batching, which again
	# would group them... heh
	dicoms = sum(seqinfo.values(), [])
	raise NotImplementedError(
	"we already grouped them so need to add a switch to avoid "
	"any grouping, so no outdir prefix doubled etc")
	progname = op.abspath(inspect.getfile(inspect.currentframe()))
	queue_conversion(progname,
	args.queue,
	study_outdir,
	heuristic.filename,
	dicoms,
	sid,
	args.anon_cmd,
	args.converter,
	session,
	args.with_prov,
	args.bids)
	continue

I suppose my broader feedback is that the slides, video and walkthrough tutorial all work for a particular use case (which is pretty common and I understand why they were developed) but they don't cover all the things that heudiconv can do. It would be really great to have some readthedocs style documentation for additional use cases. Or maybe a few examples in the README file of what the different options in the CLI can do.

I can submit a pull request with your answer to the --bids question if you can tell me where you'd like to keep that documentation!

[mgxd]

What is unclear is what variable I am supposed to pass to -q. The name of my job scheduler? The name of my partition?

The name of the SLURM partition

It would be really great to have some readthedocs style documentation for additional use cases

I agree, there are a few "hidden gems" within the tool - I'll see if I can find some time to devote to this in the coming months. In the meantime, if you (or anyone reading this issue) would like to kick off the documentation process and document some of the more well-known arguments and usage, we would be very thankful!