:py:mod:`sovabids.parsers`
==========================

.. py:module:: sovabids.parsers

.. autoapi-nested-parse::

   Module with parser utilities.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   sovabids.parsers.placeholder_to_regex
   sovabids.parsers.parse_from_placeholder
   sovabids.parsers.parse_from_regex
   sovabids.parsers.parse_entity_from_bidspath
   sovabids.parsers._modify_entities_of_placeholder_pattern
   sovabids.parsers.parse_entities_from_bidspath
   sovabids.parsers.parse_path_pattern_from_entities
   sovabids.parsers.find_bidsroot



.. py:function:: placeholder_to_regex(placeholder, encloser='%', matcher='(.+)')

   Translate a placeholder pattern to a regex pattern.

   :param placeholder: The placeholder pattern to translate.
   :type placeholder: str
   :param matcher: The regex pattern to use for the placeholder, ie : (.*?),(.*),(.+).
   :type matcher: str, optional
   :param encloser: The symbol which encloses the fields of the placeholder pattern.
   :type encloser: str, optional

   :returns: * **pattern** (*str*) -- The regex pattern.
             * **fields** (*list of str*) -- The fields as they appear in the regex pattern.


.. py:function:: parse_from_placeholder(string, pattern, encloser='%', matcher='(.+)')

   Parse string from a placeholder pattern.

   Danger: It will replace underscores and hyphens with an empty character in all fields
   except for the ignore field. This to accomodate to the bids standard restrictions automatically.

   :param string: The string to parse.
   :type string: str
   :param pattern: The placeholder pattern to use for parsing.
   :type pattern: str
   :param matcher: The regex pattern to use for the placeholder, ie : (.*?),(.*),(.+).
   :type matcher: str, optional
   :param encloser: The symbol which encloses the fields of the placeholder pattern.
   :type encloser: str, optional

   :returns: The dictionary with the fields and values requested.
   :rtype: dict


.. py:function:: parse_from_regex(string, pattern, fields, invalid_replace='')

   Parse string from regex pattern.

   Danger: It will replace underscores and hyphens with an empty character in all fields
   except for the ignore field. This to accomodate to the bids standard restrictions automatically.

   :param string: The string to parse.
   :type string: str
   :param pattern: The regex pattern to use for parsing.
   :type pattern: str
   :param fields: List of fields in the same order as they appear in the regex pattern.
   :type fields: list of str
   :param invalid_replace: String that will replace '-' and '_' that appear on extracted fields.
   :type invalid_replace: str

   :returns: The dictionary with the fields and values requested.
   :rtype: dict


.. py:function:: parse_entity_from_bidspath(path, entity, mode='r2l')

   Get the value of a bids-entity from a path.

   :param path: The bidspath we are going to derive the information on.
                Should be the complete path of file of a modality (ie an _eeg file).
   :type path: str
   :param entity: The entity we are going to extract.
                  SHOULD be one of sub|ses|task|acq|run
   :type entity: str
   :param mode: Direction of lookup. One of r2l|l2r .
                r2l (right to left)
                l2r (left to right)
   :type mode: str

   :returns: **value** -- The extracted value of the entity as a string.
             If None, it means the entity was not found on the string.
   :rtype: str


.. py:function:: _modify_entities_of_placeholder_pattern(pattern, mode='append')

   Convert between sovabids entities pattern notation and the shorter notation.

   The shorter notation is:
   %dataset%, %task%, %session%, %subject%, %run%, %acquisition%

   :param string: The pattern string to convert.
   :type string: str
   :param mode: Whether to append 'entities' or cut it. One of {'append','cut'}
   :type mode: str

   :returns: The converted pattern string.
   :rtype: str


.. py:function:: parse_entities_from_bidspath(targetpath, entities=['sub', 'ses', 'task', 'acq', 'run'], mode='r2l')

   Get the bids entities from a bidspath.

   :param targetpath: The bidspath we are going to derive the information on.
   :type targetpath: str
   :param entities: The entities we are going to extract.
                    Defaults to sub,ses,task,acq,run
   :type entities: list of str
   :param mode: Direction of lookup. One of r2l|l2r .
                r2l (right to left)
                l2r (left to right)
   :type mode: str

   :returns: A dictionary with the extracted entities.
             {'sub':'11','task':'resting','ses':'V1','acq':'A','run':1}
   :rtype: dict


.. py:function:: parse_path_pattern_from_entities(sourcepath, bids_entities)

   Get the path pattern from a path and a dictionary of bids entities and their values.

   :param sourcepath: The sourcepath that will be modified to get the path pattern
   :type sourcepath: str
   :param bids_entities: Dictionary with the entities and their values on the path.
                         Ie {'sub':'11','task':'resting','ses':'V1','acq':'A','run':1}
                         There should be no ambiguity between the sourcepath and each of the values.
                         Otherwise an error will be raised.
   :type bids_entities: dict

   :returns: The path pattern in placeholder format
   :rtype: str


.. py:function:: find_bidsroot(path)

   Get the bidsroot from an absolute path describing a bids file inside a subject subfolder.

   :param path: The absolute path to any bids file inside a sub- folder.
   :type path: str

   :returns: The bidsroot absolute path.
   :rtype: str