Usage example of source,target pair

This example illustrates how does the inference of the path_pattern from a (source,target) pair example works.

The main elements of this example are:

• A source example path of one of your files

• A target path that will be the expected mapping of your file.

• The from_io_example heuristic that internally does the inference work.

• A path pattern inferred from the above.

Be sure to read the Rules File Schema documentation section relating to the Paired Example before doing this example for more context.

graph LR S>"source path example"] B>"target path example"] AR(("from_io_example")) M>"path pattern"] S --> AR B --> AR AR --> M

The Rules File

The Rules File we are dealing here has the following path_analysis rule

import json # utility
from sovabids.files import _write_yaml # To print the yaml file

# The rule we are dealing with
rule = {
    'non-bids':{
        'path_analysis':
            {
            'source' : 'data/lemon/V001/resting/010002.vhdr',
            'target' : 'data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-resting_eeg.vhdr'
            }
        }
    }

yaml_file = _write_yaml(rule)

print('Rules File:\n\n',yaml_file)

Rules File:

 non-bids:
  path_analysis:
    source: data/lemon/V001/resting/010002.vhdr
    target: data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-resting_eeg.vhdr

The from_io_example function

Although this is hidden from the user, internally sovabids uses this function to infer the pattern.

The name of the function means “from input-output example”, as one provides an input and output pair of (source,target) paths.

Here we will illustrate how this function behaves. Lets see the documentation of the function:

from sovabids.heuristics import from_io_example # The function itself

print('from_io_example:\n\n',from_io_example.__doc__)

from_io_example:

 Get the path pattern from a source-target mapping example.

    The name of the function means "from input-output example", as one provides an input and output pair of (source,target) paths.

    Parameters
    ----------
    sourcepath : str
        The sourcepath that will be modified to get the path pattern
    targetpath : str
        The bidspath we are going to derive the information on.

    Returns
    -------
    dict :
        {
            'pattern': The path pattern in placeholder format.
        }

The result of the function

The function will return the placeholder pattern as explained in the Rules File Schema documentation section relating to the Placeholder Pattern .

sourcepath = rule['non-bids']['path_analysis']['source']
targetpath = rule['non-bids']['path_analysis']['target']
result = from_io_example(sourcepath,targetpath)

print('Result:\n\n',result)

Result:

 {'pattern': 'V%entities.session%/%entities.task%/%entities.subject%.vhdr'}

Ambiguity

This is explained in more detail in the warning section of the the Paired Example documentation . Be sure to read it before for fully understading what ambiguity means here.

An ambiguous rule would be:

rule = {
    'non-bids':{
        'path_analysis':
            {
            'source':'data/lemon/session001/taskT001/010002.vhdr',
            'target':'data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-T001_eeg.vhdr'
            }
        }
    }

yaml_file = _write_yaml(rule)

print('Ambiguous Example:\n\n',yaml_file)

Ambiguous Example:

 non-bids:
  path_analysis:
    source: data/lemon/session001/taskT001/010002.vhdr
    target: data_bids/sub-010002/ses-001/eeg/sub-010002_ses-001_task-T001_eeg.vhdr

If your example is ambiguous, the function will raise an error.

Notice the last bit of the message, it will hint you about what part of the example is suspected to have ambiguity.

from traceback import format_exc

try:
    sourcepath = rule['non-bids']['path_analysis']['source']
    targetpath = rule['non-bids']['path_analysis']['target']
    result = from_io_example(sourcepath,targetpath)
except:
    print('Error:\n\n',format_exc())

Error:

 Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/sovabids/checkouts/latest/examples/example_heuristic_source_target_pair.py", line 116, in <module>
    result = from_io_example(sourcepath,targetpath)
  File "/home/docs/checkouts/readthedocs.org/user_builds/sovabids/checkouts/latest/sovabids/heuristics.py", line 48, in from_io_example
    pattern = parse_path_pattern_from_entities(sourcepath,bids_entities)
  File "/home/docs/checkouts/readthedocs.org/user_builds/sovabids/checkouts/latest/sovabids/parsers.py", line 257, in parse_path_pattern_from_entities
    raise ValueError(f'{val} seems to be ambiguous with any of the following values {possible_ambiguity_with}')
ValueError: T001 seems to be ambiguous with any of the following values {'001'}