clinicaio.directory
===================

.. py:module:: clinicaio.directory

.. autoapi-nested-parse::

   Path functions and classes.



Attributes
----------

.. autoapisummary::

   clinicaio.directory.LOGGER


Classes
-------

.. autoapisummary::

   clinicaio.directory._BIDSDirectoryMetaclass
   clinicaio.directory.BIDSDirectory


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

.. py:data:: LOGGER

.. py:class:: _BIDSDirectoryMetaclass

   Bases: :py:obj:`type`


   Metaclass for BIDSDirectory that automatically defines methods in subclasses
   based on configured subdirectory types for different entities.


.. py:class:: BIDSDirectory

   Bases: :py:obj:`clinicaio.path.BIDSPath`


   A directory in a BIDS dataset.

   Attributes:
       SUBDIRECTORY_TYPES_BY_ENTITY:
           An optional dict mapping entity types to subclasses of BIDSPath or
           BIDSDirectory. This can be used conveniently convert child nodes of
           a directory to custom subclasses by entity. For example, the
           BIDSDataset class can automatically convert its child subjects to
           instances of the class BIDSSubject.

       SUBCLASSES_BY_SUFFIX:
           Similar to SUBCLASSES_BY_ENTITY, this is an optional dict mapping
           suffixes to subclasses of BIDSPath or BIDSDirectory. Currently
           SUBCLASSES_BY_ENTITY will take precedence but this behavior may be
           configured by overriding the maybe_convert_child method.


   .. py:attribute:: SUBCLASSES_BY_ENTITY


   .. py:attribute:: SUBCLASSES_BY_SUFFIX


   .. py:method:: maybe_convert_child(bids_path: clinicaio.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:: get_child_paths(include_files: bool = True, include_dirs: bool = True)

      Get an iterator over file paths in this directory.

      Args:
          include_files:
              Include file (i.e. non-directory) paths.

          include_dirs:
              Include directory paths.

      Returns:
          The iterator over Path instances of the selected paths.



   .. py:method:: get_child_bids_paths(**kwargs)

      An iterable of BIDSPath instances of paths in this directory.

      Args:
          **kwargs:
              Keyword arguments passed through to get_paths.

      Returns:
          An iterator over BIDSPath instances.



   .. py:property:: child_entities

      The set of entities found in this directory's child node filepaths.



   .. py:method:: get_children_by_entity(entity: clinicaio.entities.EntityArg, value: clinicaio.entities.EntityValue = None, include: bool = True, **kwargs)

      Get an iterator over BIDS paths in this directory that match the target
      entity.

      Args:
          entity:
              The target entity.

          value:
              An optional entity value to match. If none, all paths with
              the given entity are matched.

          include:
              If True, return paths that match, else return paths that don't
              match.

          **kwargs:
              Keyword arguments passed through to get_bids_paths.

      Returns:
          A generator over instances of BIDSPath for each matching path.

      TODO:
          Maybe generalize this function to support multiple entities.



   .. py:method:: get_child_mapping_by_entity(entity: clinicaio.entities.EntityArg, *args, **kwargs)

      Get a dict mapping entity values to children of this directory
      containing that entity as instances of BIDSPath or a subclass thereof.

      Args:
          entity:
              The target entity.

          *args:
              Additional ositional arguments passed through to
              get_children_by_entity.

          **kwargs:
              Keyword arguments passed through to get_children_by_entity.

      Returns:
          A dict mapping entity values to instances of the class passed
          through to get_children_by_entity.



   .. py:method:: recurse_directory(filter_func: Optional[Callable[[Union[clinicaio.path.BIDSPath, BIDSDirectory]], bool]] = None)

      Recurse paths within this directory.

      Args:
          filter_func:
              A optional function that accepts a BIDSPath argument and returns
              a boolean to indicate if the path should be included in the
              results (True) or not (False).

      Returns:
          A generator over all directories and files in this directory, as
          instances of BIDSDirectory and BIDSPath, respectively, or subclasses
          thereof.



   .. 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:: add_custom_subclass_methods()
      :classmethod:


      Add custom caching accessors for the entity subdirectories specified in
      SUBDIRECTORY_TYPES_BY_ENTITY.