From be86a6f5c6cea9e56eb796d362cc5d018cf20006 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 18:30:37 +0000 Subject: [PATCH] Write an optional head-average safety factor into VOP files pypulseqpp reads global_safety_factor from a VOP file's metadata and multiplies every head-average SAR by it. The writer and the vops command take it with its basis line; a file without it gives head-average SAR a factor of 1. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MFB6QLPkuY13FdsMg5RBpE --- PLAN.md | 5 ++++- src/mariepy/cli.py | 8 ++++++++ src/mariepy/vop.py | 27 ++++++++++++++++++++++++++- tests/test_cli.py | 23 +++++++++++++++++++++++ tests/test_vop.py | 32 ++++++++++++++++++++++++++++++++ 5 files changed, 93 insertions(+), 2 deletions(-) diff --git a/PLAN.md b/PLAN.md index b64ed8b..e5880f1 100644 --- a/PLAN.md +++ b/PLAN.md @@ -64,13 +64,16 @@ The unit must be the same for every channel. Channel order is the coil model's. | `compression_margin` | Overestimation allowed in VOP compression | | `safety_factor` | Factor, at least 1, on every local SAR read from the file | | `safety_basis` | What the safety factor covers and where it comes from | +| `global_safety_factor` | Optional: factor, at least 1, on every head-average SAR read from the file; 1 when absent | +| `global_safety_basis` | With `global_safety_factor`: what it covers and where it comes from | | `transmit` | Optional: the transmit configuration the file is valid for, as the scanner reports it | | `mariepy_version` | Version that wrote the file | | `data_licence` | Licence of the file, set by its body models | pypulseqpp's `read_vops` reads the points, the head-average matrix of every body model and the metadata; its `check_sar` multiplies every local SAR by the -file's `safety_factor`. A factor on the matrices themselves would cancel in a +file's `safety_factor`, and every head-average SAR by its +`global_safety_factor` where the file carries one. A factor on the matrices themselves would cancel in a ratio of two drives' SAR, which is why it travels as metadata. ## Field maps diff --git a/src/mariepy/cli.py b/src/mariepy/cli.py index 3e865a3..261778f 100644 --- a/src/mariepy/cli.py +++ b/src/mariepy/cli.py @@ -255,6 +255,8 @@ def _vops(args) -> None: safety_basis=args.safety_basis, data_licence=licence, transmit=args.transmit, + global_safety_factor=args.global_safety_factor, + global_safety_basis=args.global_safety_basis, ) print(f"wrote {args.out} with mariepy {__version__} in {time.time() - t0:.0f}s") @@ -313,6 +315,12 @@ def main(argv: list[str] | None = None) -> None: vops.add_argument( "--transmit", help="the transmit configuration the scanner reports" ) + vops.add_argument( + "--global-safety-factor", type=float, help="on every head-average SAR read" + ) + vops.add_argument( + "--global-safety-basis", help="what the global safety factor covers, one line" + ) vops.set_defaults(run=_vops) args = parser.parse_args(argv) diff --git a/src/mariepy/vop.py b/src/mariepy/vop.py index 3808654..d219880 100644 --- a/src/mariepy/vop.py +++ b/src/mariepy/vop.py @@ -234,6 +234,8 @@ def write( safety_basis: str, data_licence: str, transmit: str | None = None, + global_safety_factor: float | None = None, + global_safety_basis: str | None = None, ) -> None: """Write the virtual observation points a pulse designer reads. @@ -276,12 +278,21 @@ def write( transmit Identity of the transmit configuration the file is valid for, as the scanner reports it; a scanner refuses a file written for another. + global_safety_factor + Factor, at least 1, every head-average SAR read from the file is + multiplied by, for what the head-average matrices do not carry, such as + a vendor cross-check that finds them low. Like ``safety_factor`` it + travels as metadata; a file without it gives head-average SAR a factor + of 1. + global_safety_basis + One line stating what ``global_safety_factor`` covers and where it + comes from; required with it. Raises ------ ValueError A stack is not Hermitian, the two stacks disagree on the channel count, - the safety factor is below 1 or has no basis, or the names do not match + a safety factor is below 1 or has no basis, or the names do not match the matrices they label. """ from mariepy import __version__ @@ -297,6 +308,17 @@ def write( raise ValueError(f"the safety factor is at least 1, got {safety_factor}") if not str(safety_basis).strip(): raise ValueError("the safety factor needs a basis stating what it covers") + if global_safety_factor is not None: + if not (np.isfinite(global_safety_factor) and global_safety_factor >= 1.0): + raise ValueError( + f"the global safety factor is at least 1, got {global_safety_factor}" + ) + if not str(global_safety_basis or "").strip(): + raise ValueError( + "the global safety factor needs a basis stating what it covers" + ) + elif global_safety_basis is not None: + raise ValueError("a global safety basis needs a global safety factor") names = [str(name) for name in channels] models = [str(name) for name in bodies] if len(names) != points.shape[-1]: @@ -323,6 +345,9 @@ def write( } if transmit is not None: metadata["transmit"] = str(transmit) + if global_safety_factor is not None: + metadata["global_safety_factor"] = float(global_safety_factor) + metadata["global_safety_basis"] = str(global_safety_basis) np.savez_compressed( path, vops=points, diff --git a/tests/test_cli.py b/tests/test_cli.py index 05ff60a..5623dc2 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -50,3 +50,26 @@ def test_vops_refuses_both_a_case_and_the_sphere(tmp_path): "test", ] ) + + +def test_vops_writes_the_global_safety_factor_it_is_given(tmp_path): + path = tmp_path / "vops.npz" + main( + [ + "vops", + "--sphere", + "--out", + str(path), + "--safety-factor", + "1.5", + "--safety-basis", + "test", + "--global-safety-factor", + "1.35", + "--global-safety-basis", + "vendor cross-check", + ] + ) + back = vop.read(path).metadata + assert back["global_safety_factor"] == 1.35 + assert back["global_safety_basis"] == "vendor cross-check" diff --git a/tests/test_vop.py b/tests/test_vop.py index 2585c16..c0706be 100644 --- a/tests/test_vop.py +++ b/tests/test_vop.py @@ -192,6 +192,38 @@ def test_the_transmit_identity_reads_back_and_is_absent_unless_given(tmp_path, d assert vop.read(path).metadata["transmit"] == "Head8Tx/8/0x1a2b3c4d" +def test_the_global_safety_factor_reads_back_and_is_absent_unless_given( + tmp_path, device +): + path, _, _, _ = _written(tmp_path, device) + assert "global_safety_factor" not in vop.read(path).metadata + path, _, _, _ = _written( + tmp_path, + device, + global_safety_factor=1.35, + global_safety_basis="vendor head SAR above the population's", + ) + back = vop.read(path).metadata + assert back["global_safety_factor"] == 1.35 + assert back["global_safety_basis"] == "vendor head SAR above the population's" + + +@pytest.mark.parametrize("factor", [0.9, float("nan")]) +def test_a_global_safety_factor_below_one_is_refused(tmp_path, device, factor): + with pytest.raises(ValueError, match="at least 1"): + _written(tmp_path, device, global_safety_factor=factor, global_safety_basis="x") + + +def test_a_global_safety_factor_without_a_basis_is_refused(tmp_path, device): + with pytest.raises(ValueError, match="basis"): + _written(tmp_path, device, global_safety_factor=1.2) + + +def test_a_global_safety_basis_without_its_factor_is_refused(tmp_path, device): + with pytest.raises(ValueError, match="needs a global safety factor"): + _written(tmp_path, device, global_safety_basis="x") + + @pytest.mark.parametrize("factor", [0.9, float("nan")]) def test_a_safety_factor_below_one_is_refused(tmp_path, device, factor): with pytest.raises(ValueError, match="at least 1"):