This tutorial prepares an heuristic file to process general phys2bids inputs.
Let's have a look under the hood of the heuristic files used in the tutorial. It's the file heur_tutorial.py in phys2bids/phys2bids/heuristics/:
../phys2bids/heuristics/heur_tutorial.py
We can split this file into three parts: the initialisation, the dictionaries, and the functional code.
../phys2bids/heuristics/heur_tutorial.py
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 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 function initialises info, a python dictionary 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.
../phys2bids/heuristics/heur_tutorial.py
if .. elif .. else 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, 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:
taskstands 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.runis the optional entity for the index of the scan in a group of same modalities (e.g. 2 resting states).recis the optional entity for the reconstruction algorithm.acqis the optional entity for the set of acquisition parameters.diris the optional entity for the phase encoding direction (see here).
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". 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.
Let's try to read the first statement in the example:
"If the name of the file (``physinfo``) contains the string ``'tutorial*'
, then assign the entitytaskwith valuetest, therunas number00, and the reconstruction used aslabchart``"*
Note that we used only a subset of possible entities.
../phys2bids/heuristics/heur_tutorial.py
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.
Once you modified your heuristic file or created a new one, you can save it anywhere you want, as a python script (somename.py). Check that the file is executable! Then, you will have to call phys2bids using the -heur, the -sub, and optionally the -ses, arguments:
phys2bids -in tutorial_file.txt -indir /home/arthurdent/git/phys2bids/phys2bids/tests/data/ -chtrig 1 -ntp 158 -tr 1.2 -outdir /home/arthurdent/physio -heur /home/arthurdent/git/phys2bids/phys2bids/heuristics/heur_tutorial.py -sub 006 -ses 01Remember to specify the full path to the heuristic file. A copy of the heuristic file will be saved in the site folder.
You can find more information in the relevant tutorial section.