heuristic option: sequence names remappings and other control

[yarikoptic]

ATM, as the heuristic was developed, we addressed some user errors by providing

• per-study list of regular expressions on how sequences should be renamed to fit our convention: https://github.com/nipy/heudiconv/blob/master/heudiconv/heuristics/reproin.py#L158
• per-accession list of regular expressions on which sequences to skip (canceled runs etc)

IIRC We also restricted at some point which accessions (based on regex) to consider at all. Might be an option useful in some cases, especially whenever "monitoring" would become available

Such remapping could be generalized further to make reproin heuristic usable for many (if not any) already collected datasets, where people would simply provide remapping into ReproIn specification, as the intermediate specification to arrive to BIDS by using reproin heuristic.

May be both of the above cases could be generalized so a single specification of what to be remapped to what and when could exist. Check on how done in http://imaging-docs.cbbs.eu which also work toward similar goal/approach

[yarikoptic]

Here is an example from one of the local studies on how to provide an "overload" on top of reproin to provide desired renamings and possibly overrides of different aspects of the heuristic:

# Provide mapping into reproin heuristic names

from heudiconv.heuristics import reproin

from heudiconv.heuristics.reproin import *

protocols2fix.update({
    '':  # for any study given.  Needs recent heudiconv e.g. >= 0.9.0
        [
            # All those come untested and correspond to some older pilot runs
            # regular expression, what to replace with
            ('AAHead_Scout_.*', 'anat-scout'),
            ('^dti_.*', 'dwi'),
            ('^space_top_distortion_corr.*_([ap]+)_([12])', r'fmap-epi_dir-\1_run-\2'),
            # I do not think there is a point in keeping any
            # of _ap _32ch _mb8 in the output filename, although
            # could be brought into _acq- if very much desired OR
            # there are some subjects/sessions scanned differently
            ('^(.+)_ap.*_r(0[0-9])', r'func_task-\1_run-\2'),
            # also the same as above...
            ('^t1w_.*', 'anat-T1w'),
            # below are my guesses based on what I saw in README
            ('_r(0[0-9])', r'_run-\1'),
            ('self_other', 'selfother'),

            # For more recent runs:
            # pepolar for DWI -- upper cased, so let's just do manually for each
            # Added  _acq-96dir-6b0-mb  so matches the one in DWI
            ('dwi_acq-discorr-PA', r'fmap-epi_dir-pa_acq-96dir-6b0-mb'),
            ('dwi_acq-discorr-AP', r'fmap-epi_dir-ap_acq-96dir-6b0-mb'),
            # pepolar for fMRI
            # problematic case -- multiple identically named pepolar fieldmap runs
            # I guess we will just sacrifice ability to detect canceled runs here.
            # And we cannot just use _run+ since it would increment indepdently
            # for ap and then for pa.  We will rely on having ap preceding pa.
            # Added  _acq-mb8  so they match the one in funcs
            ('func_task-discorr_acq-ap', r'fmap-epi_dir-ap_acq-mb8_run+'),
            ('func_task-discorr_acq-pa', r'fmap-epi_dir-pa_acq-mb8_run='),
            # but removing -ap in funcs so we do not introduce non-matching _acq
            ('_acq-ap-mb8', '_acq-mb8'),
        ],
})

# We need to overload to be able to feed scans from varying
# accessions as for ses02 tasks being scanned in ses04.
# Fix to reproin sent in https://github.com/nipy/heudiconv/pull/508
def fix_canceled_runs(seqinfo):
    return seqinfo
reproin.fix_canceled_runs = fix_canceled_runs

just save into a file, e.g "myreproin.py" and point heudiconv -f myreproin.py to it. Good strategy to just place it under e.g. .heudiconv/heudiconv_heuristic.py within the target BIDS datasets itself to contain the "provenance" on how it was all remapped alongside with your data.