AFQ.definitions.image

Classes

ImageFile	Define an image based on a file.
FullImage	Define an image which covers a full volume.
RoiImage	Define an image which is all include ROIs or'd together.
LabelledImageFile	Define an image based on labels in a file.
ThresholdedImageFile	Define an image based on thresholding a file.
ScalarImage	Define an image based on a scalar.
ThresholdedScalarImage	Define an image based on thresholding a scalar image.
PVEImage	Define an CSF/GM/WM PVE image from a single file.
PVEImages	Define a CSF/GM/WM PVE image from three separate files.
TemplateImage	Define a scalar based on a template.

Module Contents

class AFQ.definitions.image.ImageFile(path=None, suffix=None, filters=None, resample=True)

Bases: ImageDefinition

Define an image based on a file. Does not apply any labels or thresholds; Generates image with floating point data. Useful for seed images, where threshold can be applied after interpolation (see example).

Parameters:

pathstr, optional

path to file to get image from. Use this or suffix. Default: None

suffixstr, optional

suffix to pass to bids_layout.get() to identify the file. Default: None

filtersstr, optional

Additional filters to pass to bids_layout.get() to identify the file. Default: {}

resamplebool, optional

Whether to resample the image to the DWI data. Default: True

Examples

seed_image = ImageFile(

suffix=”WM”, filters={“scope”:”dmriprep”})

api.GroupAFQ(tracking_params={“seed_image”: seed_image,

“seed_threshold”: 0.1})

resample = True

find_path(bids_layout, from_path, subject, session, required=True)

get_path_data_affine(dwi_path)

get_name()

get_image_getter(task_name)

class AFQ.definitions.image.FullImage

Bases: ImageDefinition

Define an image which covers a full volume.

Examples

brain_image_definition = FullImage()

get_name()

get_image_getter(task_name)

class AFQ.definitions.image.RoiImage(use_waypoints=True, use_presegment=False, use_endpoints=False, only_wmgmi=False, only_wm=False, dilate=True, tissue_property=None, tissue_property_n_voxel=None, tissue_property_threshold=None)

Bases: ImageDefinition

Define an image which is all include ROIs or’d together.

Parameters:

use_waypointsbool

Whether to use the include ROIs to generate the image.

use_presegmentbool

Whether to use presegment bundle dict from segmentation params to get ROIs.

use_endpointsbool

Whether to use the endpoints (“start” and “end”) to generate the image.

only_wmgmibool

Whether to only include portion of ROIs in the WM-GM interface.

only_wmbool

Whether to only include portion of ROIs in the white matter.

dilatebool

Whether to dilate the ROIs before combining them, according to the tolerance that will be used during bundle recognition.

tissue_propertystr or None

Tissue property from scalars to multiply the ROI image with. Can be useful to limit seed mask to the core white matter. Note: this must be a built-in tissue property. Default: None

tissue_property_n_voxelint or None

Threshold tissue_property to a boolean mask with tissue_property_n_voxel number of voxels set to True. Default: None

tissue_property_thresholdint or None

Threshold to threshold tissue_property if a boolean mask is desired. This threshold is interpreted as a percentile. Overrides tissue_property_n_voxel. Default: None

Examples

——–

seed_image = RoiImage()

api.GroupAFQ(tracking_params={“seed_image”: seed_image})

use_waypoints = True

use_presegment = False

use_endpoints = False

only_wmgmi = False

only_wm = False

dilate = True

tissue_property = None

tissue_property_n_voxel = None

tissue_property_threshold = None

get_name()

get_image_getter(task_name)

class AFQ.definitions.image.LabelledImageFile(path=None, suffix=None, filters=None, inclusive_labels=None, exclusive_labels=None, combine='or')

Bases: ImageFile, CombineImageMixin

Define an image based on labels in a file.

Parameters:

pathstr, optional

path to file to get image from. Use this or suffix. Default: None

suffixstr, optional

suffix to pass to bids_layout.get() to identify the file. Default: None

filtersstr, optional

Additional filters to pass to bids_layout.get() to identify the file. Default: {}

inclusive_labelslist of ints, optional

The labels from the file to include from the boolean image. If None, no inclusive labels are applied.

exclusive_labelslist of ints, optional

The labels from the file to exclude from the boolean image. If None, no exclusive labels are applied. Default: None.

combinestr, optional

How to combine the boolean images generated by inclusive_labels and exclusive_labels. If “and”, they will be and’d together. If “or”, they will be or’d. Note: in this class, you will most likely want to either set inclusive_labels or exclusive_labels, not both, so combine will not matter. Default: “or”

Examples

brain_image_definition = LabelledImageFile(

suffix=”aseg”, filters={“scope”: “dmriprep”}, exclusive_labels=[0])

api.GroupAFQ(brain_image_definition=brain_image_definition)

inclusive_labels = None

exclusive_labels = None

apply_conditions(image_data_orig, image_file)

class AFQ.definitions.image.ThresholdedImageFile(path=None, suffix=None, filters=None, lower_bound=None, upper_bound=None, as_percentage=False, combine='and')

Bases: ThresholdMixin, ImageFile

Define an image based on thresholding a file. Note that this should not be used to directly make a seed image. In those cases, consider thresholding after interpolation, as in the example for ImageFile.

Parameters:

pathstr, optional

path to file to get image from. Use this or suffix. Default: None

suffixstr, optional

suffix to pass to bids_layout.get() to identify the file. Default: None

filtersstr, optional

Additional filters to pass to bids_layout.get() to identify the file. Default: {}

lower_boundfloat, optional

Lower bound to generate boolean image from data in the file. If None, no lower bound is applied. Default: None.

upper_boundfloat, optional

Upper bound to generate boolean image from data in the file. If None, no upper bound is applied. Default: None.

as_percentagebool, optional

Interpret lower_bound and upper_bound as percentages of the total non-nan voxels in the image to include (between 0 and 100), instead of as a threshold on the values themselves. Default: False

combinestr, optional

How to combine the boolean images generated by lower_bound and upper_bound. If “and”, they will be and’d together. If “or”, they will be or’d. Default: “and”

Examples

brain_image_definition = ThresholdedImageFile(

suffix=”BM”, filters={“scope”:”dmriprep”}, lower_bound=0.1)

api.GroupAFQ(brain_image_definition=brain_image_definition)

class AFQ.definitions.image.ScalarImage(scalar)

Bases: ImageDefinition

Define an image based on a scalar. Does not apply any labels or thresholds; Generates image with floating point data. Useful for seed images, where threshold can be applied after interpolation (see example).

Parameters:

scalarstr

Scalar to threshold. Can be one of “dti_fa”, “dti_md”, “dki_fa”, “dki_md”.

Examples

seed_image = ScalarImage(

“dti_fa”)

api.GroupAFQ(tracking_params={

“seed_image”: seed_image, “seed_threshold”: 0.2})

scalar

get_name()

get_image_getter(task_name)

class AFQ.definitions.image.ThresholdedScalarImage(scalar, lower_bound=None, upper_bound=None, as_percentage=False, combine='and')

Bases: ThresholdMixin, ScalarImage

Define an image based on thresholding a scalar image. Note that this should not be used to directly make a seed image. In those cases, consider thresholding after interpolation, as in the example for ScalarImage.

Parameters:

scalarstr

Scalar to threshold. Can be one of “dti_fa”, “dti_md”, “dki_fa”, “dki_md”.

lower_boundfloat, optional

Lower bound to generate boolean image from data in the file. If None, no lower bound is applied. Default: None.

upper_boundfloat, optional

Upper bound to generate boolean image from data in the file. If None, no upper bound is applied. Default: None.

as_percentagebool, optional

Interpret lower_bound and upper_bound as percentages of the total non-nan voxels in the image to include (between 0 and 100), instead of as a threshold on the values themselves. Default: False

combinestr, optional

How to combine the boolean images generated by lower_bound and upper_bound. If “and”, they will be and’d together. If “or”, they will be or’d. Default: “and”

Examples

seed_image = ThresholdedScalarImage(

“dti_fa”, lower_bound=0.2)

api.GroupAFQ(tracking_params={“seed_image”: seed_image})

scalar

class AFQ.definitions.image.PVEImage(pve_order=None, path=None, suffix=None, filters=None, resample=True)

Bases: ImageDefinition

Define an CSF/GM/WM PVE image from a single file.

Parameters:

pve_orderstr

Order of PVEs in file. Should be a list of three strings, each of “csf”, “gm”, or “wm”, indicating which volume in the file corresponds to which tissue type.

pathstr, optional

path to file to get image from. Use this or suffix. Default: None

suffixstr, optional

suffix to pass to bids_layout.get() to identify the file. Default: None

filtersstr, optional

Additional filters to pass to bids_layout.get() to identify the file. Default: {}

resamplebool, optional

Whether to resample the image to the DWI data. Default: True

Examples

——–

pve = PVEImage(

pve_order=[“csf”, “gm”, “wm”], suffix=”pve”)

api.GroupAFQ(…, pve=pve)

pve_order = None

get_image_getter(task_name)

class AFQ.definitions.image.PVEImages(CSF_probseg, GM_probseg, WM_probseg)

Bases: ImageDefinition

Define a CSF/GM/WM PVE image from three separate files.

Parameters:

CSF_probsegImageFile

Corticospinal fluid segmentation file.

GM_probsegImageFile

Gray matter segmentation file.

WM_probsegImageFile

White matter segmentation file.

Examples

pve = PVEImages(

afm.ImageFile(suffix=”CSFprobseg”), afm.ImageFile(suffix=”GMprobseg”), afm.ImageFile(suffix=”WMprobseg”))

api.GroupAFQ(…, pve=pve)

probsegs

find_path(bids_layout, from_path, subject, session, required=True)

get_name()

get_image_getter(task_name)

class AFQ.definitions.image.TemplateImage(path)

Bases: ImageDefinition

Define a scalar based on a template. This template will be transformed into subject space before use.

Parameters:

pathstr

path to the template.

Examples

my_scalar = TemplateImage(

“path/to/my_scalar_in_MNI.nii.gz”)

api.GroupAFQ(scalars=[“dti_fa”, “dti_md”, my_scalar])

path

get_name()

get_image_getter(task_name)