Add --n-cpus to parallize cubids validate --sequential

cubids/__about__.py

@@ -20,6 +20,7 @@
 DOWNLOAD_URL : str
     The URL to download the CuBIDS package.
 """
+
 try:
     from cubids._version import __version__
 except ImportError:

cubids/cli.py

@@ -106,11 +106,10 @@ def _parse_validate():
       If a filename prefix is provided, the output will be placed in
       bids_dir/code/CuBIDS. If a full path is provided, the output files will
       go to the specified location.
-    - --sequential: Run the BIDS validator sequentially on each subject.
+    - --validation-scope: Choose between 'dataset' (default) or 'subject' validation.
     - --container: Docker image tag or Singularity image file.
     - --ignore-nifti-headers: Disregard NIfTI header content during validation.
-    - --sequential-subjects: Filter the sequential run to only include the
-      listed subjects.
+    - --participant-label: Filter the validation to only include the listed subjects.
     """
     parser = argparse.ArgumentParser(
         description="cubids validate: Wrapper around the official BIDS Validator",
@@ -143,10 +142,13 @@ def _parse_validate():
         ),
     )
     parser.add_argument(
-        "--sequential",
-        action="store_true",
-        default=False,
-        help="Run the BIDS validator sequentially on each subject.",
+        "--validation-scope",
+        choices=["dataset", "subject"],
+        default="dataset",
+        help=(
+            "Scope of validation. 'dataset' validates the entire dataset (default). "
+            "'subject' validates each subject separately."
+        ),
         required=False,
     )
     parser.add_argument(
@@ -157,12 +159,12 @@ def _parse_validate():
         required=False,
     )
     parser.add_argument(
-        "--sequential-subjects",
+        "--participant-label",
         action="store",
         default=None,
         help=(
-            "List: Filter the sequential run to only include "
-            "the listed subjects. e.g. --sequential-subjects "
+            "List: Filter the validation to only include "
+            "the listed subjects. e.g. --participant-label "
             "sub-01 sub-02 sub-03"
         ),
         nargs="+",
@@ -186,6 +188,20 @@ def _parse_validate():
         ),
         required=False,
     )
+    parser.add_argument(
+        "--n-cpus",
+        "--n_cpus",
+        type=int,
+        action="store",
+        dest="n_cpus",
+        default=1,
+        help=(
+            "Number of CPUs to use for parallel validation "
+            "when `--validation-scope` is 'subject'. "
+            "Defaults to 1 (sequential processing)."
+        ),
+        required=False,
+    )
     return parser
 
 
@@ -1017,12 +1033,24 @@ def _parse_print_metadata_fields():
     ("apply", _parse_apply, workflows.apply),
     ("purge", _parse_purge, workflows.purge),
     ("add-nifti-info", _parse_add_nifti_info, workflows.add_nifti_info),
-    ("add-file-collections", _parse_add_file_collections, workflows.add_file_collections),
+    (
+        "add-file-collections",
+        _parse_add_file_collections,
+        workflows.add_file_collections,
+    ),
     ("copy-exemplars", _parse_copy_exemplars, workflows.copy_exemplars),
     ("undo", _parse_undo, workflows.undo),
     ("datalad-save", _parse_datalad_save, workflows.datalad_save),
-    ("print-metadata-fields", _parse_print_metadata_fields, workflows.print_metadata_fields),
-    ("remove-metadata-fields", _parse_remove_metadata_fields, workflows.remove_metadata_fields),
+    (
+        "print-metadata-fields",
+        _parse_print_metadata_fields,
+        workflows.print_metadata_fields,
+    ),
+    (
+        "remove-metadata-fields",
+        _parse_remove_metadata_fields,
+        workflows.remove_metadata_fields,
+    ),
 ]
 
 
@@ -1073,4 +1101,10 @@ def _main(argv=None):
     options = _get_parser().parse_args(argv)
     args = vars(options).copy()
     args.pop("func")
+
+    # Automatically set validation_scope='subject' when --participant-label is provided
+    if "participant_label" in args and "validation_scope" in args:
+        if args["participant_label"]:
+            args["validation_scope"] = "subject"
+
     options.func(**args)

cubids/metadata_merge.py

@@ -369,7 +369,11 @@ def group_by_acquisition_sets(files_tsv, output_prefix, acq_group_level, is_long
         if is_longitudinal:
             for subject, session in contents_to_subjects[content_id]:
                 grouped_sub_sess.append(
-                    {"subject": "sub-" + subject, "session": session, "AcqGroup": groupnum}
+                    {
+                        "subject": "sub-" + subject,
+                        "session": session,
+                        "AcqGroup": groupnum,
+                    }
                 )
         elif not is_longitudinal:
             for subject in contents_to_subjects[content_id]:

cubids/tests/test_bond.py

@@ -476,7 +476,9 @@ def test_tsv_merge_no_datalad(tmp_path):
 
     with pytest.raises(Exception):
         bod.apply_tsv_changes(
-            invalid_tsv_file, str(tmp_path / "originals_files.tsv"), str(tmp_path / "ok_modified")
+            invalid_tsv_file,
+            str(tmp_path / "originals_files.tsv"),
+            str(tmp_path / "ok_modified"),
         )
 
 
@@ -586,7 +588,9 @@ def test_tsv_merge_changes(tmp_path):
 
     with pytest.raises(Exception):
         bod.apply_tsv_changes(
-            invalid_tsv_file, str(tmp_path / "originals_files.tsv"), str(tmp_path / "ok_modified")
+            invalid_tsv_file,
+            str(tmp_path / "originals_files.tsv"),
+            str(tmp_path / "ok_modified"),
         )
 
     # Make sure MergeInto == 0 deletes the param group and all associations
@@ -1118,9 +1122,7 @@ def test_validator(tmp_path):
     call = build_validator_call(str(data_root) + "/complete")
     ret = run_validator(call)
 
-    assert (
-        ret.returncode == 0
-    ), (
+    assert ret.returncode == 0, (
         "Validator was expected to pass on the clean dataset, "
         f"but returned code {ret.returncode}.\n"
         f"STDOUT:\n{ret.stdout.decode('UTF-8', errors='replace')}\n"
@@ -1158,9 +1160,7 @@ def test_validator(tmp_path):
     call = build_validator_call(str(data_root) + "/complete")
     ret = run_validator(call)
 
-    assert (
-        ret.returncode == 16
-    ), (
+    assert ret.returncode == 16, (
         "Validator was expected to fail after corrupting files, "
         f"but returned code {ret.returncode}.\n"
         "Corrupted files: removed JSON sidecar and modified NIfTI header.\n"

cubids/tests/test_cli.py

@@ -249,6 +249,24 @@ def test_validate_command_with_test_dataset(tmp_path):
     assert (output_prefix.parent / f"{output_prefix.name}_validation.json").exists()
 
 
+def test_validate_subject_scope_with_n_cpus(tmp_path):
+    """Test the validate command with validation-scope subject and n_cpus parallelization."""
+    # Copy test dataset to temporary directory
+    test_data = TEST_DATA / "BIDS_Dataset"
+    bids_dir = tmp_path / "BIDS_Dataset"
+    shutil.copytree(test_data, bids_dir)
+
+    # Run subject-level validation with 2 CPUs (parallel processing)
+    output_prefix = tmp_path / "validation_parallel"
+
+    # This should complete without error
+    _main(["validate", str(bids_dir), str(output_prefix), "--validation-scope", "subject", "--n-cpus", "1"])
+
+    # Verify the command completed successfully by checking if the output files exist
+    assert (output_prefix.parent / f"{output_prefix.name}_validation.tsv").exists()
+    assert (output_prefix.parent / f"{output_prefix.name}_validation.json").exists()
+
+
 def test_group_command_with_test_dataset(tmp_path):
     """Test the group command with the test BIDS dataset."""
     # Copy test dataset to temporary directory