:py:mod:`sovabids.rules`
========================

.. py:module:: sovabids.rules

.. autoapi-nested-parse::

   Module dealing with the rules for bids conversion.



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


Functions
~~~~~~~~~

.. autoapisummary::

   sovabids.rules._regex_match
   sovabids.rules.get_info_from_path
   sovabids.rules.get_files
   sovabids.rules.load_rules
   sovabids.rules.apply_rules_to_single_file
   sovabids.rules.apply_rules
   sovabids.rules.sovapply



Attributes
~~~~~~~~~~

.. autoapisummary::

   sovabids.rules.LOGGER


.. py:data:: LOGGER

   

.. py:function:: _regex_match(pattern, string)


.. py:function:: get_info_from_path(path, rules)

   Parse information from a given path, given a set of rules.

   :param path: The path from where we want to extract information.
   :type path: str
   :param rules: A dictionary following the "Rules File Schema".
   :type rules: dict

   .. rubric:: Notes

   See the Rules File Schema documentation for the expected schema of the dictionary.


.. py:function:: get_files(source_path, rules)

   Recursively scan the directory for valid files, returning a list with the full-paths to each.

   The valid files are given by the 'non-bids.eeg_extension' rule. See the "Rules File Schema".

   :param source_path: The path we want to obtain the files from.
   :type source_path: str
   :param rules: The path to the rules file, or the rules dictionary.
   :type rules: str|dict

   :returns: **filepaths** -- A list containing the path to each valid file in the source_path.
   :rtype: list of str


.. py:function:: load_rules(rules)

   Load rules if given a path, bypass if given a dict.

   :param rules: The path to the rules file, or the rules dictionary.
   :type rules: str|dict

   :returns: The rules dictionary.
   :rtype: dict


.. py:function:: apply_rules_to_single_file(file, rules, bids_path, write=False, preview=False)

   Apply rules to a single file.

   :param file: Path to the file.
   :type file: str
   :param rules: Path to the rules file or rules dictionary.
   :type rules: str|dict
   :param bids_path: Path to the bids directory
   :type bids_path: str
   :param write: Whether to write the converted files to disk or not.
   :type write: bool, optional
   :param preview: Whether to return a dictionary with a "preview" of the conversion.
                   This dict will have the same schema as the "Mapping File Schema" but may have flat versions of its fields.
                   *UNDER CONSTRUCTION*
   :type preview: bool, optional

   :returns: * **mapping** (*dict*) -- The mapping obtained from applying the rules to the given file
             * **preview** (*bool|dict*) -- If preview = False, then False. If True, then the preview dictionary.


.. py:function:: apply_rules(source_path, bids_path, rules, mapping_path='')

   Apply rules to a set of files.

   :param source_path: If str, the path with the files we want to convert to bids.
                       If list of str with the paths of the files we want to convert (ie the output of get_files).
   :type source_path: str | list of str
   :param bids_path: The path we want the converted files in.
   :type bids_path: str
   :param rules: The path to the rules file, or a dictionary with the rules.
   :type rules: str|dict
   :param mapping_path: The fullpath where we want to write the mappings file.
                        If '', then bids_path/code/sovabids/mappings.yml will be used.
   :type mapping_path: str, optional

   :returns:

             A dictionary following: {
                                         'General': rules given,
                                         'Individual':list of mapping dictionaries for each file
                                     }
   :rtype: dict


.. py:function:: sovapply()

   Console script usage for applying rules.