Fix M0 scan variant name inheritance (#466)

* perf: stop renaming M0 scans; keep aslcontext rename and update M0 IntendedFor; add regression test

* perf(perf): only rename aslcontext/labeling when renaming ASL time series

* test(validator): expand assertion messages with decoded stdout/stderr for debugging

* validator: pass schema as file:// URL to deno validator to force bundled schema

* test(validator): expect return code 16 for corrupted dataset case

---------

Co-authored-by: Cursor Agent <[email protected]>

Author: singlesp

cubids/cubids.py

@@ -683,28 +683,19 @@ def change_filename(self, filepath, entities):
             new_physio = new_path.replace(new_scan_end, "_physio.tsv.gz")
             self.new_filenames.append(new_physio)
 
-        # Update ASL-specific files
-        if "/perf/" in filepath:
+        # Update ASL-specific files only when ASL timeseries is being renamed
+        if "/perf/" in filepath and old_suffix == "asl":
             old_context = filepath.replace(scan_end, "_aslcontext.tsv")
             if Path(old_context).exists():
                 self.old_filenames.append(old_context)
                 new_scan_end = "_" + suffix + old_ext
                 new_context = new_path.replace(new_scan_end, "_aslcontext.tsv")
                 self.new_filenames.append(new_context)
 
-            old_m0scan = filepath.replace(scan_end, "_m0scan.nii.gz")
-            if Path(old_m0scan).exists():
-                self.old_filenames.append(old_m0scan)
-                new_scan_end = "_" + suffix + old_ext
-                new_m0scan = new_path.replace(new_scan_end, "_m0scan.nii.gz")
-                self.new_filenames.append(new_m0scan)
-
-            old_mjson = filepath.replace(scan_end, "_m0scan.json")
-            if Path(old_mjson).exists():
-                self.old_filenames.append(old_mjson)
-                new_scan_end = "_" + suffix + old_ext
-                new_mjson = new_path.replace(new_scan_end, "_m0scan.json")
-                self.new_filenames.append(new_mjson)
+            # Do NOT rename M0 scans or their JSON sidecars. M0 files should
+            # retain their original filenames to preserve independent variability.
+            # The IntendedFor field in M0 JSONs will be updated below to point
+            # to the newly renamed ASL files.
 
             old_labeling = filepath.replace(scan_end, "_asllabeling.jpg")
             if Path(old_labeling).exists():

cubids/tests/test_bond.py

@@ -1118,7 +1118,14 @@ 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"
+        f"STDERR:\n{ret.stderr.decode('UTF-8', errors='replace') if getattr(ret, 'stderr', None) else ''}"
+    )
     parsed = parse_validator_output(ret.stdout.decode("UTF-8"))
 
     # change this assert
@@ -1151,7 +1158,15 @@ def test_validator(tmp_path):
     call = build_validator_call(str(data_root) + "/complete")
     ret = run_validator(call)
 
-    assert ret.returncode == 1
+    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"
+        f"STDOUT:\n{ret.stdout.decode('UTF-8', errors='replace')}\n"
+        f"STDERR:\n{ret.stderr.decode('UTF-8', errors='replace') if getattr(ret, 'stderr', None) else ''}"
+    )
 
     parsed = parse_validator_output(ret.stdout.decode("UTF-8"))
 

cubids/tests/test_perf_m0.py

@@ -0,0 +1,81 @@
+"""Tests for ASL/M0 renaming behavior.
+
+Ensures that when ASL scans are renamed with variant acquisition labels:
+- aslcontext files are renamed to match the ASL scan
+- M0 files (nii/json) are NOT renamed
+- M0 JSON IntendedFor entries are updated to point to the new ASL path
+"""
+
+import json
+from pathlib import Path
+
+from cubids.cubids import CuBIDS
+
+
+def _write(path: Path, content: str = ""):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+
+
+def test_m0_not_renamed_but_aslcontext_is_and_intendedfor_updated(tmp_path):
+    bids_root = tmp_path / "bids"
+    sub = "sub-01"
+    ses = "ses-01"
+
+    # Create minimal perf files
+    perf_dir = bids_root / sub / ses / "perf"
+    perf_dir.mkdir(parents=True, exist_ok=True)
+
+    asl_base = perf_dir / f"{sub}_{ses}_asl.nii.gz"
+    asl_json = perf_dir / f"{sub}_{ses}_asl.json"
+    m0_base = perf_dir / f"{sub}_{ses}_m0scan.nii.gz"
+    m0_json = perf_dir / f"{sub}_{ses}_m0scan.json"
+    aslcontext = perf_dir / f"{sub}_{ses}_aslcontext.tsv"
+
+    # Touch NIfTIs (empty is fine for this test) and sidecars
+    asl_base.write_bytes(b"")
+    m0_base.write_bytes(b"")
+
+    _write(asl_json, json.dumps({}))
+
+    # M0 IntendedFor should reference the ASL time series (participant-relative path)
+    intended_for_rel = f"{ses}/perf/{sub}_{ses}_asl.nii.gz"
+    _write(m0_json, json.dumps({"IntendedFor": [intended_for_rel]}))
+
+    _write(aslcontext, "label\ncontrol\nlabel\ncontrol\n")
+
+    c = CuBIDS(str(bids_root))
+
+    # Rename the ASL scan by adding a variant acquisition
+    entities = {"suffix": "asl", "acquisition": "VARIANTTest"}
+    c.change_filename(str(asl_base), entities)
+
+    # Old/new filenames prepared for ASL and aslcontext, but NOT for M0
+    assert str(asl_base) in c.old_filenames
+    assert any(fn.endswith("_asl.json") for fn in c.old_filenames)
+    assert any(fn.endswith("_aslcontext.tsv") for fn in c.old_filenames)
+
+    assert not any(fn.endswith("_m0scan.nii.gz") for fn in c.old_filenames)
+    assert not any(fn.endswith("_m0scan.json") for fn in c.old_filenames)
+
+    # Compute expected new ASL path and aslcontext path
+    expected_new_asl = perf_dir / f"{sub}_{ses}_acq-VARIANTTest_asl.nii.gz"
+    expected_new_aslcontext = perf_dir / f"{sub}_{ses}_acq-VARIANTTest_aslcontext.tsv"
+
+    assert str(expected_new_asl) in c.new_filenames
+    assert str(expected_new_aslcontext) in c.new_filenames
+
+    # M0 files remain with original names
+    assert m0_base.exists()
+    assert m0_json.exists()
+
+    # But M0 IntendedFor should now point to the new ASL relative path
+    with open(m0_json, "r") as f:
+        m0_meta = json.load(f)
+
+    new_rel = f"{ses}/perf/{sub}_{ses}_acq-VARIANTTest_asl.nii.gz"
+    assert "IntendedFor" in m0_meta
+    assert new_rel in m0_meta["IntendedFor"]
+    # Ensure old reference removed
+    assert intended_for_rel not in m0_meta["IntendedFor"]
+

cubids/validator.py

@@ -48,11 +48,18 @@ def build_validator_call(path, local_validator=False, ignore_headers=False, sche
         command.append("--ignoreNiftiHeaders")
 
     if schema is None:
-        schema = str(importlib.resources.files("cubids") / "data/schema.json")
+        schema_path = importlib.resources.files("cubids") / "data/schema.json"
+        schema_path = pathlib.Path(schema_path)
     else:
-        schema = str(schema.resolve())
+        schema_path = pathlib.Path(schema).resolve()
 
-    command += ["--schema", schema]
+    # The Deno-based validator expects a URL for --schema; use a file:// URI
+    if not local_validator:
+        schema_arg = schema_path.as_uri()
+    else:
+        schema_arg = str(schema_path)
+
+    command += ["--schema", schema_arg]
 
     return command