Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 8 additions & 0 deletions src/mariepy/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")

Expand Down Expand Up @@ -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)
Expand Down
27 changes: 26 additions & 1 deletion src/mariepy/vop.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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__
Expand All @@ -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]:
Expand All @@ -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,
Expand Down
23 changes: 23 additions & 0 deletions tests/test_cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
32 changes: 32 additions & 0 deletions tests/test_vop.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"):
Expand Down
Loading