Spin compartments and spin selection

[JanWP]

Feature Request

Hi,

I would like to get your thoughts on a small extension to Phantom: keeping explicit per-spin compartment labels, and adding helpers to select spins by those labels. I'm looking for early feedback, this is far from a finished PR proposal. Mostly I'd like to know whether the idea feels useful to anyone but me and whether you think the rough API direction fits in with the rest of KomaMRI.

Why?

I have started to think about this in the context of a larger project to make spin properties a bit more flexible, but then I thought this might be useful for the current simulators as well.

Several phantom constructors already use tissue, material, species, or region labels internally to assign contrast parameters. After construction, that membership is usually lost and downstream code only sees spin-indexed vectors.

Keeping those labels on the phantom could make a few workflows more direct:

• tissue-specific editing of contrast parameters;
• ROI extraction and debugging;
• plotting or summarizing spins by tissue/material;
• defining regional motion or other spin-subset operations;
• preserving documented species/pool metadata from imported phantom formats.

Rough Model

The idea is to add static per-spin compartment labels to Phantom.

Compartments are discrete labels only. They do not define contrast values, motion, or simulation behavior. A label identifies membership in a tissue, material, species, region, or pool such as :GM, :WM, :fat, :blood, or :myocardium. For now, I would keep this simple: exactly one compartment label per spin.

When no labels are provided, existing behavior is preserved. We should probably assigning all spins to a default compartment in that case, tentatively :default.

My current thought is to normalize labels internally to Symbols, while accepting both Symbol and AbstractString at public boundaries. For built-in phantoms, I would reuse labels already present in source tables or masks. I think a global KomaMRI label ontology is out-of-scope, at least for now.

Fit With Existing Code

Labels should live on Phantom, since they are spin-aligned sample metadata. They would follow the usual phantom operations:

• obj[p] and @view obj[p];
• copy;
• equality;
• obj1 + obj2;
• precision conversion without numeric conversion of labels;
• no transfer to GPU memory unless future simulation methods consume it;
• .phantom file read/write, with old files defaulting to :default.

Current GPU simulation kernels consume numeric spin fields and motion, not compartment labels. If labels are needed to choose a spin subset, that selection should be resolved before backend transfer. We could keep the field present but treat it as a non-transferred leaf to avoid surprising manual gpu(obj) users while avoiding unnecessary GPU memory use.

How to perform spin selection

Existing SpinSpan, AllSpins, and SpinRange would remain unchanged. They are already-resolved index selectors: once constructed, they contain the spin indices or index range to use.

A compartment label such as :GM is different because it is unresolved without a specific phantom’s compartment metadata. To use the compartment labels to select a subset of spins I am leaning toward explicit helpers, because they make the label-to-index resolution visible:

idx = spin_indices(obj, :GM)
obj_gm = obj[idx]

sel = spin_selector(obj, :GM)
motion = translate(..., sel)

spin_indices returns concrete indices and is useful immediately, including for irregular tissue masks.

spin_selector could return existing AbstractSpinSpan values where the selection is exactly representable, for example AllSpins() or SpinRange. Irregular selections probably need a future arbitrary-index span type. I think that part would need more discussion before coming up with an API.

Overloading indexing may be a bit too invasive in adding a new meaning for the indexing operation and it couldn't be used for motion. So I'd avoid:

sel = obj[:GM]

Possible PR Split

If this seems worth pursuing, I imagine splitting it into small PRs:

1. Add compartment storage to Phantom, preserve all existing constructors and operations, and persist labels in .phantom files.
2. Add spin_indices and possibly a limited spin_selector for selections representable by existing span types.
3. Populate compartments in built-in phantoms and external readers where labels are already documented or implicit and unambiguous.

Questions

The obvious one is: Do you think compartments and per-compartment selection would be a useful addition to KomaMRI? I have briefly checked existing feature requests and have not found anything.

Do you see anything wrong with the direction I took in thinking about this? Any obvious design flaws?

And then there are the technicalities:

• Did I forget any phantom operations we need to handle?
• Do you think symbols are a good fit to store labels internally while accepting strings at API and file-I/O boundaries?
• Should the first PR include only spin_indices, or also a limited spin_selector? Or do you prefer a larger PR once everything is in?
• Is a future arbitrary-index AbstractSpinSpan desirable for irregular compartment selections, especially for motion APIs?
• Does treating compartments as CPU-side leaf metadata during GPU transfer match expectations for gpu(obj)?
• What are the requirements for backwards compatibility of the .phantom files? Would this require a version bump on KomaMRIFiles?

[cncastillo]

This sounds interesting. @pvillacorta @mcgrathcm what do you think?

[cncastillo]

After thinking about this ... I think I like the idea, but I would probably drop all that info at the simulation level as I dont want to have simulation depend on these labels. For exchange between pools (Bloch-McConnell) and stuff like that (where the pool could be interesting inside the simulation) I would force a new Phantom with pools.

Also, the tags could generate some performance issues if the tags are not ordered:

spin 1 - :WM
spin 2 - :GM
spin 3 - :CSF
spin 4 - :WM
spin 5 - :GM
spin 6 - :CSF
...

Then, obj[:WM] (better than spin_selector, to extend the getindex for Symbol's) would not be very performant. So i would try to force tags to be a range, :WM => 1:100, :GM => 101:200, etc.

Therefore, the definition of phantoms with tags would need to be like this:

obj1 = Phantom(...., tag=:WM)
obj2 = Phantom(...., tag=:GM)
obj = obj1 + obj2

[JanWP]

Thanks for the feedback!

Yes, I agree that the labels should not enter the simulation itself. I thought of them as useful in user space and potentially in simulation preparation.

I think requiring contiguous labels would really be limiting, though. Two reasons that come to my mind: The first is that the spins in some example phantoms (e.g. Brain2D and Brain3D) have a natural spatial order. A slice could be selected as a spin range. I know this is not guaranteed or an intrinsic requirement of phantoms, but it seems natural (for example in the motion docs where a spin range is associated with being the "upper half" of a phantom: https://juliahealth.org/KomaMRI.jl/stable/explanation/gen-2-motion). If the brain phantoms are re-ordered by tissue, I wouldn't be surprised if that breaks existing user code relying implicitly on spatial ordering. And in some applications a different order could be natural. The free ordering of spins in KomaMRI phantoms is really a strength in my mind, and I think it would be a shame to limit that.

The other reason is that a natural next step of the concept could be to allow several labels per spin, to handle different categories (tissue, anatomy...): :WM, :GM, :left_hemisphere, :right_hemisphere etc. Then ordering by label becomes impossible. I think this is where the concept could really become useful, if labels are not necessarily mutually exclusive. That's a direction I have not explored at all, though. I have working prototype code for a single label per spin, but not more.

I agree that making labels useful for motion is a strong argument for contiguous labels. And I must admit that I haven't thought about performance much. The former could maybe be handled by an arbitrary-index AbstractSpinSpan? And performance is a point I have yet to look into. You have a much better understanding on that than I do - somehow that didn't strike me as a potential problem. My intuition without thinking much about it was that storing labels for large phantoms would be an issue in terms of memory consumption before it became an issue with performance.

What I'm still unsure about, is if the added value of labels being part of the phantom object is worth the added code complexity right now. In user space we can already build arbitrary-index vectors to select subsets of spins. Integrated handling in KomaMRI would allow us to keep info neatly in one place, to save the info to .phantom files. And what I would like to do is to flexibly compose spin properties and maybe motion flexibly using labels (pending a solution for the issue of ordering). But maybe judging the value of that needs to wait until that work has progressed more?

[pvillacorta]

Hi! Sorry for the delay in my response (just came back from ISMRM).

I think this is a great idea. Personally, I have already faced situations where I needed to separate tissues within a phantom, so the use of labels definitely makes sense to me.

Regarding label order, my intuition tells me that they should not be necessarily ordered. As @JanWP has mentioned, that might be the actual value of them. While performance problems might appear for phantom spin selection, nothing should change when simulating, as labels would not be used for that. Additionally, spin selection is an action that is not used that regularly; operations such as obj_gm = obj[:GM] are normally only executed once.

That said, some performance checks should definitely be made in the PR just to ensure that no significant regressions occur.

Thank you!

[mcgrathcm]

I also am convinced by the non-ordered argument. It makes sense to allow the user to structure the phantom as the see fit. In some cases, ordering by slice will make more sense than ordering by tissue, and vise versa. If at some point labelling (or label derived slicing) makes its way into the simulation, there could be a restructuring step prior to simulation that orders the phantom in an efficient way.