Could you check the pyAFQ API commands?

Dear experts,

I want to perform tractometry with pyAFQ using whole-brain tractography results obtained using MRtrix. Our dMRI images were preprocessed with FSL TOPUP and EDDY. I fitted the CSD model to the preprocessed dMRI data and generated whole-brain streamlines using MRtrix3.
I read the pyAFQ GitHub and wrote API commands. They worked without error, but I’m not confident with them because I’m not familiar with Python.

Here, I would like to ask three questions.

  1. Are the following commands sufficient to achieve my goal (= segmenting bundles, calculating tract profiles)? Could you check if anything is missing? If you tell me any other points for improvement, it’s also welcome.
  2. The sub-N0001_dir-AP_coordsys_RASMM_trkmethod-probCSD_recogmented-AFQ_desc_profiles_dwi.csv was obtained as a result of export_all(). This file contains the dti_fa and dti_md for each node. Whether these values calculated based on the DTI model or the CSD model? I’m using the .tck file of the reconstructed tractographies using dMRI image fitted on the CSD model.
  3. Is it possible to calculate AD and RD as tract profiles? Is this possible by adding any optional command?

Command used :

The commands I used are below. To make it easy for pyAFQ to recognize, the file names have been simplified. The mask image was generated from an eddy-corrected b0 image using fslroi.

import os
import os.path as op
from AFQ.api.participant import ParticipantAFQ
from AFQ.definitions.image import ImageFile

bids_path = op.join('/media/brain', 'my_disk', 'my_project')

dwi_path = op.join(bids_path, 'derivatives', 'my_preproc_pipeline', 'sub-N0001', 'dwi', 'sub-N0001_dir-AP_dwi.nii.gz')
bval_path = op.join(bids_path, 'derivatives', 'my_preproc_pipeline', 'sub-N0001', 'dwi', 'sub-N0001_dir-AP_dwi.bval')
bvec_path = op.join(bids_path, 'derivatives', 'my_preproc_pipeline', 'sub-N0001', 'dwi', 'sub-N0001_dir-AP_dwi.bvec')

mask_path = op.join(bids_path, 'derivatives', 'my_preproc_pipeline', 'sub-N0001', 'dwi', 'sub-N0001_mask.nii.gz')
tck_path = op.join(bids_path, 'derivatives', 'my_tractography', 'sub-N0001', 'dwi', 'sub-N0001_CSD_Prob_ACT_5000000_tractography.tck')

out_dir = op.join(bids_path, 'derivatives', 'afq', 'sub-N0001')

brain_mask_definition = ImageFile(
	path = mask_path, 
	suffix = "mask", 
	filters = {"scope":"my_preproc_pipeline"})

myafq = ParticipantAFQ(
	dwi_path, bval_path, bvec_path, out_dir,
	import_tract = tck_path, 
	brain_mask_definition = brain_mask_definition, 
	mapping_definition = None)



Hi @Printemps,

This all looks correct to me, but pyAFQ provides a lot of ways to examine the outputs for their quality. For example, you should have an html file in every participant’s output folder that you can open in a browser to see whether the tract segmentations look reasonable, so you should be able to answer that question better by carefully examining these outputs. Given that it looks like the data is organized according to BIDS, I do wonder why you are using the ParticipantAFQ object, rather than GroupAFQ (see How pyAFQ uses BIDS — AFQ 1.3.2 documentation for some explanations).

To your specific questions: the tract profiles are calculated using the DTI model (that’s what the dti_* means). You can add AD and RD tract profiles by adding the following input to your initialization of GroupAFQ / ParticipantAFQ:

scalars = ['dti_fa', 'dti_md', 'dti_rd', 'dti_ad']

Dear @Ariel_Rokem ,

Thank you for your kind reply.

I used GroupAFQ when I started learning pyAFQ. Almost it worked, sometimes pyAFQ failed to find DWI images. I guess something wrong is here in my BIDS directory…anyway, it seems to be simple for me to use ParticipantAFQ because it just needs the full path of each file. Is there any essential difference between the processes carried out by GroupAFQ and ParticipantAFQ?

the tract profiles are calculated using the DTI model (that’s what the dti_* means).

Thank you for this clear answer. Can’t pyAFQ generate the tract profiles using the CSD model?



  1. Under the hood, ParticipantAFQ and GroupAFQ use identifical computational pipelines. The difference is just that GroupAFQ can take advantage of the BIDS structure to locate files related to a particular subject/session. So, no essential differences.

  2. To clarify: the default setting is to use the CSD model to generate the tractography streamlines (using probabilistic methods for direction getting) and to use the DTI model (or DKI, for multi-shell acquisitions) to compute the tract profile tissue properties, such as FA and MD.


Dear @Ariel_Rokem ,

Thank you for your reply.
You have given me a better understanding of pyAFQ.