🔧 Improve `coregistration_prep_vol` design for choosing whole-head/brain-only

[sgiavasis]

Related problem

The "selected functional volume" sbref generation nodeblock has a confusing flow for picking the input BOLD data.

• Its first choice for input BOLD is desc-brain_bold, which may not exist in the resource pool, leading to missing resource errors. There is also the possibility that desc-preproc_bold is already skull-stripped.
• There is conditional logic for the reg_with_skull option for coregistration, which chooses between desc-brain_bold for skull-stripped and either desc-motion_bold or bold for whole-head. However, there is no guarantee these two may be whole-head.

Proposed feature

Ideally, in the final engine iteration, SkullStripped status will be handled in the meta-data within the resource pool.

In the meantime, the easiest solution would probably be:

• Change the input to desc-preproc_bold and leave it to the user to enable BOLD masking if they want a skull-stripped sbref
• Change the whole-head input to something like desc-head_bold (which doesn't exist yet) similar to how we have for the T1w
• Create desc-head_bold as a bookmark resource - can also use just bold (raw BOLD ingressed) but this would exclude any other preprocessing done to it
• Possibly: add the ability to mask the sbref as an option within the nodeblock, or as its own nodeblock

Acceptance criteria

• Users can include the Selected Functional Volume option to create an sbref without needing desc-brain_bold in the resource pool.
• Flexible options for either brain or whole-head sbref via this nodeblock (and ideally all sbref nodeblocks) that are easy and clear to use

Alternatives

No response

Additional context

No response

[birajstha]

Do we really need mask_sbref switch in config?
It looks like this switch reg_with_skull functions similarly.

[shnizzedy]

Flexible options for either brain or whole-head sbref via this nodeblock (and ideally all sbref nodeblocks) that are easy and clear to use

― #2174 (comment)

In #2183, we have a NodeBlock

C-PAC/CPAC/registration/registration.py

Lines 3125 to 3139 in 94bd58f

	@nodeblock(
	name="mask_sbref",
	switch=[
	["registration_workflows", "functional_registration", "coregistration", "run"],
	[
	"registration_workflows",
	"functional_registration",
	"coregistration",
	"func_input_prep",
	"mask_sbref",
	],
	],
	inputs=["sbref", "space-bold_desc-brain_mask"],
	outputs=["sbref"],
	)

that replaces the whole-head sbref with a brain-masked sbref in the resource pool. That definitely is easy to use, but I'm not sure if it's clear ― might we need desc-brain_sbref and desc-head_sbref or is overwriting definitely the right move here?