Setting 'brain_mask_definition' in pyAFQ config.toml

1

The information about options and how to set / format the ‘brain_mask_definition’ in the config.toml file required for pyAFQ is unclear to me:

# This will be used to create
# the brain mask, which gets applied before registration to a
# template.
# If you want no brain mask to be applied, use FullImage.
# If None, use B0Image()
# Default: None
brain_mask_definition = ""

I’d like to be able to set similar to how it is defined in API examples:

brain_mask_definition = LabelledImageFile(
    suffix="seg",
    filters={"scope": "freesurfer"},
    exclusive_labels=[0])

Any suggestions or help would be greatly appreciated.

2

For brain_mask_definition, you can set it to the path of your brain mask.

minimal example:

from AFQ.api.participant import ParticipantAFQ
from AFQ.definitions.image import ImageFile
brain_mask_definition = ImageFile(path=mask_path)
myafq = ParticipantAFQ(
            dwi_path, bval_path, bvec_path, out_dir,
            import_tract=tck_path,
            brain_mask_definition=brain_mask_definition,
            mapping_definition=None)
myafq.export_all()

Best,
Steven

1 Like
3

Thank you. This is helpful if using the API but my question is how to set the brain_mask_definition in the config.toml file if using the command-line interface (CLI). I’m nearly about to give up trying to using the pyAFQ bash command and just revert to the API commands and run them through Python since it seems there’s more flexibility.

4

Ah sorry, read your question too quickly! Not sure how to change the config.toml to do this automatic filtering. Hopefully you figure it out or are able to switch to the API.

1 Like
5

Hello! I actually am having this exact same issue currently. I want to use the brain mask I created, however, when I try using the brain_mask_definition option in the configuration file, it does not work no matter how I try it. I know this was a year ago, but was wondering if you ever figured out how to do this? Or did you just switch to API commands? I would be so grateful for any insight from either of you!

6

Hi @juliafoley - thanks for posting about this. And apologies @njhunsak for not picking up your first posting (I finally figured out how to set up notifications from neurostars…).

@juliafoley : could you post the config file that you are using? Particularly the section where you are specifying the brain_mask_definition.

7

Hi Dr. Rokem! @Ariel_Rokem

Thank you so much for responding to this post. I truly appreciate it so much!

Currently, I am running pyAFQ with a configuration file that just has the path to my BIDs dataset which is working! All the configuration file has is:

[files]
bids_path = "/ZPOOL/data/projects/mdem/derivatives/PyAFQ"

Since we wanted to use our own brain mask, rather than have one created by the programm, we tried using the brain_mask_definition function

[files]
bids_path = "/ZPOOL/data/projects/mdem/derivatives/PyAFQ"
brain_mask_definition = "FullImage"

and also as

[files]
bids_path = "/ZPOOL/data/projects/mdem/derivatives/PyAFQ"
brain_mask_definition = "B0Image()"

If we entered anything other than FullImage, “”, or B0Image, (such as our file name or suffix or anything) we got a brain_mask_definition must be a definition error. Using the default, we continuously got the warning: “warning:afq: it is recommended that you provide a brain mask… otherwise, the default brain mask is calculated by using OTSU on the median filtered b0 image. This can be unreliable” When checking, the brain mask created by afq is slightly too small, so I just want to make sure I’m not missing out on any of the tracts.

I would appreciate any insight you have! Thank you so much

-Julia

8

OK - thanks! I realize that this is a bit confusing (and could possibly be better documented…), but the config file takes its instructions for image definitions as string-enclosed Python code, so, for example if you want to pull in a brain mask that was created by QSIprep (and is stored in the qsiprep derivatives folder of your BIDS dataset), than something like this should work:

brain_mask_definition = "ImageFile(suffix='mask', filters={'desc': 'brain', 'space': 'T1w', 'scope': 'qsiprep'})"

Is this one of the things you tried?

1 Like
9

Thank you so much for explaining this! I appreciate it so much. We did try a version of

brain_mask_definition = "ImageFile()"

But, I actually think we did not include all the arguments needed potentially. I did not realize we could enter it that way in the configuration file though the CLI. I currently have pyAFQ running now with its default arguments. But once it is done, I will absolutely try this and see if it is successful. Thank you so much again! I will update you after trying it this way to let you know.

10

Hi Dr. Rokem!

I commented back in this thread earlier today explaining my issue further, but I am just editing this post now to let you know I was able to get it to work with your help!

I believe I was originally including too much information, once I cut it down to just:

brain_mask_definition = "ImageFile(suffix='mask', filters={'desc': 'brain})"

it worked and is using our mask!!

Thank you so much for your help with this! I truly appreciate it so much!

-Julia

1 Like
11

Thanks Julia! Glad to hear it’s resolved on your end. For future reference, I think that it can work with more extensive BIDS filters, but things get a bit finicky. One thing that has tripped me up in the past is when the derivative pipeline in which I ask it to look has a dataset_description file with a non-compliant PipelineDescription. Not saying that’s what was happening here, but just want to make sure that anyone finding this in the future goes and carefully checks that everything matches (i.e., the name of the derivative folder, the name of the pipeline, etc.).