Adding Definitions

pyAFQ uses definitions to allow users to customize the mappings and images (see The pyAFQ Image API and The pyAFQ Mapping API), 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.