clinicaio.path
==============

.. py:module:: clinicaio.path

.. autoapi-nested-parse::

   Path functions and classes.



Attributes
----------

.. autoapisummary::

   clinicaio.path.LOGGER
   clinicaio.path.KEY_DELIMITER
   clinicaio.path.COMPONENT_DELIMITER
   clinicaio.path.PathArg


Classes
-------

.. autoapisummary::

   clinicaio.path.BIDSPath


Functions
---------

.. autoapisummary::

   clinicaio.path.get_path
   clinicaio.path.check_name


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

.. py:data:: LOGGER

.. py:data:: KEY_DELIMITER
   :value: '-'


.. py:data:: COMPONENT_DELIMITER
   :value: '_'


.. py:function:: get_path(path: PathArg)

   Get the underlying Path object from a PathArg.


.. py:function:: check_name(name)

   Check entity and suffix names for invalid characters. This is used for keys
   and suffixes.

   Raises:
       ValueError:
           The name is invalid.


.. py:class:: BIDSPath

   BIDS path with parsed metadata.


   .. py:attribute:: extensions
      :type:  List[str]


   .. py:attribute:: entities
      :type:  collections.OrderedDict[str, Union[str, int]]


   .. py:attribute:: suffix
      :type:  Optional[str]
      :value: None



   .. py:attribute:: parent
      :type:  Optional[Union[BIDSDirectory, pathlib.Path]]
      :value: None



   .. py:method:: __post_init__()

      Validate that the data is BIDS-compliant.



   .. py:method:: asdict()

      Get the dict of attributes for this dataclass.

      Returns:
          The shallow copy of dict of attributes that can be used to
          instantiate a new instance via unpacking.



   .. py:property:: prime_entity

      The first entity in this path, or None if this path has no entities.



   .. py:property:: path

      The pathlib.Path object for this BIDSPath.



   .. py:method:: check()

      Check for errors in this path. Override this in subclasses to add
      specific logic for that subclass, such as checking entity values in
      names or that required files exist in a directory. The method should
      raise BIDSPathError or a subclass thereof if the check fails.



   .. py:method:: __str__()


   .. py:method:: __repr__()


   .. py:method:: from_path(path: PathArg, parent: Optional[BIDSDirectory] = None, is_root: bool = False)
      :classmethod:


      Create an instance of this class from a path and parent.

      Args:
          path:
              The path.

          parent:
              An optional BIDSDirectory subclass to return when the parent
              directory is requested.

          is_root:
              If True, treat path as the root directory of a dataset and skip
              entity checking. The filename's stem will be set to the suffix.

      Returns:
          An instance of this class.



   .. py:method:: from_bids_path(bids_path: BIDSPath)
      :classmethod:


      Create an instance of this class from another BIDSPath instance or
      subclass thereof.

      Args:
          bids_path:
              The BIDSPath instance.

      Returns:
          An instance of this class. If the input argument is already a direct
          instance of this class then it will be returned unchanged. Otherwise
          a new instance of this class will be created with shallow copies of
          the attributes in the input path.



   .. py:method:: get_entities_and_suffix(path: pathlib.Path)
      :classmethod:


      Parse the entities and suffix from a path.

      Args:
          path:
              The pathlib.Path object to parse.

      Returns:
          The OrderedDict of entities and the suffix.



   .. py:method:: get_entity_value(entity: clinicaio.entities.EntityArg)

      Get the value of an entity if it exits.

      Args:
          entity:
              The entity name.

      Returns:
          The entity value as a string if present, else None.



   .. py:method:: has_entity(entity: clinicaio.entities.EntityArg)

      Check if this path contains the given entity.

      Args:
          entity:
              The entity to check.

      Returns:
          True if this path contains the entity, else False.



   .. py:method:: matches_entity_value(entity: clinicaio.entities.EntityArg, value: clinicaio.entities.EntityValue)

      Check if this path matches the given entity value. If the value to match
      is an integer, the internal value will be converted to an integer before
      matching.

      Args:
          entity:
              The entity to match.

          value:
              The value to match.

      Returns:
          True if the values match, else False. Missing entities will also
          return False.



   .. py:method:: is_dir()

      True if this path is a directory, else False.



   .. py:method:: resolve()

      Resolve the path (equivalent to pathlib.Path.resolve()).



   .. py:method:: maybe_convert_child(bids_path: BIDSPath)

      Optionally convert a child BIDSPath instance to a different BIDSPath
      type. This function is invoked by the __div__ operator and can be
      overridden in subclasses to customize child paths by e.g. entity.

      When cnoverting types, it is recommended to invoke the from_bids_path()
      method of the target class with the given bids_path argument.

      Args:
          bids_path:
              The child BIDSPath instance.

      Returns:
          A child BIDSPath instance.



   .. py:method:: __div__(value: PathArg)

      Emulate Path's division operator.

      Args:
          value:
              The value to join to the path.

      Returns:
          The joined path as a BIDSPath or subclass thereof.



   .. py:property:: depth

      The depth of this path within a dataset's file hierarchy, or None if it
      is not part of one.



.. py:data:: PathArg