.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/example_heuristic_source_target_pair.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_example_heuristic_source_target_pair.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_example_heuristic_source_target_pair.py:


===================================
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 <https://sovabids.readthedocs.io/en/latest/rules_schema.html#paired-example>`_ before doing this example for more context.


.. mermaid::

    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

.. GENERATED FROM PYTHON SOURCE LINES 34-53

.. code-block:: Python


    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)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    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





.. GENERATED FROM PYTHON SOURCE LINES 54-63

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:


.. GENERATED FROM PYTHON SOURCE LINES 63-68

.. code-block:: Python


    from sovabids.heuristics import from_io_example # The function itself

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





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    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.
            }
    




.. GENERATED FROM PYTHON SOURCE LINES 69-75

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 <https://sovabids.readthedocs.io/en/latest/rules_schema.html#placeholder-pattern>`_ .



.. GENERATED FROM PYTHON SOURCE LINES 75-82

.. code-block:: Python

    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)






.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Result:

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




.. GENERATED FROM PYTHON SOURCE LINES 83-91

Ambiguity
----------

This is explained in more detail in `the warning section of the the Paired Example documentation <https://sovabids.readthedocs.io/en/latest/rules_schema.html#paired-example>`_ .
Be sure to read it before for fully understading what ambiguity means here.

An ambiguous rule would be:


.. GENERATED FROM PYTHON SOURCE LINES 91-106

.. code-block:: Python


    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)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    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





.. GENERATED FROM PYTHON SOURCE LINES 107-111

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.


.. GENERATED FROM PYTHON SOURCE LINES 111-119

.. code-block:: Python

    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())




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    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'}






.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.071 seconds)


.. _sphx_glr_download_auto_examples_example_heuristic_source_target_pair.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: example_heuristic_source_target_pair.ipynb <example_heuristic_source_target_pair.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: example_heuristic_source_target_pair.py <example_heuristic_source_target_pair.py>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_