pyAFQ uses definitions to allow users to customize the mappings and images
(see usage/image and usage/mapping),
used by the
AFQ.api.group.GroupAFQ object. All definitions ultimately
AFQ.definitions.utils.Definition. For a given subject and
session within the API, a definition is used to create a given mask, map, etc.
Definition-inherited classes must have two methods: __init__ and find_path.
The requirements of each of these methods are described below:
Definition-inherited classes have an __init__ method which the users uses to configure the the definition for a given instance of the
AFQ.api.group.GroupAFQobject. These __init__ methods must be thoroughly documented as they are what the user interacts with. The class must have attributes of same name as the __init__ args. This is important for reading/writing Definition-inherited classes as arguments to config files.
The api calls find_path during the
AFQ.api.group.GroupAFQobject initialization to let the definition find relevant files for the given subject and session. All find_path methods have the same input: bids_layout, from_path, subject, session. See
AFQ.definitions.image.ImageFile.find_path()for an example. If your definition does not need to run anything during
AFQ.api.group.GroupAFQobject initialization, simply override this method with a method that only passes (see
AFQ.definitions.image.FullImage.find_path()source for an example.)
Furthermore, mapping and image definitions each have their own required methods. Here is the mapping required method (get_for_subses):
AFQ.api.group.GroupAFQobject calls get_for_subses to get the map during workflow construction or execution. get_for_subses should return a “mapping”. The “mapping” must have transform and transform_inverse functions which each accept two arguments: (1) an ndarray called data and (2) **kwargs. get_for_subses takes as input self, subses_dict, reg_template, and reg_subject.
Image definitions require get_name, get_image_getter, get_image_direct:
get_name has no inputs and returns a name which should uniquely identify this image.
get_image_getter returns a method which can be called as task in the task workflow specified by its one input, task_name. This method can have any valid inputs for its task module and ouputs an image.
get_image_direct returns the image. It is similar to get_image_getter, but is called directly instead of being a task. Thus there are stricter restrictions on its inputs (see
AFQ.definitions.image.B0Image.get_image_getter()for an example). Some images cannot be generated using this method because they rely on later derivatives. In this case, raise a value error.