Adding Definitions

pyAFQ uses definitions to allow users to customize the mappings, masks, etc. 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 three methods: __init__, find_path, and get_for_subses. 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. For scalar definitions, each class should have a name parameter (see AFQ.definitions.scalar.ScalarFile source for an example).

  • 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.mask.MaskFile.find_path() for a basic 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.mask.FullMask.find_path() source for an example.)

  • The AFQ.api.group.group.GroupAFQ object calls get_for_subses to get the mask, map, etc. during workflow construction or execution. The form of this method varies significantly between mapping, scalar, and mask Definition-inherited classes. get_for_subses must return a task which can be called to generate the mask. In scalar Definition-inherited classes, get_for_subses only takes the self argument and similarly returns a task which generates the mask. In mapping Definition-inherited classes, 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. In mapping Definition-inherited classes, get_for_subses takes as input self, subses_dict, reg_template, and reg_subject.