Merge pull request INT-NIT#162 from sifaoufatai/clean-branch

Improve documentation: add structured descriptions to each module

Author: sifaoufatai

.gitignore

@@ -56,6 +56,6 @@ Thumbs.db
 *~
 
 # Fichiers temporaires à ignorer
-BIDSTools/fff.json
-BIDSTools/ffffff.json
-BIDSTools/fff.CSV
+BIDSTools/dev_tests/fff.json
+BIDSTools/dev_tests/ffffff.json
+BIDSTools/dev_tests/fff.CSV

BIDSTools/BidsDatatype.py

@@ -1,30 +1,33 @@
 """
-BIDSTools/BidsDatatype.py, this file is used to load data types from a YAML file.
- this module aim  to load  all the data types defined by the BIDS standard. and provide a function to retrieve the value of a specific data type based on its name."""
-import yaml
+BidsDatatype.py
 
+This module loads and manages data types defined by the BIDS (Brain Imaging Data Structure) standard.
+It provides utilities to retrieve data type values from a YAML schema and facilitates working with BIDS-compliant datasets.
 
-def _load_data_types(yaml_path="ressources/schema/objects/datatypes.yaml"):
-    """
-    Load data types from a YAML file.
+Main Features:
+- Loads all BIDS data types from a YAML configuration file.
+- Provides access to data type names and values.
+- Facilitates lookup of data type values by name.
 
-    Args:
-        yaml_path (str): The path to the YAML file containing data type data.
+Typical Usage:
+    from BIDSTools.BidsDatatype import DataTypes
+    datatypes = DataTypes()
+    value = datatypes.get_data_type_value("anat")
+
+Refer to the BIDS specification for more details on data type definitions.
+"""
+import yaml
+from BIDSTools.resource_paths import DATATYPES_YAML
+from BIDSTools.helper import load_yaml_file
 
-    Returns:
-        dict: A dictionary containing data type data.
-    """
-    with open(yaml_path, 'r') as file:
-        data_types_data = yaml.safe_load(file)
-    return data_types_data
 
 
 class DataTypes:
     def __init__(self):
         """
         Initialize a DataTypes object and load data types from a YAML file.
         """
-        self.data_types = _load_data_types()
+        self.data_types = load_yaml_file(DATATYPES_YAML)
 
     def get_data_type_value(self, data_type_name):
         """

BIDSTools/BidsDirectoryStructure.py

@@ -1,18 +1,34 @@
 """
-this module aim  to load all all the directories defined by the BIDS standard, their level and their details
+BidsDirectoryStructure.py
+
+This module loads and manages directory structures defined by the BIDS (Brain Imaging Data Structure) standard.
+It provides utilities to retrieve, inspect BIDS directory structures .
+
+Main Features:
+- Loads all BIDS directories and their attributes from a YAML configuration file.
+- Provides access to directory names, levels, and requirements.
+- Facilitates validation and inspection of directory structures for BIDS compliance.
+
+Typical Usage:
+    from BIDSTools.BidsDirectoryStructure import DirectoryStructure
+    ds = DirectoryStructure()
+    print(ds.all_directory)
+
+Refer to the BIDS specification for directory structure guidelines.
 """
 
 from pathlib import Path
 import yaml
 import BIDSTools.helper as helper
+from resource_paths import DIRECTORIES_YAML
 
 
 class DirectoryStructure:
     def __init__(self):
         """
         Initialize a DirectoryStructure object with default parameters.
         """
-        self.relative_path = "ressources/schema/rules/directories.yaml"
+        self.relative_path = DIRECTORIES_YAML
         self.entity_directory = []
         self.all_directory = None
         self.value_directory = None

BIDSTools/BidsEmptyRepositoryGenerator.py

@@ -1,4 +1,13 @@
-"""BIDS Empty Repository Generator. This module generates an empty BIDS repository structure."""
+"""
+BidsEmptyRepositoryGenerator.py
+
+This module generates an empty BIDS (Brain Imaging Data Structure) repository structure.
+It creates the required directory .
+
+
+
+Refer to the BIDS specification for repository initialization guidelines.
+"""
 import sys
 from BIDSTools.Createfile import CreatFile
 from BIDSTools.Createdirectory import Createdirectory

BIDSTools/BidsEntity.py

@@ -1,27 +1,24 @@
-""" this module aim  to load all all the entities defined by the BIDS standard """
-import yaml
+"""
+BidsEntity.py
+
+This module loads and manages entities defined by the BIDS (Brain Imaging Data Structure) standard.
+It provides utilities to retrieve entity names and details .
+
 
 
+"""
+import yaml
+from BIDSTools.resource_paths import ENTITIES_YAML
+from BIDSTools.helper import load_yaml_file
+
 class Entity:
     def __init__(self):
         """
         Initialize an Entity object and load entities from a YAML file.
         """
-        self.entities = self._load_entities()
+        self.entities = load_yaml_file(ENTITIES_YAML)
 
-    def _load_entities(self, yaml_path="ressources/schema/objects/entities.yaml"):
-        """
-        Load entities from a YAML file.
-
-        Args:
-            yaml_path (str): The path to the YAML file containing entity data.
 
-        Returns:
-            dict: A dictionary containing entity data.
-        """
-        with open(yaml_path, 'r') as file:
-            entities_data = yaml.safe_load(file)
-        return entities_data
 
     def get_entity_name(self, entity_name):
         """

BIDSTools/BidsFilestructure.py

@@ -1,11 +1,29 @@
+"""
+BidsFilestructure.py
+
+This module loads and manages file structures defined by the BIDS (Brain Imaging Data Structure) standard.
+It provides utilities to retrieve, inspect, and validate BIDS file structures from YAML schemas.
+
+Main Features:
+- Loads all BIDS file structure rules from YAML configuration files.
+- Provides access to file names, directory levels, and file details.
+- Facilitates validation and inspection of file structures for BIDS compliance.
+
+Typical Usage:
+    from BIDSTools.BidsFilestructure import FileStructure
+    fs = FileStructure()
+    print(fs.all_files)
+
+Refer to the BIDS specification for file structure guidelines.
+"""
 
 import yaml
 
 import os
-
+from BIDSTools.resource_paths import CORE_FILES_YAML, DIRECTORIES_YAML, FILES_YAML, TABLES_YAML
 
 class FileStructure:
-    def __init__(self, relative_path="ressources/schema/rules/files/common/core.yaml"):
+    def __init__(self, relative_path=CORE_FILES_YAML):
         """
         Initialize a FileStructure object with a relative path to a YAML file.
 
@@ -27,7 +45,7 @@ def get_all_files(self):
         """
 
         with open(os.path.join(os.path.dirname(os.path.abspath(__file__)),
-                               'ressources/schema/objects/files.yaml'), 'r') as file:
+                               FILES_YAML), 'r') as file:
 
             file_rules = yaml.safe_load(file)
             if file_rules:
@@ -62,7 +80,7 @@ def get_detail(self):
         self.get_all_files()
         self.get_all_files_detail(self.relative_path)
         self.get_all_files_detail(os.path.join(os.path.dirname(os.path.abspath(__file__)),
-                                               "ressources/schema/rules/files/common/tables.yaml"))
+                                               TABLES_YAML))
         return self
 
     def get_detail_for_file(self, file_name):

BIDSTools/BidsModality.py

@@ -1,9 +1,32 @@
-""" this module aim  to load all all the modalities defined by the BIDS standard  so that we can get the value of a specific modality based on its name."""
+"""
+BidsModality.py
+
+This module provides functionality to load and manage all modalities defined by the BIDS (Brain Imaging Data Structure) standard.
+It enables retrieval of modality values based on their names, using a YAML schema as the source of truth for available modalities.
+
+Main Features:
+- Loads BIDS modalities from a YAML configuration file.
+- Provides access to modality names and details.
+- Facilitates lookup of modality information by name.
+
+Typical Usage:
+    modality = Modality()
+    available_modalities = modality.modalities
+    details = modality.modality_details
+Example:
+    modality = Modality()
+    print("Available Modalities:", modality.modalities)
+    print("Modality Details:", modality.modality_details)
+
+
+See the BIDS specification for more details on modality definitions.
+"""
 
 import yaml
 import os
 
-
+from BIDSTools.resource_paths import MODALITIES_YAML
+from BIDSTools.helper import load_yaml_file
 class Modality:
     def __init__(self, relative_path=None):
         """
@@ -17,7 +40,7 @@ def __init__(self, relative_path=None):
             # Get the directory where the current script is located
             script_dir = os.path.dirname(os.path.abspath(__file__))
             # Construct the absolute path to modalities.yaml
-            relative_path = os.path.join(script_dir, "ressources", "schema", "objects", "modalities.yaml")
+            relative_path = os.path.join(script_dir, MODALITIES_YAML)
 
         self.relative_path = relative_path
         self.modalities = []

BIDSTools/Createdirectory.py

@@ -1,13 +1,32 @@
 """
-this module contains the Createdirectory class that creates directory layout based on BIDS directory structure
+Createdirectory.py
+
+This module defines the Createdirectory class, which automates the creation of directory layouts compliant with the BIDS (Brain Imaging Data Structure) directory structure.
+
+Main Features:
+- Generates a BIDS-compliant directory tree for neuroimaging datasets.
+- Supports customization of subject ID, session ID, and modality.
+- Integrates with other BIDSTools components for file and entity management.
+
+Typical Usage:
+    creator = Createdirectory(output_path, sub_id=1, session_id=1, modality="micr")
+    creator.create_directories()
+    Example of outuput:
+    sub-1
+    └─ ses-1
+        └─ micr
+
+
+
+Refer to the BIDS specification for directory organization guidelines.
 """
 import json
 import os
-from BIDSTools.BidsFilestructure import FileStructure
-from BIDSTools.BidsDirectoryStructure import DirectoryStructure
-from BIDSTools.BidsEntity import Entity
-from BIDSTools.BidsDatatype import DataTypes
 from pathlib import Path
+from BIDSTools import BidsFilestructure
+from BIDSTools import BidsDirectoryStructure
+from BIDSTools import BidsEntity
+from BIDSTools import BidsDatatype
 
 
 class Createdirectory:
@@ -24,11 +43,11 @@ def __init__(self, output_path, sub_id=1, session_id=1, modality="micr"):
         self.session_path = None
         self.output_path = output_path
         self.dir_name = []
-        self.filestructure = FileStructure()
+        self.filestructure = BidsFilestructure.FileStructure()
         self.filestructure.get_detail()
-        self.directorystructure = DirectoryStructure()
-        self.entity = Entity()
-        self.dataType = DataTypes()
+        self.directorystructure = BidsDirectoryStructure.DirectoryStructure()
+        self.entity = BidsEntity.Entity()
+        self.dataType = BidsDatatype.DataTypes()
         self.sub_id = sub_id
         self.session_id = session_id
         self.modality = modality

BIDSTools/Createfile.py

@@ -1,10 +1,25 @@
 """
-this module contains the CreatFile class that creates files based on BIDS directory structure , its creat all files and dataset structure (especially  agnostic files)
+Createfile.py
+
+This module defines the CreatFile class for generating files and dataset structures based on the BIDS (Brain Imaging Data Structure) directory structure.
+It automates the creation of all required files, including modality-agnostic files, to ensure BIDS compliance.
+
+Main Features:
+- Creates empty files and structured datasets following BIDS specifications.
+- Integrates with BIDSTools file structure components.
+- Supports automated generation of modality-agnostic files.
+
+Typical Usage:
+    from BIDSTools.Createfile import CreatFile
+    creator = CreatFile(output_path)
+    creator.create_empty_file('dataset_description.json')
+
+Refer to the BIDS specification for file and dataset structure guidelines.
 """
 
 import json
 import os
-from .BidsFilestructure import FileStructure
+from BIDSTools.BidsFilestructure import FileStructure
 
 
 class CreatFile:

BIDSTools/Experiment.py

@@ -1,3 +1,22 @@
+"""
+Experiment.py
+
+This module defines the Experiment class for representing and managing experiment metadata in BIDS (Brain Imaging Data Structure) workflows.
+Each experiment is typically initialized from a row in a metadata CSV file, with dynamic attributes for each metadata field.
+
+Main Features:
+- Dynamically creates attributes for each metadata field.
+- Provides methods for attribute access, modification, and comparison.
+- Integrates with BIDSTools for experiment-based data processing.
+
+Typical Usage:
+    from BIDSTools import Experiment
+    exp = Experiment.Experiment(subject_id='01', session_id='01', modality='anat')
+    print(exp.subject_id)
+
+Refer to the BIDSTools documentation for more details on experiment management.
+"""
+
 import csv as csv
 import json
 import logging