Merge branch 'main' into separator_fix

cubids/metadata_merge.py

@@ -1,4 +1,8 @@
-"""Tools for merging metadata."""
+"""Metadata merging utilities for CuBIDS.
+
+This module provides utilities for merging metadata in CuBIDS, including functions
+for checking merging operations, grouping acquisitions, and handling metadata fields.
+"""
 
 import json
 from collections import defaultdict
@@ -179,15 +183,44 @@ def merge_without_overwrite(source_meta, dest_meta_orig, raise_on_error=False):
 
 
 def is_nan(val):
-    """Return True if val is NaN."""
+    """Check if the given value is NaN (Not a Number).
+
+    Parameters
+    ----------
+    val : any
+        The value to check.
+
+    Returns
+    -------
+    bool
+        True if the value is NaN, False otherwise.
+    """
     if not isinstance(val, float):
         return False
 
     return isnan(val)
 
 
 def print_merges(merge_list):
-    """Print formatted text of merges."""
+    """Print formatted text of merges.
+
+    Parameters
+    ----------
+    merge_list : list of tuple
+        A list of tuples where each tuple contains two elements:
+
+        - src_id : tuple
+            The source identifier, where the last element is the source ID and
+            the first element is the source name.
+        - dest_id : tuple
+            The destination identifier, where the last element is the destination
+            ID and the first element is the destination name.
+
+    Returns
+    -------
+    str
+        A formatted string representing the merges, with each merge on a new line.
+    """
     merge_strings = []
     for src_id, dest_id in merge_list:
         src_id_str = f"{src_id[-1]}:{src_id[0]}"

cubids/validator.py

@@ -1,4 +1,8 @@
-"""Methods for validating BIDS datasets."""
+"""Methods for validating BIDS datasets.
+
+This module provides functions for validating BIDS datasets, including building
+subprocess commands for the BIDS validator and handling validation results.
+"""
 
 import glob
 import json
@@ -61,7 +65,24 @@ def get_bids_validator_version():
 
 
 def build_subject_paths(bids_dir):
-    """Build a list of BIDS dirs with 1 subject each."""
+    """Build a dictionary of BIDS directories with one subject each.
+
+    Parameters
+    ----------
+    bids_dir : str
+        The root directory of the BIDS dataset.
+
+    Returns
+    -------
+    dict
+        A dictionary where the keys are subject labels and the values are
+        lists of file paths associated with each subject.
+
+    Raises
+    ------
+    ValueError
+        If no subjects are found in the specified directory.
+    """
     bids_dir = Path(bids_dir)
     if not bids_dir.as_posix().endswith(os.sep):
         bids_dir = bids_dir / ""
@@ -87,7 +108,21 @@ def build_subject_paths(bids_dir):
 
 
 def build_first_subject_path(bids_dir, subject):
-    """Build a list of BIDS dirs with 1 subject each."""
+    """Build a dictionary containing BIDS directory paths for a single subject.
+
+    Parameters
+    ----------
+    bids_dir : str
+        The root directory of the BIDS dataset.
+    subject : str
+        The path to the subject directory.
+
+    Returns
+    -------
+    dict
+        A dictionary where the key is the subject label and the value is a list of file paths
+        within the subject directory and the root BIDS directory.
+    """
     bids_dir = Path(bids_dir)
     if not bids_dir.as_posix().endswith(os.sep):
         bids_dir = bids_dir / ""
@@ -223,7 +258,7 @@ def extract_summary_info(output):
 
 
 def update_dataset_description(path, new_info):
-    """Update or append information to dataset_description.json.
+    """Update or append information to dataset_description.json with new information.
 
     Parameters
     ----------

cubids/workflows.py

@@ -944,15 +944,36 @@ def remove_metadata_fields(bids_dir, container, fields):
 
 
 def print_metadata_fields(bids_dir, container):
-    """Print unique metadata fields.
+    """Print unique metadata fields from a BIDS dataset.
+
+    This function identifies and prints all unique metadata fields from
+    the `dataset_description.json` file in a BIDS directory. It can run
+    either directly in Python or within a specified container (Docker or
+    Singularity).
 
     Parameters
     ----------
     bids_dir : :obj:`pathlib.Path`
-        Path to the BIDS directory.
+        Path to the BIDS directory containing the `dataset_description.json` file.
     container : :obj:`str`
-        Container in which to run the workflow.
+        Name of the container (e.g., Docker, Singularity) to use for running the
+        `cubids print-metadata-fields` command. If `None`, the operation is performed
+        directly in Python without a container.
+
+    Raises
+    ------
+    SystemExit
+        Raised in the following cases:
+        - The `dataset_description.json` file is not found in the BIDS directory.
+        - The subprocess returns a non-zero exit code when executed in a container.
+
     """
+    # Check if dataset_description.json exists
+    dataset_description = bids_dir / "dataset_description.json"
+    if not dataset_description.exists():
+        logger.error("dataset_description.json not found in the BIDS directory.")
+        sys.exit(1)
+
     # Run directly from python
     if container is None:
         bod = CuBIDS(data_root=str(bids_dir), use_datalad=False)