Mappings File Schema

The Mappings File setups the way the conversion is done from an individual point of view, that is, in a per-file basis. It is intended to be produced by the apply_rules (in the cli sovapply) module, or by a GUI editor that allows the user to edit the mapping in a per-file basis.

The Mappings File is in yaml format. As of now the purpose of this documentation is not to teach yaml (we may have a dedicated file for that in the future). For now, you can check this guide though.

The Typical Mapping File

A typical mapping file looks like this:

General:
IO:
    source: Y:\code\sovabids\_data\DUMMY\DUMMY_SOURCE
    target: Y:\code\sovabids\_data\DUMMY\DUMMY_BIDS_custom
channels:
    name:
    '0': ECG_CHAN
    '1': EOG_CHAN
    type:
    ECG_CHAN: ECG
    EOG_CHAN: EOG
dataset_description:
    Authors:
    - A1
    - A2
    Name: Dummy
non-bids:
    code_execution:
    - print('some good code')
    - print(raw.info)
    - print(some bad code)
    eeg_extension: .vhdr
    path_analysis:
    pattern: T%entities.task%/S%entities.session%/sub%entities.subject%_%entities.acquisition%_%entities.run%.vhdr
sidecar:
    EEGReference: FCz
    PowerLineFrequency: 50
    SoftwareFilters:
    Anti-aliasing filter:
        Roll-off: 6dB/Octave
        half-amplitude cutoff (Hz): 500
Individual:
- IO:
    source: Y:\code\sovabids\_data\DUMMY\DUMMY_SOURCE\T0\S0\sub0_0_0.vhdr
    target: Y:\code\sovabids\_data\DUMMY\DUMMY_BIDS_custom\sub-0\ses-0\eeg\sub-0_ses-0_task-0_acq-0_run-0_eeg.vhdr
channels:
    name:
    '0': ECG_CHAN
    '1': EOG_CHAN
    type:
    ECG_CHAN: ECG
    EOG_CHAN: EOG
dataset_description:
    Authors:
    - A1
    - A2
    Name: Dummy
entities:
    acquisition: '0'
    run: '0'
    session: '0'
    subject: '0'
    task: '0'
non-bids:
    code_execution:
    - print('some good code')
    - print(raw.info)
    - print(some bad code)
    eeg_extension: .vhdr
    path_analysis:
    pattern: T%entities.task%/S%entities.session%/sub%entities.subject%_%entities.acquisition%_%entities.run%.vhdr
sidecar:
    EEGReference: FCz
    PowerLineFrequency: 50
    SoftwareFilters:
    Anti-aliasing filter:
        Roll-off: 6dB/Octave
        half-amplitude cutoff (Hz): 500
- IO:
    source: Y:\code\sovabids\_data\DUMMY\DUMMY_SOURCE\T0\S0\sub0_0_1.vhdr
    target: Y:\code\sovabids\_data\DUMMY\DUMMY_BIDS_custom\sub-0\ses-0\eeg\sub-0_ses-0_task-0_acq-0_run-1_eeg.vhdr
channels:
    name:
    '0': ECG_CHAN
    '1': EOG_CHAN
    type:
    ECG_CHAN: ECG
    EOG_CHAN: EOG
dataset_description:
    Authors:
    - A1
    - A2
    Name: Dummy
entities:
    acquisition: '0'
    run: '1'
    session: '0'
    subject: '0'
    task: '0'
non-bids:
    code_execution:
    - print('some good code')
    - print(raw.info)
    - print(some bad code)
    eeg_extension: .vhdr
    path_analysis:
    pattern: T%entities.task%/S%entities.session%/sub%entities.subject%_%entities.acquisition%_%entities.run%.vhdr
sidecar:
    EEGReference: FCz
    PowerLineFrequency: 50
    SoftwareFilters:
    Anti-aliasing filter:
        Roll-off: 6dB/Octave
        half-amplitude cutoff (Hz): 500

Relation to the Rules File

As you may have noticed, the Mappings File has a lot of similiraties with the Rules File. This is because the Mappings File is just the rules after being applied to each file.

The General and Invididual Objects

Essentially, the mappings file will have a General and an Invididual object at the top level.

The General object will contain a copy of the “general” rules; the Individual object will hold rules for each of the files to be converted. That is, each file holds “a copy” of the rules along with the modifications that apply to that particular file.

General :
    rules
Individual :
    list of rules

In the example shown above you may notice that the General object does not have an entities object, thats because the entities object was inferred from the path_analysis rule. Nevertheless, the Individual object does show the entities object . That is because the entities object was filled by applying the path_analysis rule.

Note

As of now, the only object that actually shows the result of applying the rules is the entities object. The other ones will just show the rule applied to that particular file.

The Individual object as a list

An important difference between the General object and the Individual object is that the General object holds a single set of rules, whereas the Individual object maintains a list of them; in other words, one set of rules for each file. As a result of this, the Individual object will be a list; that why it has a (-) at the start of every mapping it holds:

General :
    rules
Individual :
    - rules for file 1
    - rules for file 2
    ...
    - rules for file N

THE IO object

A difference you will notice between the Rules File and the Mappings File is the IO object.

This object just holds input/output information, or more specifically, the source and target.

IO in the General object

For the General object we will have :

General:
IO:
    source: source path - root folder of the data to be converted (input)
    target: target path - root folder of the bids directory (output)

IO in the Invididual object

For one of the elements of the Invididual object we will have :

Individual:
IO:
    source: source filepath - non-bids input data to be converted
    target: target filepath - bids output of that file

Conclusions

In essence, the Mappings File is just the Rules File copied once for each file, plus one more to have the “General” perspective. The copies of the rules made for each file will also hold any modification of the rules that apply for that particular file.

The IO object just holds input/output information from the point-of-view of files.