From cd55bf0a953dd28668335df42a49848e6213c9b6 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Fri, 10 Apr 2020 19:57:18 +0200
Subject: [PATCH 01/20] Start from 1 in run numeration

---
 phys2bids/heuristics/heur_test_acq.py | 2 +-
 phys2bids/heuristics/heur_tutorial.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/phys2bids/heuristics/heur_test_acq.py b/phys2bids/heuristics/heur_test_acq.py
index eb8ba67d1..d065451db 100644
--- a/phys2bids/heuristics/heur_test_acq.py
+++ b/phys2bids/heuristics/heur_test_acq.py
@@ -18,7 +18,7 @@ def heur(physinfo, name, task='', acq='', direct='', rec='', run=''):
 
     if fnmatch.fnmatchcase(physinfo, '*samefreq*'):
         task = 'test'
-        run = '00'
+        run = '01'
         rec = 'biopac'
     elif physinfo == 'Example':
         task = 'rest'
diff --git a/phys2bids/heuristics/heur_tutorial.py b/phys2bids/heuristics/heur_tutorial.py
index e4fad14e7..4a6855444 100644
--- a/phys2bids/heuristics/heur_tutorial.py
+++ b/phys2bids/heuristics/heur_tutorial.py
@@ -18,7 +18,7 @@ def heur(physinfo, name, task='', acq='', direct='', rec='', run=''):
 
     if fnmatch.fnmatchcase(physinfo, '*tutorial*'):
         task = 'test'
-        run = '00'
+        run = '01'
         rec = 'labchart'
     elif physinfo == 'Example':
         task = 'rest'

From 38a7142b69875007630014b7bf06fa06c7ee8ca6 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Fri, 10 Apr 2020 20:00:05 +0200
Subject: [PATCH 02/20] Delete heur_ex and heur

---
 phys2bids/heuristics/heur.py    | 73 ---------------------------------
 phys2bids/heuristics/heur_ex.py | 57 -------------------------
 2 files changed, 130 deletions(-)
 delete mode 100644 phys2bids/heuristics/heur.py
 delete mode 100644 phys2bids/heuristics/heur_ex.py

diff --git a/phys2bids/heuristics/heur.py b/phys2bids/heuristics/heur.py
deleted file mode 100644
index 0091a0b1f..000000000
--- a/phys2bids/heuristics/heur.py
+++ /dev/null
@@ -1,73 +0,0 @@
-# import sys
-import fnmatch
-
-
-def heur(physinfo, name, task='', acq='', direct='', rec='', run=''):
-    # ############################## #
-    # ##       Modify here!       ## #
-    # ##                          ## #
-    # ##  Possible variables are: ## #
-    # ##    -task (required)      ## #
-    # ##    -run                  ## #
-    # ##    -rec                  ## #
-    # ##    -acq                  ## #
-    # ##    -direct               ## #
-    # ##                          ## #
-    # ##                          ## #
-    # ##    See example below     ## #
-    # ############################## #
-
-    if physinfo == 'origfilename1':
-        task = 'newname1'
-    elif physinfo == 'origfilename2':
-        task = 'newname2'
-        run = 'runnum'
-    elif physinfo == 'BH4':
-        task = 'breathhold'
-    elif fnmatch.fnmatchcase(physinfo, 'MOTOR?'):
-        task = 'motor'
-    elif fnmatch.fnmatchcase(physinfo, 'LOCALIZER?'):
-        task = 'pinel'
-    elif fnmatch.fnmatchcase(physinfo, 'SIMON?'):
-        task = 'simon'
-    elif physinfo == 'RS1':
-        task = 'rest'
-        run = '01'
-    elif physinfo == 'RS2':
-        task = 'rest'
-        run = '02'
-    elif physinfo == 'RS3':
-        task = 'rest'
-        run = '03'
-    elif physinfo == 'RS4':
-        task = 'rest'
-        run = '04'
-        # ############################## #
-        # ## Don't modify below this! ## #
-        # ############################## #
-    else:
-        # #!# Transform sys.exit in debug warnings or raiseexceptions!
-        # #!# Make all of the above a dictionary
-        raise Warning(f'The heuristic {__file__} could not deal with {physinfo}')
-
-    if not task:
-        raise KeyError(f'No "task" attribute found')
-
-    name = name + '_task-' + task
-
-    # filename spec: sub-<label>[_ses-<label>]_task-<label>[_acq-<label>] ...
-    #                ... [_ce-<label>][_dir-<label>][_rec-<label>] ...
-    #                ... [_run-<index>][_recording-<label>]_physio
-    if acq:
-        name = name + '_acq-' + acq
-
-    if direct:
-        name = name + '_dir-' + direct
-
-    if rec:
-        name = name + '_rec-' + rec
-
-    if run:
-        name = name + '_run-' + run
-
-    return name
diff --git a/phys2bids/heuristics/heur_ex.py b/phys2bids/heuristics/heur_ex.py
deleted file mode 100644
index 57c872112..000000000
--- a/phys2bids/heuristics/heur_ex.py
+++ /dev/null
@@ -1,57 +0,0 @@
-# import sys
-# import fnmatch
-
-
-def heur(physinfo, name, task='', acq='', direct='', rec='', run=''):
-    # ############################## #
-    # ##       Modify here!       ## #
-    # ##                          ## #
-    # ##  Possible variables are: ## #
-    # ##    -task (required)      ## #
-    # ##    -run                  ## #
-    # ##    -rec                  ## #
-    # ##    -acq                  ## #
-    # ##    -direct               ## #
-    # ##                          ## #
-    # ##                          ## #
-    # ##    See example below     ## #
-    # ############################## #
-
-    if physinfo == 'origfilename1':
-        task = 'newname1'
-    elif physinfo == 'origfilename2':
-        task = 'newname2'
-        run = 'runnum'
-    elif physinfo == 'Example':
-        task = 'rest'
-        run = '01'
-        acq = 'resp'
-        # ############################## #
-        # ## Don't modify below this! ## #
-        # ############################## #
-    else:
-        # #!# Transform sys.exit in debug warnings or raiseexceptions!
-        # #!# Make all of the above a dictionary
-        raise Warning(f'The heuristic {__file__} could not deal with {physinfo}')
-
-    if not task:
-        raise KeyError(f'No "task" attribute found')
-
-    name = name + '_task-' + task
-
-    # filename spec: sub-<label>[_ses-<label>]_task-<label>[_acq-<label>] ...
-    #                ... [_ce-<label>][_dir-<label>][_rec-<label>] ...
-    #                ... [_run-<index>][_recording-<label>]_physio
-    if acq:
-        name = name + '_acq-' + acq
-
-    if direct:
-        name = name + '_dir-' + direct
-
-    if rec:
-        name = name + '_rec-' + rec
-
-    if run:
-        name = name + '_run-' + run
-
-    return name

From c4e62b854ee5e873aed4098565643e4964bd1e7c Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Fri, 10 Apr 2020 20:00:32 +0200
Subject: [PATCH 03/20] Restructure heuristics to use info dictionary

---
 phys2bids/heuristics/heur_euskalibur.py | 93 +++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 phys2bids/heuristics/heur_euskalibur.py

diff --git a/phys2bids/heuristics/heur_euskalibur.py b/phys2bids/heuristics/heur_euskalibur.py
new file mode 100644
index 000000000..bd067e8ca
--- /dev/null
+++ b/phys2bids/heuristics/heur_euskalibur.py
@@ -0,0 +1,93 @@
+import fnmatch
+import logging
+
+LGR = logging.getLogger(__name__)
+
+
+def heur(physinfo, info):
+    """
+    Set of if .. elif statements to fill BIDS names.
+
+    Requires the user (you!) to adjust it accordingly!
+    The `if ..` structure should always be similar to
+    ```
+    if physinfo == 'somepattern':
+        info['var'] = 'somethingelse'
+    ```
+    or, in case it's a partial match
+    ```
+    if fnmatch.fnmatchcase(physinfo, '*somepattern?'):
+        info['var'] = 'somethingelse'
+    ```
+
+    Where:
+        - `physinfo` and `info` are dedicated keywords,
+        - 'somepattern' is the name of the file,
+        - 'var' is a bids key in the list below
+        - 'somethingelse' is the value of the key
+
+    Parameters
+    ----------
+    physinfo: str
+        Name of the file or partial match
+    info: dictionary of str
+        Dictionary containing BIDS keys
+
+    Returns
+    -------
+    info: dictionary of str
+        Populated dictionary containing BIDS keys
+    """
+    # ################################# #
+    # ##        Modify here!         ## #
+    # ##                             ## #
+    # ##  Possible variables are:    ## #
+    # ##    -info['task'] (required) ## #
+    # ##    -info['run']             ## #
+    # ##    -info['rec']             ## #
+    # ##    -info['acq']             ## #
+    # ##    -info['dir']             ## #
+    # ##                             ## #
+    # ##  Remember that they are     ## #
+    # ##  dictionary keys            ## #
+    # ##  See example below          ## #
+    # ################################# #
+
+    if physinfo == 'origfilename1':
+        info['task'] = 'newname1'
+    elif physinfo == 'origfilename2':
+        info['task'] = 'newname2'
+        info['run'] = 'runnum'
+    elif physinfo == 'BH4':
+        info['task'] = 'breathhold'
+    elif fnmatch.fnmatchcase(physinfo, 'MOTOR?'):
+        info['task'] = 'motor'
+    elif fnmatch.fnmatchcase(physinfo, 'LOCALIZER?'):
+        info['task'] = 'pinel'
+    elif fnmatch.fnmatchcase(physinfo, 'SIMON?'):
+        info['task'] = 'simon'
+    elif physinfo == 'RS1':
+        info['task'] = 'rest'
+        info['run'] = '01'
+    elif physinfo == 'RS2':
+        info['task'] = 'rest'
+        info['run'] = '02'
+    elif physinfo == 'RS3':
+        info['task'] = 'rest'
+        info['run'] = '03'
+    elif physinfo == 'RS4':
+        info['task'] = 'rest'
+        info['run'] = '04'
+        # ############################## #
+        # ## Don't modify below this! ## #
+        # ############################## #
+    else:
+        # #!# Transform sys.exit in debug warnings or raiseexceptions!
+        # #!# Make all of the above a dictionary
+        LGR.warning(f'The heuristic {__file__} could not deal with {physinfo}')
+
+    # filename spec: sub-<label>[_ses-<label>]_task-<label>[_acq-<label>] ...
+    #                ... [_ce-<label>][_dir-<label>][_rec-<label>] ...
+    #                ... [_run-<index>][_recording-<label>]_physio
+
+    return info

From 2f9146a270304e284b92111e82c0e85102cbea89 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Fri, 10 Apr 2020 20:02:22 +0200
Subject: [PATCH 04/20] Adapt use_heuristic to accept new heuristics and use
 info dictionary

---
 phys2bids/phys2bids.py | 69 +++++++++++++++++++++++++-----------------
 1 file changed, 41 insertions(+), 28 deletions(-)

diff --git a/phys2bids/phys2bids.py b/phys2bids/phys2bids.py
index a127bc424..845998e4e 100644
--- a/phys2bids/phys2bids.py
+++ b/phys2bids/phys2bids.py
@@ -1,8 +1,7 @@
 #!/usr/bin/env python3
 
 """
-Phys2bids is a python3 library meant to set physiological files in BIDS
-standard.
+Phys2bids is a python3 library meant to set physiological files in BIDS standard.
 
 It was born for Acqknowledge files (BIOPAC), and at the moment it supports
 ``.acq`` files and ``.txt`` files obtained by labchart (ADInstruments).
@@ -44,7 +43,7 @@
 
 def print_summary(filename, ntp_expected, ntp_found, samp_freq, time_offset, outfile):
     """
-    Prints a summary onscreen and in file with informations on the files.
+    Print a summary onscreen and in file with informations on the files.
 
     Parameters
     ----------
@@ -85,7 +84,7 @@ def print_summary(filename, ntp_expected, ntp_found, samp_freq, time_offset, out
 
 def print_json(outfile, samp_freq, time_offset, ch_name):
     """
-    Prints the json required by BIDS format.
+    Print the json required by BIDS format.
 
     Parameters
     ----------
@@ -112,7 +111,6 @@ def print_json(outfile, samp_freq, time_offset, ch_name):
 
 
 def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
-    utils.check_file_exists(heur_file)
     """
     Import the heuristic file specified by the user and uses its output
     to rename the file.
@@ -137,39 +135,53 @@ def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
     -------
     heurpath: str or path
         Returned fullpath to tsv.gz new file (post BIDS formatting).
+
+    Raises
+    ------
+    KeyError
+        if `info['task']` is empty
     """
+    utils.check_file_exists(heur_file)
+
+    # Initialise a dictionary of info that has already "recording"
+    info = {'sub': '', 'ses': '', 'task': '', 'acq': '', 'ce': '',
+            'dir': '', 'rec': '', 'run': '', 'recording': record_label}
 
-    if sub[:4] != 'sub-':
-        name = f'sub-{sub}'
+    # Start filling info dictionary and path with subject and session
+    if sub[:4] == 'sub-':
+        info['sub'] = sub[4:]
+        fldr = os.path.join(outdir, sub)
     else:
-        name = sub
+        info['sub'] = sub
+        fldr = os.path.join(outdir, f'sub-{sub}')
+    if ses:
+        if ses[:4] == 'ses-':
+            info['ses'] = ses[4:]
+            fldr = os.path.join(outdir, ses)
+        else:
+            info['ses'] = ses
+            fldr = os.path.join(outdir, f'ses-{ses}')
 
-    fldr = os.path.join(outdir, name)
+    # Load heuristic and use it to fill dictionary
+    heur = utils.load_heuristic(heur_file)
+    info = heur.heur(Path(filename).stem, info)
 
-    if ses:
-        if ses[:4] != 'ses-':
-            ses = f'ses-{ses}'
+    # If info['task'] is still empty, stop the program
+    if not info['task']:
+        raise KeyError(f'No "task" attribute found')
 
-        fldr = os.path.join(fldr, ses)
-        name = f'{name}_{ses}'
+    # Compose name by looping in the info dictionary
+    # and adding nonempty keys
+    name = ''
+    for key in info:
+        if info[key]:
+            name = f'{name}{key}-{info[key]}_'
 
+    # Finish path, create it, add filename, export
     fldr = os.path.join(fldr, 'func')
     utils.path_exists_or_make_it(fldr)
 
-    cwd = os.getcwd()
-    os.chdir(outdir)
-
-    heur = utils.load_heuristic(heur_file)
-    name = heur.heur(Path(filename).stem, name)
-
-    recording = ''
-    if record_label:
-        recording = f'_recording-{record_label}'
-
-    heurpath = os.path.join(fldr, f'{name}{recording}_physio')
-    # for ext in ['.tsv.gz', '.json', '.log']:
-    #     move_file(outfile, heurpath, ext)
-    os.chdir(cwd)
+    heurpath = os.path.join(fldr, f'{name}_physio')
 
     return heurpath
 
@@ -179,6 +191,7 @@ def phys2bids(filename, info=False, indir='.', outdir='.', heur_file=None,
               tr=1, thr=None, ch_name=[], chplot='', debug=False, quiet=False):
     """
     Main workflow of phys2bids.
+
     Runs the parser, does some checks on input, then imports
     the right interface file to read the input. If only info is required,
     it returns a summary onscreen.

From fbc30fdcd6ec2a0201322c0777d9fb0cb9caf505 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Fri, 10 Apr 2020 20:04:56 +0200
Subject: [PATCH 05/20] Update heuristics for tutorial and tests

---
 phys2bids/heuristics/heur_test_acq.py | 97 ++++++++++++++++-----------
 phys2bids/heuristics/heur_tutorial.py | 97 ++++++++++++++++-----------
 2 files changed, 118 insertions(+), 76 deletions(-)

diff --git a/phys2bids/heuristics/heur_test_acq.py b/phys2bids/heuristics/heur_test_acq.py
index d065451db..99eb22976 100644
--- a/phys2bids/heuristics/heur_test_acq.py
+++ b/phys2bids/heuristics/heur_test_acq.py
@@ -1,55 +1,76 @@
 import fnmatch
+import logging
 
+LGR = logging.getLogger(__name__)
 
-def heur(physinfo, name, task='', acq='', direct='', rec='', run=''):
-    # ############################## #
-    # ##       Modify here!       ## #
-    # ##                          ## #
-    # ##  Possible variables are: ## #
-    # ##    -task (required)      ## #
-    # ##    -run                  ## #
-    # ##    -rec                  ## #
-    # ##    -acq                  ## #
-    # ##    -direct               ## #
-    # ##                          ## #
-    # ##                          ## #
-    # ##    See example below     ## #
-    # ############################## #
+
+def heur(physinfo, info):
+    """
+    Set of if .. elif statements to fill BIDS names.
+
+    Requires the user (you!) to adjust it accordingly!
+    The `if ..` structure should always be similar to
+    ```
+    if physinfo == 'somepattern':
+        info['var'] = 'somethingelse'
+    ```
+    or, in case it's a partial match
+    ```
+    if fnmatch.fnmatchcase(physinfo, '*somepattern?'):
+        info['var'] = 'somethingelse'
+    ```
+
+    Where:
+        - `physinfo` and `info` are dedicated keywords,
+        - 'somepattern' is the name of the file,
+        - 'var' is a bids key in the list below
+        - 'somethingelse' is the value of the key
+
+    Parameters
+    ----------
+    physinfo: str
+        Name of the file or partial match
+    info: dictionary of str
+        Dictionary containing BIDS keys
+
+    Returns
+    -------
+    info: dictionary of str
+        Populated dictionary containing BIDS keys
+    """
+    # ################################# #
+    # ##        Modify here!         ## #
+    # ##                             ## #
+    # ##  Possible variables are:    ## #
+    # ##    -info['task'] (required) ## #
+    # ##    -info['run']             ## #
+    # ##    -info['rec']             ## #
+    # ##    -info['acq']             ## #
+    # ##    -info['dir']             ## #
+    # ##                             ## #
+    # ##  Remember that they are     ## #
+    # ##  dictionary keys            ## #
+    # ##  See example below          ## #
+    # ################################# #
 
     if fnmatch.fnmatchcase(physinfo, '*samefreq*'):
-        task = 'test'
-        run = '01'
-        rec = 'biopac'
+        info['task'] = 'test'
+        info['run'] = '01'
+        info['rec'] = 'biopac'
     elif physinfo == 'Example':
-        task = 'rest'
-        run = '01'
-        acq = 'resp'
+        info['task'] = 'rest'
+        info['run'] = '01'
+        info['acq'] = 'resp'
         # ############################## #
         # ## Don't modify below this! ## #
         # ############################## #
     else:
         # #!# Transform sys.exit in debug warnings or raiseexceptions!
         # #!# Make all of the above a dictionary
-        raise Warning(f'The heuristic {__file__} could not deal with {physinfo}')
-
-    if not task:
-        raise KeyError(f'No "task" attribute found')
-
-    name = name + '_task-' + task
+        LGR.warning(f'The heuristic {__file__} could not deal with {physinfo}')
 
     # filename spec: sub-<label>[_ses-<label>]_task-<label>[_acq-<label>] ...
     #                ... [_ce-<label>][_dir-<label>][_rec-<label>] ...
     #                ... [_run-<index>][_recording-<label>]_physio
-    if acq:
-        name = name + '_acq-' + acq
-
-    if direct:
-        name = name + '_dir-' + direct
-
-    if rec:
-        name = name + '_rec-' + rec
-
-    if run:
-        name = name + '_run-' + run
 
-    return name
+    return info
diff --git a/phys2bids/heuristics/heur_tutorial.py b/phys2bids/heuristics/heur_tutorial.py
index 4a6855444..8cf6acb93 100644
--- a/phys2bids/heuristics/heur_tutorial.py
+++ b/phys2bids/heuristics/heur_tutorial.py
@@ -1,55 +1,76 @@
 import fnmatch
+import logging
 
+LGR = logging.getLogger(__name__)
 
-def heur(physinfo, name, task='', acq='', direct='', rec='', run=''):
-    # ############################## #
-    # ##       Modify here!       ## #
-    # ##                          ## #
-    # ##  Possible variables are: ## #
-    # ##    -task (required)      ## #
-    # ##    -run                  ## #
-    # ##    -rec                  ## #
-    # ##    -acq                  ## #
-    # ##    -direct               ## #
-    # ##                          ## #
-    # ##                          ## #
-    # ##    See example below     ## #
-    # ############################## #
+
+def heur(physinfo, info):
+    """
+    Set of if .. elif statements to fill BIDS names.
+
+    Requires the user (you!) to adjust it accordingly!
+    The `if ..` structure should always be similar to
+    ```
+    if physinfo == 'somepattern':
+        info['var'] = 'somethingelse'
+    ```
+    or, in case it's a partial match
+    ```
+    if fnmatch.fnmatchcase(physinfo, '*somepattern?'):
+        info['var'] = 'somethingelse'
+    ```
+
+    Where:
+        - `physinfo` and `info` are dedicated keywords,
+        - 'somepattern' is the name of the file,
+        - 'var' is a bids key in the list below
+        - 'somethingelse' is the value of the key
+
+    Parameters
+    ----------
+    physinfo: str
+        Name of the file or partial match
+    info: dictionary of str
+        Dictionary containing BIDS keys
+
+    Returns
+    -------
+    info: dictionary of str
+        Populated dictionary containing BIDS keys
+    """
+    # ################################# #
+    # ##        Modify here!         ## #
+    # ##                             ## #
+    # ##  Possible variables are:    ## #
+    # ##    -info['task'] (required) ## #
+    # ##    -info['run']             ## #
+    # ##    -info['rec']             ## #
+    # ##    -info['acq']             ## #
+    # ##    -info['dir']             ## #
+    # ##                             ## #
+    # ##  Remember that they are     ## #
+    # ##  dictionary keys            ## #
+    # ##  See example below          ## #
+    # ################################# #
 
     if fnmatch.fnmatchcase(physinfo, '*tutorial*'):
-        task = 'test'
-        run = '01'
-        rec = 'labchart'
+        info['task'] = 'test'
+        info['run'] = '01'
+        info['rec'] = 'labchart'
     elif physinfo == 'Example':
-        task = 'rest'
-        run = '01'
-        acq = 'resp'
+        info['task'] = 'rest'
+        info['run'] = '01'
+        info['acq'] = 'resp'
         # ############################## #
         # ## Don't modify below this! ## #
         # ############################## #
     else:
         # #!# Transform sys.exit in debug warnings or raiseexceptions!
         # #!# Make all of the above a dictionary
-        raise Warning(f'The heuristic {__file__} could not deal with {physinfo}')
-
-    if not task:
-        raise KeyError(f'No "task" attribute found')
-
-    name = name + '_task-' + task
+        LGR.warning(f'The heuristic {__file__} could not deal with {physinfo}')
 
     # filename spec: sub-<label>[_ses-<label>]_task-<label>[_acq-<label>] ...
     #                ... [_ce-<label>][_dir-<label>][_rec-<label>] ...
     #                ... [_run-<index>][_recording-<label>]_physio
-    if acq:
-        name = name + '_acq-' + acq
-
-    if direct:
-        name = name + '_dir-' + direct
-
-    if rec:
-        name = name + '_rec-' + rec
-
-    if run:
-        name = name + '_run-' + run
 
-    return name
+    return info

From 28570e8db48275f265234e3ef7195af5cc4c5794 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Fri, 10 Apr 2020 20:33:23 +0200
Subject: [PATCH 06/20] Update documentation

---
 docs/heuristic.rst | 29 +++++++++++++----------------
 docs/howto.rst     |  5 +++--
 2 files changed, 16 insertions(+), 18 deletions(-)

diff --git a/docs/heuristic.rst b/docs/heuristic.rst
index 539c634aa..89431b5ad 100644
--- a/docs/heuristic.rst
+++ b/docs/heuristic.rst
@@ -22,36 +22,34 @@ Initialisation
 
 .. literalinclude:: ../phys2bids/heuristics/heur_tutorial.py
    :linenos:
-   :lines: 1-4
+   :lines: 1-40
 
 It's important **not to modify this part of the file**. Instead, you can copy and paste it into your own heuristic file.
 
 This file looks like a python function, initialised by two mandatory parameters:
 -``physinfo`` is the information used to label your file. **At the moment, it corresponds to the name of the input file itself**. This is what you need to build your heuristic.
--``name`` is an argument passed by the main script that contains part of the name of the file. Don't worry about this.
+-``info`` is a `python dictionary <https://www.w3schools.com/python/python_dictionaries.asp>`_ passed by the main script that contains the BIDS keys, such as `sub` and `ses`, as well as all the possible keys you can add to your heuristics. This is what you will work with in creating your heuristic
 
-The file also has another bunch of optional arguments that are empty by default. These are the labels you can add to your dictionaries, in order to construct the BIDsified name of your files.
-
-The scripts imports ``fnmatch``, a nice python module that lets you use bash-like wildcards.
+The scripts imports ``fnmatch``, a nice python module that lets you use bash-like wildcards, as well as ``logger``, a module that let us log what happens in the program execution.
 
 Dictionaries
 ^^^^^^^^^^^^
 
 .. literalinclude:: ../phys2bids/heuristics/heur_tutorial.py
    :linenos:
-   :lines: 5-29
-   :lineno-start: 5
+   :lines: 41-63
+   :lineno-start: 41
    :dedent: 4
 
-This is the core of the function, and the part that should be adapted to process your files. In practice, it's the beginning of a |statement|_.
-| You need an ``if`` or ``elif`` statement for each file that you want to process, that will test if the ``physinfo`` is similar to a string (first case) or exactly matches a string (second case). The content of the statement is a set of `variable initialisations as a string <https://www.w3schools.com/python/python_strings.asp>`_.
-| The list of possible variables is in the comment above, and corresponds to the list of possible entities of the `BIDs specification <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/06-physiological-and-other-continuous-recordings.html>`_:
+| This is the core of the function, and the part that should be adapted to process your files. In practice, it's the beginning of a |statement|_.
+| You need an ``if`` or ``elif`` statement for each file that you want to process, that will test if the ``physinfo`` is similar to a string (first case) or exactly matches a string (second case). The content of the statement is a set of `variable initialisations as a string <https://www.w3schools.com/python/python_strings.asp>`_, with the only difference that you're populating a dictionary here. This means that instead of declaring something like ``var = 'something'``, you will declare something like ``info['var'] = 'something'``
+| The list of possible keys is in the comment above, and corresponds to the list of possible entities of the `BIDs specification <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/06-physiological-and-other-continuous-recordings.html>`_:
 
-- ``task`` stands for the name of the task. **It's the only required entity**, and it should match the task of the neuroimaging file associated to the physiological data.
+- ``task`` stands for the name of the task. **It's the only required entity**, and it should match the task of the neuroimaging file associated to the physiological data. If this is missing **the program will stop running**
 - ``run`` is the optional entity for the `index of the scan in a group of same modalities <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#the-run-entity>`_ (e.g. 2 resting states).
 - ``rec`` is the optional entity for the `reconstruction algorithm <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#the-rec-entity>`_.
 - ``acq`` is the optional entity for the `set of acquisition parameters <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#the-acq-entity>`_.
-- ``direct`` is the equivalent of the ``dic`` entity, an optional entity for the phase encoding direction (see `here <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#task-including-resting-state-imaging-data>`_).
+- ``dir`` is the optional entity for the phase encoding direction (see `here <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#task-including-resting-state-imaging-data>`_).
 
 Note that one mandatory BIDs entity is missing: the **``sub`` entity**, correspondent to the subject label. This is because it has to be specified while calling ``phys2bids``, as it's explained in the tutorial section `"generating-outputs-in-bids-format" <howto.html#generating-outputs-in-bids-format>`_. The **session entity** can be specified in the same way. Moreover, if you have a **multifrequency file** there will be another entity, ``recording`` automatically added to those specified here, and containing the sample frequency of the different outputs.
 
@@ -70,13 +68,12 @@ Functional code
 
 .. literalinclude:: ../phys2bids/heuristics/heur_tutorial.py
    :linenos:
-   :lines: 27-
-   :lineno-start: 27
+   :lines: 64-
+   :lineno-start: 64
    :dedent: 4
 
-This part contains some code that composes the heuristic function output.
+This part contains a simple warning call that will be reported to the logger if the heuristic file doesn't contain actual references to your input files.
 It's important **not to modify this part of the file**. Instead, you can copy and paste it into your own heuristic file.
-There's a warning that will raise if the file wasn't able to process the input file, and an error that will raise if the mandatory ``task`` entity is still empty after the dictionary attribution.
 
 Using the heuristic file
 ------------------------
diff --git a/docs/howto.rst b/docs/howto.rst
index eb4b5054c..1a525e1e9 100644
--- a/docs/howto.rst
+++ b/docs/howto.rst
@@ -195,6 +195,7 @@ In the second row, we see the first and last trigger (or expected first and last
 
 .. warning::
     If you have another file that was collected in an identical way, the threshold is likely to be same. However, it is *very* important to calibrate the threshold in a couple of files before assuming this. This still *won't* necessarily mean that it's the right threshold for all the files, but there's a chance that it's ok(ish) for most of them.
+
 If for some reason ``-ntp`` and the number of timepoints found by ``phys2bids`` is not the same there are two possible reasons:
 
 1. You didn't properly count the number of timepoints. Check this again; you can use the trigger png file to help you.
@@ -281,8 +282,8 @@ Alright, now the really interesting part! This section will explain how to use t
 
 .. literalinclude:: ../phys2bids/heuristics/heur_tutorial.py
    :linenos:
-   :lines: 4-22
-   :lineno-start: 4
+   :lines: 41-63
+   :lineno-start: 41
 
 The heuristic file has to be written accordingly, with a set of rules that could work for all the files in your dataset. You can learn more about it if you check the `guide on how to set it up <heuristic.html>`_.
 In this case, our heuristic file looks for a file that contains the name ``tutorial``. It corresponds to the task ``test`` and run ``00``. Note that **only the task is required**, all the other fields are optional - look them up in the BIDs documentation and see if you need them.

From 7abb36e184b6571d78ec3ad0d0c8e309bf974b91 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Fri, 10 Apr 2020 22:07:22 +0200
Subject: [PATCH 07/20] Correct folder path

---
 phys2bids/phys2bids.py | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/phys2bids/phys2bids.py b/phys2bids/phys2bids.py
index 845998e4e..295805084 100644
--- a/phys2bids/phys2bids.py
+++ b/phys2bids/phys2bids.py
@@ -154,13 +154,14 @@ def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
     else:
         info['sub'] = sub
         fldr = os.path.join(outdir, f'sub-{sub}')
+
     if ses:
         if ses[:4] == 'ses-':
             info['ses'] = ses[4:]
-            fldr = os.path.join(outdir, ses)
+            fldr = os.path.join(fldr, ses)
         else:
             info['ses'] = ses
-            fldr = os.path.join(outdir, f'ses-{ses}')
+            fldr = os.path.join(fldr, f'ses-{ses}')
 
     # Load heuristic and use it to fill dictionary
     heur = utils.load_heuristic(heur_file)
@@ -181,7 +182,7 @@ def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
     fldr = os.path.join(fldr, 'func')
     utils.path_exists_or_make_it(fldr)
 
-    heurpath = os.path.join(fldr, f'{name}_physio')
+    heurpath = os.path.join(fldr, f'{name}physio')
 
     return heurpath
 

From bd4689752e70100e774716d905d30c20ff564d39 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Fri, 10 Apr 2020 22:07:46 +0200
Subject: [PATCH 08/20] =?UTF-8?q?Update=20tests=20to=20match=20new=20heuri?=
 =?UTF-8?q?stic=20(run-00=E2=86=9201)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 phys2bids/tests/test_integration.py | 6 +++---
 phys2bids/tests/test_phys2bids.py   | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/phys2bids/tests/test_integration.py b/phys2bids/tests/test_integration.py
index bf01e9616..232e8a0fc 100644
--- a/phys2bids/tests/test_integration.py
+++ b/phys2bids/tests/test_integration.py
@@ -250,12 +250,12 @@ def test_integration_heuristic():
     test_path_output = os.path.join(test_path, 'sub-006/ses-01/func')
 
     # Check that files are generated
-    base_filename = 'sub-006_ses-01_task-test_rec-labchart_run-00_physio'
+    base_filename = 'sub-006_ses-01_task-test_rec-labchart_run-01_physio'
     for suffix in ['.log', '.json', '.tsv.gz']:
         assert os.path.isfile(os.path.join(test_path_output, base_filename + suffix))
 
     # Read log file (note that this file is not the logger file)
-    log_filename = 'sub-006_ses-01_task-test_rec-labchart_run-00_physio.log'
+    log_filename = 'sub-006_ses-01_task-test_rec-labchart_run-01_physio.log'
     with open(os.path.join(test_path_output, log_filename)) as log_info:
         log_info = log_info.readlines()
 
@@ -271,7 +271,7 @@ def test_integration_heuristic():
     assert check_string(log_info, 'first trigger', 'Time 0', is_num=False)
 
     # Checks json file
-    json_filename = 'sub-006_ses-01_task-test_rec-labchart_run-00_physio.json'
+    json_filename = 'sub-006_ses-01_task-test_rec-labchart_run-01_physio.json'
     with open(os.path.join(test_path_output, json_filename)) as json_file:
         json_data = json.load(json_file)
 
diff --git a/phys2bids/tests/test_phys2bids.py b/phys2bids/tests/test_phys2bids.py
index 7a16b0de8..f42d8cc13 100644
--- a/phys2bids/tests/test_phys2bids.py
+++ b/phys2bids/tests/test_phys2bids.py
@@ -60,7 +60,7 @@ def test_use_heuristic(tmpdir):
                                         test_full_input_path, test_outdir, test_record_label)
 
     test_result = ('/sub-SBJ01/ses-S05/func/sub-SBJ01_ses-S05_task-test_rec'
-                   '-biopac_run-00_recording-test_physio')
+                   '-biopac_run-01_recording-test_physio')
     test_result = str(tmpdir) + test_result
 
     assert test_result == str(heur_path)

From 447c176096a6ad3ce5101e18f8292d04c0bd6ce8 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Sat, 18 Apr 2020 19:45:31 +0200
Subject: [PATCH 09/20] Change dictionary name from 'info' to 'bids_keys'

---
 phys2bids/phys2bids.py | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/phys2bids/phys2bids.py b/phys2bids/phys2bids.py
index 295805084..3a3a412bb 100644
--- a/phys2bids/phys2bids.py
+++ b/phys2bids/phys2bids.py
@@ -139,44 +139,44 @@ def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
     Raises
     ------
     KeyError
-        if `info['task']` is empty
+        if `bids_keys['task']` is empty
     """
     utils.check_file_exists(heur_file)
 
-    # Initialise a dictionary of info that has already "recording"
-    info = {'sub': '', 'ses': '', 'task': '', 'acq': '', 'ce': '',
-            'dir': '', 'rec': '', 'run': '', 'recording': record_label}
+    # Initialise a dictionary of bids_keys that has already "recording"
+    bids_keys = {'sub': '', 'ses': '', 'task': '', 'acq': '', 'ce': '',
+                 'dir': '', 'rec': '', 'run': '', 'recording': record_label}
 
-    # Start filling info dictionary and path with subject and session
+    # Start filling bids_keys dictionary and path with subject and session
     if sub[:4] == 'sub-':
-        info['sub'] = sub[4:]
+        bids_keys['sub'] = sub[4:]
         fldr = os.path.join(outdir, sub)
     else:
-        info['sub'] = sub
+        bids_keys['sub'] = sub
         fldr = os.path.join(outdir, f'sub-{sub}')
 
     if ses:
         if ses[:4] == 'ses-':
-            info['ses'] = ses[4:]
+            bids_keys['ses'] = ses[4:]
             fldr = os.path.join(fldr, ses)
         else:
-            info['ses'] = ses
+            bids_keys['ses'] = ses
             fldr = os.path.join(fldr, f'ses-{ses}')
 
     # Load heuristic and use it to fill dictionary
     heur = utils.load_heuristic(heur_file)
-    info = heur.heur(Path(filename).stem, info)
+    bids_keys = heur.heur(Path(filename).stem, bids_keys)
 
-    # If info['task'] is still empty, stop the program
-    if not info['task']:
+    # If bids_keys['task'] is still empty, stop the program
+    if not bids_keys['task']:
         raise KeyError(f'No "task" attribute found')
 
-    # Compose name by looping in the info dictionary
+    # Compose name by looping in the bids_keys dictionary
     # and adding nonempty keys
     name = ''
-    for key in info:
-        if info[key]:
-            name = f'{name}{key}-{info[key]}_'
+    for key in bids_keys:
+        if bids_keys[key]:
+            name = f'{name}{key}-{bids_keys[key]}_'
 
     # Finish path, create it, add filename, export
     fldr = os.path.join(fldr, 'func')

From a7cf2c6388a14b584101e1ed6ef26465ee7fa079 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Sat, 18 Apr 2020 19:45:48 +0200
Subject: [PATCH 10/20] Add pytest parametrisation not to loose coverage

---
 phys2bids/tests/test_phys2bids.py | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

diff --git a/phys2bids/tests/test_phys2bids.py b/phys2bids/tests/test_phys2bids.py
index f42d8cc13..c1b74da4a 100644
--- a/phys2bids/tests/test_phys2bids.py
+++ b/phys2bids/tests/test_phys2bids.py
@@ -6,6 +6,8 @@
 import os
 from pkg_resources import resource_filename
 
+import pytest
+
 from phys2bids import phys2bids
 
 
@@ -44,12 +46,12 @@ def test_print_json(tmpdir):
     assert test_json_data == loaded_data
 
 
-def test_use_heuristic(tmpdir):
+@pytest.mark.parametrize('test_sub', ['SBJ01', 'sub-006', '006'])
+@pytest.mark.parametrize('test_ses', ['', 'S05', 'ses-42', '42'])
+def test_use_heuristic(tmpdir, test_sub, test_ses):
     test_heur_path = resource_filename('phys2bids', 'heuristics')
     test_heur_file = 'heur_test_acq.py'
     test_full_heur_path = os.path.join(test_heur_path, test_heur_file)
-    test_sub = 'SBJ01'
-    test_ses = 'S05'
     test_input_path = resource_filename('phys2bids', 'tests/data')
     test_input_file = 'Test_belt_pulse_samefreq.acq'
     test_full_input_path = os.path.join(test_input_path, test_input_file)
@@ -59,8 +61,20 @@ def test_use_heuristic(tmpdir):
     heur_path = phys2bids.use_heuristic(test_full_heur_path, test_sub, test_ses,
                                         test_full_input_path, test_outdir, test_record_label)
 
-    test_result = ('/sub-SBJ01/ses-S05/func/sub-SBJ01_ses-S05_task-test_rec'
-                   '-biopac_run-01_recording-test_physio')
-    test_result = str(tmpdir) + test_result
+    if test_sub[:4] == 'sub-':
+        test_sub = test_sub[4:]
+
+    test_result_path = (f'{tmpdir}/sub-{test_sub}')
+    test_result_name = (f'sub-{test_sub}')
+
+    if test_ses[:4] == 'ses-':
+        test_ses = test_ses[4:]
+
+    if test_ses:
+        test_result_path = (f'{test_result_path}/ses-{test_ses}')
+        test_result_name = (f'{test_result_name}_ses-{test_ses}')
+
+    test_result = (f'{test_result_path}/func/{test_result_name}'
+                   f'_task-test_rec-biopac_run-01_recording-test_physio')
 
     assert test_result == str(heur_path)

From e21c138ea68a4eecd985302c718d948e829a87c3 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Sat, 18 Apr 2020 20:12:09 +0200
Subject: [PATCH 11/20] Change file link for deleted file

---
 phys2bids/tests/conftest.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/phys2bids/tests/conftest.py b/phys2bids/tests/conftest.py
index 9d252c8e9..16d66969f 100644
--- a/phys2bids/tests/conftest.py
+++ b/phys2bids/tests/conftest.py
@@ -76,5 +76,5 @@ def multifreq_lab_file(testpath):
 
 @pytest.fixture
 def notime_lab_file(testpath):
-    return fetch_file('u5dq8', testpath,
+    return fetch_file('5829m', testpath,
                       'Test2_trigger_CO2_O2_pulse_1000Hz_534TRs_no_time.txt')

From c9a54e171c443ef78042aa528fbbee6a373c5838 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Mon, 20 Apr 2020 21:03:14 +0200
Subject: [PATCH 12/20] Update phys2bids/phys2bids.py

Co-Authored-By: Ross Markello <rossmarkello@gmail.com>
---
 phys2bids/phys2bids.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/phys2bids/phys2bids.py b/phys2bids/phys2bids.py
index 3a3a412bb..ffe126f06 100644
--- a/phys2bids/phys2bids.py
+++ b/phys2bids/phys2bids.py
@@ -175,7 +175,7 @@ def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
     # and adding nonempty keys
     name = ''
     for key in bids_keys:
-        if bids_keys[key]:
+        if bids_keys[key] != '':
             name = f'{name}{key}-{bids_keys[key]}_'
 
     # Finish path, create it, add filename, export

From 0ba2ec567917f9a0aba367768b74baa307de2f65 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Mon, 20 Apr 2020 21:03:32 +0200
Subject: [PATCH 13/20] Update phys2bids/phys2bids.py

Co-Authored-By: Ross Markello <rossmarkello@gmail.com>
---
 phys2bids/phys2bids.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/phys2bids/phys2bids.py b/phys2bids/phys2bids.py
index ffe126f06..676b0d30c 100644
--- a/phys2bids/phys2bids.py
+++ b/phys2bids/phys2bids.py
@@ -148,7 +148,7 @@ def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
                  'dir': '', 'rec': '', 'run': '', 'recording': record_label}
 
     # Start filling bids_keys dictionary and path with subject and session
-    if sub[:4] == 'sub-':
+    if sub.startswith('sub-'):
         bids_keys['sub'] = sub[4:]
         fldr = os.path.join(outdir, sub)
     else:

From 8158e414c3786f3eb09c3e8baf63541ee97c0579 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Mon, 20 Apr 2020 21:03:51 +0200
Subject: [PATCH 14/20] Update docs/heuristic.rst

Co-Authored-By: Ross Markello <rossmarkello@gmail.com>
---
 docs/heuristic.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/heuristic.rst b/docs/heuristic.rst
index 89431b5ad..ba9ae1732 100644
--- a/docs/heuristic.rst
+++ b/docs/heuristic.rst
@@ -45,7 +45,7 @@ Dictionaries
 | You need an ``if`` or ``elif`` statement for each file that you want to process, that will test if the ``physinfo`` is similar to a string (first case) or exactly matches a string (second case). The content of the statement is a set of `variable initialisations as a string <https://www.w3schools.com/python/python_strings.asp>`_, with the only difference that you're populating a dictionary here. This means that instead of declaring something like ``var = 'something'``, you will declare something like ``info['var'] = 'something'``
 | The list of possible keys is in the comment above, and corresponds to the list of possible entities of the `BIDs specification <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/06-physiological-and-other-continuous-recordings.html>`_:
 
-- ``task`` stands for the name of the task. **It's the only required entity**, and it should match the task of the neuroimaging file associated to the physiological data. If this is missing **the program will stop running**
+- ``task`` stands for the name of the task. **It's the only required entity**, and it should match the task of the neuroimaging file associated to the physiological data. If this is missing **the program will stop running**.
 - ``run`` is the optional entity for the `index of the scan in a group of same modalities <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#the-run-entity>`_ (e.g. 2 resting states).
 - ``rec`` is the optional entity for the `reconstruction algorithm <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#the-rec-entity>`_.
 - ``acq`` is the optional entity for the `set of acquisition parameters <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#the-acq-entity>`_.

From c0d995474ed7da8bfc5bf26232451642cc2769dd Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Mon, 20 Apr 2020 21:03:58 +0200
Subject: [PATCH 15/20] Update phys2bids/phys2bids.py

Co-Authored-By: Ross Markello <rossmarkello@gmail.com>
---
 phys2bids/phys2bids.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/phys2bids/phys2bids.py b/phys2bids/phys2bids.py
index 676b0d30c..5e11a7744 100644
--- a/phys2bids/phys2bids.py
+++ b/phys2bids/phys2bids.py
@@ -156,7 +156,7 @@ def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
         fldr = os.path.join(outdir, f'sub-{sub}')
 
     if ses:
-        if ses[:4] == 'ses-':
+        if ses.startswith('ses-'):
             bids_keys['ses'] = ses[4:]
             fldr = os.path.join(fldr, ses)
         else:

From 4eecc217af4e672fc9076a157d976f641707c508 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Tue, 21 Apr 2020 20:20:01 +0200
Subject: [PATCH 16/20] Remove logger from heuristic, initialise dictionary
 internally rather than passing it as an argument

---
 phys2bids/heuristics/heur_euskalibur.py | 48 ++++++++++---------------
 phys2bids/heuristics/heur_test_acq.py   | 48 ++++++++++---------------
 phys2bids/heuristics/heur_tutorial.py   | 48 ++++++++++---------------
 3 files changed, 57 insertions(+), 87 deletions(-)

diff --git a/phys2bids/heuristics/heur_euskalibur.py b/phys2bids/heuristics/heur_euskalibur.py
index bd067e8ca..a311de834 100644
--- a/phys2bids/heuristics/heur_euskalibur.py
+++ b/phys2bids/heuristics/heur_euskalibur.py
@@ -1,14 +1,24 @@
 import fnmatch
-import logging
 
-LGR = logging.getLogger(__name__)
 
-
-def heur(physinfo, info):
+def heur(physinfo):
     """
     Set of if .. elif statements to fill BIDS names.
 
-    Requires the user (you!) to adjust it accordingly!
+    Require the user (you!) to adjust it accordingly!
+
+    Parameters
+    ----------
+    physinfo: str
+        Name of an input file that should be bidsified (See Notes)
+
+    Returns
+    -------
+    info: dictionary of str
+        Dictionary containing BIDS keys
+
+    Notes
+    -----
     The `if ..` structure should always be similar to
     ```
     if physinfo == 'somepattern':
@@ -19,25 +29,13 @@ def heur(physinfo, info):
     if fnmatch.fnmatchcase(physinfo, '*somepattern?'):
         info['var'] = 'somethingelse'
     ```
-
     Where:
         - `physinfo` and `info` are dedicated keywords,
         - 'somepattern' is the name of the file,
         - 'var' is a bids key in the list below
         - 'somethingelse' is the value of the key
-
-    Parameters
-    ----------
-    physinfo: str
-        Name of the file or partial match
-    info: dictionary of str
-        Dictionary containing BIDS keys
-
-    Returns
-    -------
-    info: dictionary of str
-        Populated dictionary containing BIDS keys
     """
+    info = {}
     # ################################# #
     # ##        Modify here!         ## #
     # ##                             ## #
@@ -78,16 +76,8 @@ def heur(physinfo, info):
     elif physinfo == 'RS4':
         info['task'] = 'rest'
         info['run'] = '04'
-        # ############################## #
-        # ## Don't modify below this! ## #
-        # ############################## #
-    else:
-        # #!# Transform sys.exit in debug warnings or raiseexceptions!
-        # #!# Make all of the above a dictionary
-        LGR.warning(f'The heuristic {__file__} could not deal with {physinfo}')
-
-    # filename spec: sub-<label>[_ses-<label>]_task-<label>[_acq-<label>] ...
-    #                ... [_ce-<label>][_dir-<label>][_rec-<label>] ...
-    #                ... [_run-<index>][_recording-<label>]_physio
 
+    # ############################## #
+    # ## Don't modify below this! ## #
+    # ############################## #
     return info
diff --git a/phys2bids/heuristics/heur_test_acq.py b/phys2bids/heuristics/heur_test_acq.py
index 99eb22976..0e9c4a01b 100644
--- a/phys2bids/heuristics/heur_test_acq.py
+++ b/phys2bids/heuristics/heur_test_acq.py
@@ -1,14 +1,24 @@
 import fnmatch
-import logging
 
-LGR = logging.getLogger(__name__)
 
-
-def heur(physinfo, info):
+def heur(physinfo):
     """
     Set of if .. elif statements to fill BIDS names.
 
-    Requires the user (you!) to adjust it accordingly!
+    Require the user (you!) to adjust it accordingly!
+
+    Parameters
+    ----------
+    physinfo: str
+        Name of an input file that should be bidsified (See Notes)
+
+    Returns
+    -------
+    info: dictionary of str
+        Dictionary containing BIDS keys
+
+    Notes
+    -----
     The `if ..` structure should always be similar to
     ```
     if physinfo == 'somepattern':
@@ -19,25 +29,13 @@ def heur(physinfo, info):
     if fnmatch.fnmatchcase(physinfo, '*somepattern?'):
         info['var'] = 'somethingelse'
     ```
-
     Where:
         - `physinfo` and `info` are dedicated keywords,
         - 'somepattern' is the name of the file,
         - 'var' is a bids key in the list below
         - 'somethingelse' is the value of the key
-
-    Parameters
-    ----------
-    physinfo: str
-        Name of the file or partial match
-    info: dictionary of str
-        Dictionary containing BIDS keys
-
-    Returns
-    -------
-    info: dictionary of str
-        Populated dictionary containing BIDS keys
     """
+    info = {}
     # ################################# #
     # ##        Modify here!         ## #
     # ##                             ## #
@@ -61,16 +59,8 @@ def heur(physinfo, info):
         info['task'] = 'rest'
         info['run'] = '01'
         info['acq'] = 'resp'
-        # ############################## #
-        # ## Don't modify below this! ## #
-        # ############################## #
-    else:
-        # #!# Transform sys.exit in debug warnings or raiseexceptions!
-        # #!# Make all of the above a dictionary
-        LGR.warning(f'The heuristic {__file__} could not deal with {physinfo}')
-
-    # filename spec: sub-<label>[_ses-<label>]_task-<label>[_acq-<label>] ...
-    #                ... [_ce-<label>][_dir-<label>][_rec-<label>] ...
-    #                ... [_run-<index>][_recording-<label>]_physio
 
+    # ############################## #
+    # ## Don't modify below this! ## #
+    # ############################## #
     return info
diff --git a/phys2bids/heuristics/heur_tutorial.py b/phys2bids/heuristics/heur_tutorial.py
index 8cf6acb93..b1ce3384c 100644
--- a/phys2bids/heuristics/heur_tutorial.py
+++ b/phys2bids/heuristics/heur_tutorial.py
@@ -1,14 +1,24 @@
 import fnmatch
-import logging
 
-LGR = logging.getLogger(__name__)
 
-
-def heur(physinfo, info):
+def heur(physinfo):
     """
     Set of if .. elif statements to fill BIDS names.
 
-    Requires the user (you!) to adjust it accordingly!
+    Require the user (you!) to adjust it accordingly!
+
+    Parameters
+    ----------
+    physinfo: str
+        Name of an input file that should be bidsified (See Notes)
+
+    Returns
+    -------
+    info: dictionary of str
+        Dictionary containing BIDS keys
+
+    Notes
+    -----
     The `if ..` structure should always be similar to
     ```
     if physinfo == 'somepattern':
@@ -19,25 +29,13 @@ def heur(physinfo, info):
     if fnmatch.fnmatchcase(physinfo, '*somepattern?'):
         info['var'] = 'somethingelse'
     ```
-
     Where:
         - `physinfo` and `info` are dedicated keywords,
         - 'somepattern' is the name of the file,
         - 'var' is a bids key in the list below
         - 'somethingelse' is the value of the key
-
-    Parameters
-    ----------
-    physinfo: str
-        Name of the file or partial match
-    info: dictionary of str
-        Dictionary containing BIDS keys
-
-    Returns
-    -------
-    info: dictionary of str
-        Populated dictionary containing BIDS keys
     """
+    info = {}
     # ################################# #
     # ##        Modify here!         ## #
     # ##                             ## #
@@ -61,16 +59,8 @@ def heur(physinfo, info):
         info['task'] = 'rest'
         info['run'] = '01'
         info['acq'] = 'resp'
-        # ############################## #
-        # ## Don't modify below this! ## #
-        # ############################## #
-    else:
-        # #!# Transform sys.exit in debug warnings or raiseexceptions!
-        # #!# Make all of the above a dictionary
-        LGR.warning(f'The heuristic {__file__} could not deal with {physinfo}')
-
-    # filename spec: sub-<label>[_ses-<label>]_task-<label>[_acq-<label>] ...
-    #                ... [_ce-<label>][_dir-<label>][_rec-<label>] ...
-    #                ... [_run-<index>][_recording-<label>]_physio
 
+    # ############################## #
+    # ## Don't modify below this! ## #
+    # ############################## #
     return info

From 6c94afe6615ebdb29211ed8ef911be379ee56bbd Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Tue, 21 Apr 2020 20:20:46 +0200
Subject: [PATCH 17/20] Add logger that was in the heuristics before, update
 dictionary instead of reassigning it.

---
 phys2bids/phys2bids.py | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/phys2bids/phys2bids.py b/phys2bids/phys2bids.py
index 3a3a412bb..c0d6d61c0 100644
--- a/phys2bids/phys2bids.py
+++ b/phys2bids/phys2bids.py
@@ -112,8 +112,7 @@ def print_json(outfile, samp_freq, time_offset, ch_name):
 
 def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
     """
-    Import the heuristic file specified by the user and uses its output
-    to rename the file.
+    Import and use the heuristic specified by the user to rename the file.
 
     Parameters
     ----------
@@ -165,10 +164,12 @@ def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
 
     # Load heuristic and use it to fill dictionary
     heur = utils.load_heuristic(heur_file)
-    bids_keys = heur.heur(Path(filename).stem, bids_keys)
+    bids_keys.update(heur.heur(Path(filename).stem)
 
     # If bids_keys['task'] is still empty, stop the program
     if not bids_keys['task']:
+        LGR.warning(f'The heuristic {heur_file} could not deal with'
+                    f'{Path(filename).stem}')
         raise KeyError(f'No "task" attribute found')
 
     # Compose name by looping in the bids_keys dictionary

From 34fa496ba92ad81d85f3892e5c78e0863837629b Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Tue, 21 Apr 2020 20:27:20 +0200
Subject: [PATCH 18/20] Tiny parenthesis matter

---
 phys2bids/phys2bids.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/phys2bids/phys2bids.py b/phys2bids/phys2bids.py
index 7ffc24dba..9169d7f68 100644
--- a/phys2bids/phys2bids.py
+++ b/phys2bids/phys2bids.py
@@ -164,7 +164,7 @@ def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
 
     # Load heuristic and use it to fill dictionary
     heur = utils.load_heuristic(heur_file)
-    bids_keys.update(heur.heur(Path(filename).stem)
+    bids_keys.update(heur.heur(Path(filename).stem))
 
     # If bids_keys['task'] is still empty, stop the program
     if not bids_keys['task']:

From 2d64201ca6a061c0e21ae7d1c8bce1a47501fad7 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Tue, 21 Apr 2020 20:43:28 +0200
Subject: [PATCH 19/20] Update documentations

---
 docs/heuristic.rst                      | 23 ++++++++++++-----------
 docs/howto.rst                          |  4 ++--
 phys2bids/heuristics/heur_euskalibur.py |  7 ++++++-
 phys2bids/heuristics/heur_test_acq.py   |  7 ++++++-
 phys2bids/heuristics/heur_tutorial.py   |  7 ++++++-
 5 files changed, 32 insertions(+), 16 deletions(-)

diff --git a/docs/heuristic.rst b/docs/heuristic.rst
index ba9ae1732..08d70a6bb 100644
--- a/docs/heuristic.rst
+++ b/docs/heuristic.rst
@@ -22,26 +22,27 @@ Initialisation
 
 .. literalinclude:: ../phys2bids/heuristics/heur_tutorial.py
    :linenos:
-   :lines: 1-40
+   :lines: 1-43
 
 It's important **not to modify this part of the file**. Instead, you can copy and paste it into your own heuristic file.
 
-This file looks like a python function, initialised by two mandatory parameters:
--``physinfo`` is the information used to label your file. **At the moment, it corresponds to the name of the input file itself**. This is what you need to build your heuristic.
--``info`` is a `python dictionary <https://www.w3schools.com/python/python_dictionaries.asp>`_ passed by the main script that contains the BIDS keys, such as `sub` and `ses`, as well as all the possible keys you can add to your heuristics. This is what you will work with in creating your heuristic
+This file looks like a python function, initialised by a mandatory parameter, ``physinfo``.
+| ``physinfo`` is the information used to label your file. **At the moment, it corresponds to the name of the input file itself**. This is what you need to build your heuristic.
 
-The scripts imports ``fnmatch``, a nice python module that lets you use bash-like wildcards, as well as ``logger``, a module that let us log what happens in the program execution.
+The function initialises ``info``, a `python dictionary <https://www.w3schools.com/python/python_dictionaries.asp>`_ that contains the BIDS keys, such as `sub` and `ses`, as well as all the possible keys you can add to your heuristics. This is what you will work with in creating your heuristic.
+
+The scripts also imports ``fnmatch``, a nice python module that lets you use bash-like wildcards.
 
 Dictionaries
 ^^^^^^^^^^^^
 
 .. literalinclude:: ../phys2bids/heuristics/heur_tutorial.py
    :linenos:
-   :lines: 41-63
-   :lineno-start: 41
+   :lines: 44-67
+   :lineno-start: 44
    :dedent: 4
 
-| This is the core of the function, and the part that should be adapted to process your files. In practice, it's the beginning of a |statement|_.
+| This is the core of the function, and the part that should be adapted to process your files. In practice, it's a |statement|_.
 | You need an ``if`` or ``elif`` statement for each file that you want to process, that will test if the ``physinfo`` is similar to a string (first case) or exactly matches a string (second case). The content of the statement is a set of `variable initialisations as a string <https://www.w3schools.com/python/python_strings.asp>`_, with the only difference that you're populating a dictionary here. This means that instead of declaring something like ``var = 'something'``, you will declare something like ``info['var'] = 'something'``
 | The list of possible keys is in the comment above, and corresponds to the list of possible entities of the `BIDs specification <https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/06-physiological-and-other-continuous-recordings.html>`_:
 
@@ -68,11 +69,11 @@ Functional code
 
 .. literalinclude:: ../phys2bids/heuristics/heur_tutorial.py
    :linenos:
-   :lines: 64-
-   :lineno-start: 64
+   :lines: 68-
+   :lineno-start: 68
    :dedent: 4
 
-This part contains a simple warning call that will be reported to the logger if the heuristic file doesn't contain actual references to your input files.
+This part is very simple: it returns the dictionary populated by the correct statement to the main program.
 It's important **not to modify this part of the file**. Instead, you can copy and paste it into your own heuristic file.
 
 Using the heuristic file
diff --git a/docs/howto.rst b/docs/howto.rst
index 1a525e1e9..8dcdfb55d 100644
--- a/docs/howto.rst
+++ b/docs/howto.rst
@@ -282,8 +282,8 @@ Alright, now the really interesting part! This section will explain how to use t
 
 .. literalinclude:: ../phys2bids/heuristics/heur_tutorial.py
    :linenos:
-   :lines: 41-63
-   :lineno-start: 41
+   :lines: 44-62
+   :lineno-start: 44
 
 The heuristic file has to be written accordingly, with a set of rules that could work for all the files in your dataset. You can learn more about it if you check the `guide on how to set it up <heuristic.html>`_.
 In this case, our heuristic file looks for a file that contains the name ``tutorial``. It corresponds to the task ``test`` and run ``00``. Note that **only the task is required**, all the other fields are optional - look them up in the BIDs documentation and see if you need them.
diff --git a/phys2bids/heuristics/heur_euskalibur.py b/phys2bids/heuristics/heur_euskalibur.py
index a311de834..570c5991d 100644
--- a/phys2bids/heuristics/heur_euskalibur.py
+++ b/phys2bids/heuristics/heur_euskalibur.py
@@ -5,7 +5,12 @@ def heur(physinfo):
     """
     Set of if .. elif statements to fill BIDS names.
 
-    Require the user (you!) to adjust it accordingly!
+    It requires the user (you!) to adjust it accordingly!
+    It needs an ``if`` or ``elif`` statement for each file that 
+    needs to be processed.
+    The statement will test if the ``physinfo``:
+        - is similar to a string (first case), or
+        - exactly matches a string (second case).
 
     Parameters
     ----------
diff --git a/phys2bids/heuristics/heur_test_acq.py b/phys2bids/heuristics/heur_test_acq.py
index 0e9c4a01b..346733807 100644
--- a/phys2bids/heuristics/heur_test_acq.py
+++ b/phys2bids/heuristics/heur_test_acq.py
@@ -5,7 +5,12 @@ def heur(physinfo):
     """
     Set of if .. elif statements to fill BIDS names.
 
-    Require the user (you!) to adjust it accordingly!
+    It requires the user (you!) to adjust it accordingly!
+    It needs an ``if`` or ``elif`` statement for each file that 
+    needs to be processed.
+    The statement will test if the ``physinfo``:
+        - is similar to a string (first case), or
+        - exactly matches a string (second case).
 
     Parameters
     ----------
diff --git a/phys2bids/heuristics/heur_tutorial.py b/phys2bids/heuristics/heur_tutorial.py
index b1ce3384c..72b3c8797 100644
--- a/phys2bids/heuristics/heur_tutorial.py
+++ b/phys2bids/heuristics/heur_tutorial.py
@@ -5,7 +5,12 @@ def heur(physinfo):
     """
     Set of if .. elif statements to fill BIDS names.
 
-    Require the user (you!) to adjust it accordingly!
+    It requires the user (you!) to adjust it accordingly!
+    It needs an ``if`` or ``elif`` statement for each file that 
+    needs to be processed.
+    The statement will test if the ``physinfo``:
+        - is similar to a string (first case), or
+        - exactly matches a string (second case).
 
     Parameters
     ----------

From 3387c345270631b9c088357da0c95011751a7377 Mon Sep 17 00:00:00 2001
From: Stefano Moia <s.moia@bcbl.eu>
Date: Tue, 21 Apr 2020 20:51:09 +0200
Subject: [PATCH 20/20] It's always the whitespaces. Always.

---
 phys2bids/heuristics/heur_euskalibur.py | 2 +-
 phys2bids/heuristics/heur_test_acq.py   | 2 +-
 phys2bids/heuristics/heur_tutorial.py   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/phys2bids/heuristics/heur_euskalibur.py b/phys2bids/heuristics/heur_euskalibur.py
index 570c5991d..8c0e1d5e2 100644
--- a/phys2bids/heuristics/heur_euskalibur.py
+++ b/phys2bids/heuristics/heur_euskalibur.py
@@ -6,7 +6,7 @@ def heur(physinfo):
     Set of if .. elif statements to fill BIDS names.
 
     It requires the user (you!) to adjust it accordingly!
-    It needs an ``if`` or ``elif`` statement for each file that 
+    It needs an ``if`` or ``elif`` statement for each file that
     needs to be processed.
     The statement will test if the ``physinfo``:
         - is similar to a string (first case), or
diff --git a/phys2bids/heuristics/heur_test_acq.py b/phys2bids/heuristics/heur_test_acq.py
index 346733807..9f553dcfb 100644
--- a/phys2bids/heuristics/heur_test_acq.py
+++ b/phys2bids/heuristics/heur_test_acq.py
@@ -6,7 +6,7 @@ def heur(physinfo):
     Set of if .. elif statements to fill BIDS names.
 
     It requires the user (you!) to adjust it accordingly!
-    It needs an ``if`` or ``elif`` statement for each file that 
+    It needs an ``if`` or ``elif`` statement for each file that
     needs to be processed.
     The statement will test if the ``physinfo``:
         - is similar to a string (first case), or
diff --git a/phys2bids/heuristics/heur_tutorial.py b/phys2bids/heuristics/heur_tutorial.py
index 72b3c8797..eebc08259 100644
--- a/phys2bids/heuristics/heur_tutorial.py
+++ b/phys2bids/heuristics/heur_tutorial.py
@@ -6,7 +6,7 @@ def heur(physinfo):
     Set of if .. elif statements to fill BIDS names.
 
     It requires the user (you!) to adjust it accordingly!
-    It needs an ``if`` or ``elif`` statement for each file that 
+    It needs an ``if`` or ``elif`` statement for each file that
     needs to be processed.
     The statement will test if the ``physinfo``:
         - is similar to a string (first case), or