Adding Definitions

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 inherit from 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.GroupAFQ object. 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.GroupAFQ object 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.GroupAFQ object 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):

• The AFQ.api.group.GroupAFQ object 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.