elikopy package

Submodules

elikopy.core module

Elikopy @author: qdessain, msimon

class elikopy.core.Elikopy(folder_path, cuda=False, slurm=False, slurm_email='example@example.com')

Bases: object

Main class containing all the necessary function to process and preprocess a specific study.

diamond(folder_path=None, patient_list_m=None, reportOnly=False, slurm=None, slurm_email=None, slurm_timeout=None, cpus=None, slurm_mem=None)

Computes the DIAMOND metrics for each subject. The outputs are available in the directories <folder_path>/subjects/<subjects_ID>/dMRI/microstructure/diamond/.

example : study.diamond()

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • patient_list_m – Define a subset of subjects to process instead of all the available subjects. example : [‘patientID1’,’patientID2’,’patientID3’]. default=None

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 14h by a custom timeout.

  • cpus – Replace the default number of slurm cpus of 4 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (6096MO by cpu) by a custom amount of ram.

dti(folder_path=None, patient_list_m=None, slurm=None, slurm_email=None, slurm_timeout=None, slurm_cpus=None, slurm_mem=None)

Computes the DTI metrics for each subject using Weighted Least-Squares. The outputs are available in the directories <folder_path>/subjects/<subjects_ID>/dMRI/dti/.

example : study.dti()

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • patient_list_m – Define a subset of subjects to process instead of all the available subjects. example : [‘patientID1’,’patientID2’,’patientID3’]. default=None

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 1h by a custom timeout.

  • slurm_cpus – Replace the default number of slurm cpus of 1 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (8096MO by cpu) by a custom amount of ram.

export(folder_path=None, raw=False, preprocessing=False, dti=False, noddi=False, diamond=False, mf=False, wm_mask=False, report=False, preprocessed_first_b0=False, patient_list_m=None, tractography=False)

Allows to obtain in a single Export folder the outputs of specific processing steps for all subjects.

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • patient_list_m – Define a subset of subjects to process instead of all the available subjects. example : [‘patientID1’,’patientID2’,’patientID3’]. default=None

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • raw – If true, copy the raw data of each subject in the Export folder. default=FALSE

  • preprocessing – If true, copy the preprocessed data of each subject in the Export folder. default=FALSE

  • dti – If true, copy the DTI outputs of each subject in the Export folder. default=FALSE

  • noddi – If true, copy the NODDI outputs of each subject in the Export folder. default=FALSE

  • diamond – If true, copy the DIAMOND outputs of each subject in the Export folder. default=FALSE

  • mf – If true, copy the MF outputs of each subject in the Export folder. default=FALSE

  • wm_mask – If true, copy the white matter mask of each subject in the Export folder. default=FALSE

  • report – If true, copy the quality control reports of each subject in the Export folder. default=FALSE

  • tractography – If true, copy the tractography outputs of each subject in the Export folder. default=FALSE

fingerprinting(dictionary_path=None, folder_path=None, CSD_bvalue=None, slurm=None, patient_list_m=None, slurm_email=None, slurm_timeout=None, cpus=None, slurm_mem=None)

Computes the Microstructure Fingerprinting metrics for each subject. The outputs are available in the directories <folder_path>/subjects/<subjects_ID>/dMRI/microstructure/mf/.

example : study.fingerprinting(dictionary_path=’my_dictionary’)

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • dictionary_path – Path to the dictionary of fingerprints (mandatory).

  • CSD_bvalue – If the DIAMOND outputs are not available, the fascicles directions are estimated using a CSD with the images at the b-values specified in this argument. default=None

  • patient_list_m – Define a subset of subjects to process instead of all the available subjects. example : [‘patientID1’,’patientID2’,’patientID3’]. default=None

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 20h by a custom timeout.

  • slurm_cpus – Replace the default number of slurm cpus of 1 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (8096MO by cpu) by a custom amount of ram.

noddi(folder_path=None, patient_list_m=None, force_brain_mask=False, slurm=None, slurm_email=None, slurm_timeout=None, cpus=None, slurm_mem=None)

Computes the NODDI metrics for each subject. The outputs are available in the directories <folder_path>/subjects/<subjects_ID>/dMRI/microstructure/noddi/.

example : study.noddi()

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • patient_list_m – Define a subset of subjects to process instead of all the available subjects. example : [‘patientID1’,’patientID2’,’patientID3’]. default=None

  • force_brain_mask – Force the use of a brain mask even if a whitematter mask exist. default=False

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 10h by a custom timeout.

  • cpus – Replace the default number of slurm cpus of 1 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (8096MO by cpu) by a custom amount of ram.

noddi_amico(folder_path=None, patient_list_m=None, force_brain_mask=False, slurm=None, slurm_email=None, slurm_timeout=None, slurm_cpus=None, slurm_mem=None)

Computes the NODDI amico metrics for each subject. The outputs are available in the directories <folder_path>/subjects/<subjects_ID>/dMRI/microstructure/noddi/.

example : study.noddi_amico()

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • patient_list_m – Define a subset of subjects to process instead of all the available subjects. example : [‘patientID1’,’patientID2’,’patientID3’]. default=None

  • force_brain_mask – Force the use of a brain mask even if a whitematter mask exist. default=False

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 10h by a custom timeout.

  • slurm_cpus – Replace the default number of slurm cpus of 1 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (8096MO by cpu) by a custom amount of ram.

noddi_fix_icvf_thresholding(folder_path=None, patient_list_m=None, fintra_threshold=0.99, fbundle_threshold=0.05, use_brain_mask=False, use_wm_mask=False)

A function to quickly change the treshold value applied on the icvf metric of noddi without the needs of executing again the full noddi core function.

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • patient_list_m – Define a subset of subjects to process instead of all the available subjects. example : [‘patientID1’,’patientID2’,’patientID3’]. default=None

  • fintra_threshold – Threshold applied on the fintra. default=0.99

  • fbundle_threshold – Threshold applied on the fbundle. default=0.05

  • use_brain_mask – Set to 0 values outside the brain mask. default=False

  • use_wm_mask – Set to 0 values outside the white matter mask. default=False

patient_list(folder_path=None, bids_path=None, reverseEncoding=True)

From the root folder containing data_1, data_2, … data_n folders with nifti files (and their corresponding bvals and bvecs), the Elikopy folder structure is created in a directory named ‘subjects’ inside folder_path. This step is mandatory. The validity of all the nifti present in the root folder is verified. If some nifti do not possess an associated bval and bvec file, they are discarded and the user is notified in a summary file named subj_error.json generated in the out sub-directory. All valid patients are stored in a file named patient_list.json. In addition to the nifti + bval + bvec, the data_n folders can also contain the json files (with the patient informations) as well as the acquparam, index and slspec files (used during the preprocessing). If these files are missing a warning is raised. In addition to the DW images, T1 structural images can be provided in a directory called ‘T1’ in the root folder.

example : study.patient_list()

Parameters

  • folder_path – Path to the root folder of the study. default = study_folder

  • bids_path – Path to the optional folder containing subjects’ data in the BIDS format.

  • reverseEncoding – Append reverse encoding direction to the DW-MRI data if available. default = True

patientlist_wrapper(function, func_args, folder_path=None, patient_list_m=None, filename=None, function_name=None, slurm=False, slurm_email=None, slurm_timeout=None, cpus=None, slurm_mem=None)

A wrapper function that apply a function given as an argument to every subject of the study. The wrapped function must takes two arguments as input, the patient_name and the path to the root of the study.

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • patient_list_m – Define a subset of subjects to process instead of all the available subjects. example : [‘patientID1’,’patientID2’,’patientID3’]. default=None

  • function – The pointer to the function (only without slurm /!)

  • func_args – Additional arguments to pass to the wrapped function (only without slurm /!)

  • filename – The name of the file containing the wrapped function (only with slurm /!)

  • function_name – The name of the wrapped function (only with slurm /!)

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 20h by a custom timeout.

  • cpus – Replace the default number of slurm cpus of 1 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (8096MO by cpu) by a custom amount of ram.

preproc(folder_path=None, reslice=False, reslice_addSlice=False, denoising=False, gibbs=False, topup=False, topupConfig=None, forceSynb0DisCo=False, useGPUsynb0DisCo=False, eddy=False, biasfield=False, biasfield_bsplineFitting=[100, 3], biasfield_convergence=[1000, 0.001], patient_list_m=None, starting_state=None, bet_median_radius=2, bet_numpass=1, bet_dilate=2, cuda=None, cuda_name='eddy_cuda10.1', s2v=[0, 5, 1, 'trilinear'], olrep=[False, 4, 250, 'sw'], slurm=None, slurm_email=None, slurm_timeout=None, cpus=None, slurm_mem=None, qc_reg=True, niter=5, slspec_gc_path=None, report=True)

Performs data preprocessing. By default only the brain extraction is enabled. Optional preprocessing steps include : reslicing, denoising, gibbs ringing correction, susceptibility field estimation, EC-induced distortions and motion correction, bias field correction. The results are stored in the preprocessing subfolder of each study subject <folder_path>/subjects/<subjects_ID>/dMRI/preproc.

example : study.preproc(denoising=True, topup=True, eddy=True, biasfield=True)

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • reslice – If true, data will be resliced with a new voxel resolution of 2*2*2. default=False

  • reslice_addSlice – If true, an additional empty slice will be added to each volume (might be useful for motion correction if one slice is dropped during the acquisition and the user still wants to perform easily the slice-to-volume motion correction). default=False

  • denoising – If true, MPPCA-denoising is performed on the data. default=False

  • gibbs – If true, Gibbs ringing correction is performed. We do not advise to use this correction unless the data suffers from a lot of Gibbs ringing artifacts. default=False

  • topup – If true, Topup will estimate the susceptibility induced distortions. These distortions are corrected at the same time as EC-induced distortions if eddy=True. In the absence of images acquired with a reverse phase encoding direction, a T1 structural image is required. default=False

  • topupConfig – If not None, Topup will use additionnal parameters based on the supplied config file located at <topupConfig>. default=None

  • forceSynb0DisCo – If true, Topup will always estimate the susceptibility field using the T1 structural image. default=False

  • eddy – If true, Eddy corrects the EC-induced (+ susceptibility, if estimated) distortions and the motion. If these corrections are performed the acquparam and index files are required (see documentation). To perform the slice-to-volume motion correction the slspec file is also needed. default=False

  • biasfield – If true, low frequency intensity non-uniformity present in MRI image data known as a bias or gain field will be corrected. default=False

  • biasfield_bsplineFitting – Define the initial mesh resolution in mm and the bspline order of the biasfield correction tool. default=[100,3]

  • biasfield_convergence – Define the maximum number of iteration and the convergences threshold of the biasfield correction tool. default=[1000,0.001]

  • patient_list_m – Define a subset of subjects to process instead of all the available subjects. example : [‘patientID1’,’patientID2’,’patientID3’]. default=None

  • starting_state – Manually set which step of the preprocessing to execute first. Could either be None, denoising, gibbs, topup, eddy, biasfield, report or post_report. default=None

  • bet_median_radius – Radius (in voxels) of the applied median filter during brain extraction. default=2

  • bet_numpass – Number of pass of the median filter during brain extraction. default=1

  • bet_dilate – Number of iterations for binary dilation during brain extraction. default=2

  • cuda – If true, eddy will run on cuda with the command name specified in cuda_name. default=False

  • cuda_name – name of the eddy command to run when cuda==True. default=”eddy_cuda10.1”

  • s2v – list of parameters of Eddy for slice-to-volume motion correction (see Eddy FSL documentation): [mporder,s2v_niter,s2v_lambda,s2v_interp]. The slice-to-volume motion correction is performed if mporder>0, cuda is used and a slspec file is provided during the patient_list command. default=[0,5,1,’trilinear’]

  • olrep – list of parameters of Eddy for outlier replacement (see Eddy FSL documentation): [repol,ol_nstd,ol_nvox,ol_type]. The outlier replacement is performed if repol==True. default=[False, 4, 250, ‘sw’]

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout by a custom timeout.

  • cpus – Replace the default number of slurm cpus by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task by a custom amount of ram.

  • qc_reg – If true, the motion registration step of the quality control will be performed. We do not advise to use this argument as it increases the computation time. default=False

  • niter – Define the number of iterations for eddy volume-to-volume. default=5

  • slspec_gc_path – Path to the folder containing volume specific slice-specification for eddy. If not None, eddy motion correction with gradient cycling will be performed.

  • report – If False, no quality report will be generated. default=True

randomise_all(folder_path=None, randomise_numberofpermutation=5000, skeletonised=True, metrics_dic={'FA': 'dti', '_diamond_kappa': 'diamond', '_mf_fvf_tot': 'mf', '_noddi_odi': 'noddi'}, regionWiseMean=True, slurm=None, slurm_email=None, slurm_timeout=None, cpus=None, slurm_mem=None)

Performs tract base spatial statistics (TBSS) between the data in grp1 and grp2 (groups are specified during the call to regall_FA) for each diffusion metric specified in the argument metrics_dic. The mean value of the diffusion metrics across atlases regions can also be reported in CSV files using the regionWiseMean flag. The used atlases are : the Harvard-Oxford cortical and subcortical structural atlases, the JHU DTI-based white-matter atlases and the MNI structural atlas It is mandatory to have performed regall_FA prior to randomise_all.

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • randomise_numberofpermutation – Define the number of permutations. default=5000

  • skeletonised – If True, randomize will be using only the white matter skeleton instead of the whole brain. default=True

  • metrics_dic – Dictionnary containing the diffusion metrics to register in a common space. For each diffusion metric, the metric name is the key and the metric’s folder is the value. default={‘_noddi_odi’:’noddi’,’_mf_fvf_tot’:’mf’,’_diamond_kappa’:’diamond’}

  • regionWiseMean – If true, csv containing atlas-based region wise mean will be generated.

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 20h by a custom timeout.

  • cpus – Replace the default number of slurm cpus of 1 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (8096MO by cpu) by a custom amount of ram.

regall(folder_path=None, grp1=None, grp2=None, metrics_dic={'_diamond_kappa': 'diamond', '_mf_fvf_tot': 'mf', '_noddi_odi': 'noddi'}, slurm=None, slurm_email=None, slurm_timeout=None, cpus=None, slurm_mem=None)

Register all the subjects diffusion metrics specified in the argument metrics_dic into a common space using the transformation computed for the FA with the regall_FA function. This is performed based on TBSS of FSL. It is mandatory to have performed regall_FA prior to regall.

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • grp1 – List of number corresponding to the type of the subjects to put in the first group.

  • grp2 – List of number corresponding to the type of the subjects to put in the second group.

  • metrics_dic – Dictionnary containing the diffusion metrics to register in a common space. For each diffusion metric, the metric name is the key and the metric’s folder is the value. default={‘_noddi_odi’:’noddi’,’_mf_fvf_tot’:’mf’,’_diamond_kappa’:’diamond’}

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 20h by a custom timeout.

  • cpus – Replace the default number of slurm cpus of 1 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (8096MO by cpu) by a custom amount of ram.

regall_FA(folder_path=None, grp1=None, grp2=None, starting_state=None, registration_type='-T', postreg_type='-S', prestats_treshold=0.2, slurm=None, slurm_email=None, slurm_timeout=None, cpus=None, slurm_mem=None)

Register all the subjects Fractional Anisotropy into a common space, skeletonisedd and non skeletonised. This is performed based on TBSS of FSL. It is mandatory to have performed DTI prior to regall_FA.

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • grp1 – List of number corresponding to the type of the subjects to put in the first group.

  • grp2 – List of number corresponding to the type of the subjects to put in the second group.

  • starting_state – Manually set which step of TBSS to execute first. Could either be None, reg, post_reg, prestats, design or randomise. default=None

  • registration_type – Define the argument used by the tbss command tbss_2_reg. Could either by ‘-T’, ‘-t’ or ‘-n’. If ‘-T’ is used, a FMRIB58_FA standard-space image is used. If ‘-t’ is used, a custom image is used. If ‘-n’ is used, every FA image is align to every other one, identify the “most representative” one, and use this as the target image.

  • postreg_type – Define the argument used by the tbss command tbss_3_postreg. Could either by ‘-S’ or ‘-T’. If you wish to use the FMRIB58_FA mean FA image and its derived skeleton, instead of the mean of your subjects in the study, use the ‘-T’ option. Otherwise, use the ‘-S’ option.

  • prestats_treshold – Thresholds the mean FA skeleton image at the chosen threshold during prestats. default=0.2

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 20h by a custom timeout.

  • cpus – Replace the default number of slurm cpus of 8 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (8096MO by cpu) by a custom amount of ram.

tbss(folder_path=None, grp1=None, grp2=None, starting_state=None, last_state=None, registration_type='-T', postreg_type='-S', prestats_treshold=0.2, randomise_numberofpermutation=5000, slurm=None, slurm_email=None, slurm_timeout=None, slurm_tasks=None, slurm_mem=None)

Performs tract base spatial statistics (TBSS) between the data in grp1 and grp2. The data type of each subject is specified by the subj_type.json file generated during the call to the patient_list function. The data type corresponds to the original directory of the subject (e.g. a subject that was originally in the folder data_2 is of type 2). It is mandatory to have performed DTI prior to tbss. This is function should not be used as it has been replaced by regall_FA, regall and randomise_all to allow for more flexibility.

example : study.tbss(grp1=[1,2], grp2=[3,4])

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • grp1 – List of number corresponding to the type of the subjects to put in the first group.

  • grp2 – List of number corresponding to the type of the subjects to put in the second group.

  • starting_state – Manually set which step of TBSS to execute first. Could either be None, reg, post_reg, prestats, design or randomise. default=None

  • last_state – Manually set which step of TBSS to execute last. Could either be None, preproc, reg, post_reg, prestats, design or randomise. default=None

  • registration_type – Define the argument used by the tbss command tbss_2_reg. Could either by ‘-T’, ‘-t’ or ‘-n’. If ‘-T’ is used, a FMRIB58_FA standard-space image is used. If ‘-t’ is used, a custom image is used. If ‘-n’ is used, every FA image is align to every other one, identify the “most representative” one, and use this as the target image.

  • postreg_type – Define the argument used by the tbss command tbss_3_postreg. Could either by ‘-S’ or ‘-T’. If you wish to use the FMRIB58_FA mean FA image and its derived skeleton, instead of the mean of your subjects in the study, use the ‘-T’ option. Otherwise, use the ‘-S’ option.

  • prestats_treshold – Thresholds the mean FA skeleton image at the chosen threshold during prestats. default=0.2

  • randomise_numberofpermutation – Define the number of permutations. default=5000

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 20h by a custom timeout.

  • slurm_tasks – Replace the default number of slurm cpus of 8 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (8096MO by cpu) by a custom amount of ram.

white_mask(folder_path=None, patient_list_m=None, corr_gibbs=True, forceUsePowerMap=False, debug=False, slurm=None, slurm_email=None, slurm_timeout=None, cpus=None, slurm_mem=None)

Computes a white matter mask for each subject based on the T1 structural images or on the anisotropic power maps (obtained from the diffusion images) if the T1 images are not available. The outputs are available in the directories <folder_path>/subjects/<subjects_ID>/masks/. The T1 images can be gibbs ringing corrected.

example : study.white_mask()

Parameters

  • folder_path – the path to the root directory. default=study_folder

  • patient_list_m – Define a subset of subjects to process instead of all the available subjects. example : [‘patientID1’,’patientID2’,’patientID3’]. default=None

  • corr_gibbs – If true, Gibbs ringing correction is performed on the T1 images. default=True

  • forceUsePowerMap – Force the use of an AnisotropicPower map for the white matter mask generation. default=False

  • debug – If true, additional intermediate output will be saved. default=False

  • slurm – Whether to use the Slurm Workload Manager or not (for computer clusters). default=value_during_init

  • slurm_email – Email adress to send notification if a task fails. default=None

  • slurm_timeout – Replace the default slurm timeout of 3h by a custom timeout.

  • cpus – Replace the default number of slurm cpus of 1 by a custom number of cpus of using slum, or for standard processing, its the number of core available for processing.

  • slurm_mem – Replace the default amount of ram allocated to the slurm task (8096MO by cpu) by a custom amount of ram.

elikopy.core.dicom_to_nifti(folder_path)

Convert dicom data into compressed nifti. Converted dicoms are then moved to a sub-folder named original_data. The niftis are named patientID_ProtocolName_SequenceName.

Parameters

folder_path – Path to root folder containing all the dicoms

elikopy.individual_subject_processing module

elikopy.individual_subject_processing.diamond_solo(folder_path, p, core_count=4, reportOnly=False)

Computes the DIAMOND metrics for a single subject. The outputs are available in the directories <folder_path>/subjects/<subjects_ID>/dMRI/microstructure/diamond/.

Parameters

  • folder_path – the path to the root directory.

  • p – The name of the patient.

  • core_count – Number of allocated cpu cores. default=4

elikopy.individual_subject_processing.dti_solo(folder_path, p)

Computes the DTI metrics for a single subject. The outputs are available in the directories <folder_path>/subjects/<subjects_ID>/dMRI/dti/.

Parameters

  • folder_path – the path to the root directory.

  • p – The name of the patient.

elikopy.individual_subject_processing.mf_solo(folder_path, p, dictionary_path, CSD_bvalue=None, core_count=1)

Perform microstructure fingerprinting and store the data in the <folder_path>/subjects/<subjects_ID>/dMRI/microstructure/mf/.

Parameters

  • folder_path – the path to the root directory.

  • p – The name of the patient.

  • dictionary_path – Path to the dictionary of fingerprints (mandatory).

  • CSD_bvalue – If the DIAMOND outputs are not available, the fascicles directions are estimated using a CSD with the images at the b-values specified in this argument. default=None

  • core_count – Define the number of available core. default=1

elikopy.individual_subject_processing.noddi_amico_solo(folder_path, p)

Perform noddi amico on a single subject and store the data in the <folder_path>/subjects/<subjects_ID>/dMRI/microstructure/noddi_amico/.

Parameters

  • folder_path – the path to the root directory.

  • p – The name of the patient.

elikopy.individual_subject_processing.noddi_solo(folder_path, p, force_brain_mask=False, lambda_iso_diff=3e-09, lambda_par_diff=1.7e-09, use_amico=False, core_count=1)

Computes the NODDI metrics for a single. The outputs are available in the directories <folder_path>/subjects/<subjects_ID>/dMRI/microstructure/noddi/.

Parameters

  • folder_path – the path to the root directory.

  • p – The name of the patient.

  • force_brain_mask – Force the use of a brain mask even if a whitematter mask exist. default=False

  • lambda_iso_diff – Define the noddi lambda_iso_diff parameters. default=3.e-9

  • lambda_par_diff – Define the noddi lambda_par_diff parameters. default=1.7e-9

  • use_amico – If true, use the amico optimizer. default=FALSE

  • core_count – Number of allocated cpu cores. default=1

elikopy.individual_subject_processing.preproc_solo(folder_path, p, reslice=False, reslice_addSlice=False, denoising=False, gibbs=False, topup=False, topupConfig=None, forceSynb0DisCo=False, useGPUsynb0DisCo=False, eddy=False, biasfield=False, biasfield_bsplineFitting=[100, 3], biasfield_convergence=[1000, 0.001], starting_state=None, bet_median_radius=2, bet_numpass=1, bet_dilate=2, cuda=False, cuda_name='eddy_cuda10.1', s2v=[0, 5, 1, 'trilinear'], olrep=[False, 4, 250, 'sw'], qc_reg=True, core_count=1, niter=5, report=True, slspec_gc_path=None)

Performs data preprocessing on a single subject. By default only the brain extraction is enabled. Optional preprocessing steps include : reslicing, denoising, gibbs ringing correction, susceptibility field estimation, EC-induced distortions and motion correction, bias field correction. The results are stored in the preprocessing subfolder of the study subject <folder_path>/subjects/<subjects_ID>/dMRI/preproc.

Parameters

  • folder_path – the path to the root directory.

  • p – The name of the patient.

  • reslice – If true, data will be resliced with a new voxel resolution of 2*2*2. default=False

  • reslice_addSlice – If true, an additional empty slice will be added to each volume (might be useful for motion correction if one slice is dropped during the acquisition and the user still wants to perform easily the slice-to-volume motion correction). default=False

  • denoising – If true, MPPCA-denoising is performed on the data. default=False

  • gibbs – If true, Gibbs ringing correction is performed. We do not advise to use this correction unless the data suffers from a lot of Gibbs ringing artifacts. default=False

  • topup – If true, Topup will estimate the susceptibility induced distortions. These distortions are corrected at the same time as EC-induced distortions if eddy=True. In the absence of images acquired with a reverse phase encoding direction, a T1 structural image is required. default=False

  • topupConfig – If not None, Topup will use additionnal parameters based on the supplied config file located at <topupConfig>. default=None

  • forceSynb0DisCo – If true, Topup will always estimate the susceptibility field using the T1 structural image. default=False

  • useGPUsynb0DisCo – If true, Topup will estimate the susceptibility field with the T1 structural image using cuda. default=FALSE

  • eddy – If true, Eddy corrects the EC-induced (+ susceptibility, if estimated) distortions and the motion. If these corrections are performed the acquparam and index files are required (see documentation). To perform the slice-to-volume motion correction the slspec file is also needed. default=False

  • biasfield – If true, low frequency intensity non-uniformity present in MRI image data known as a bias or gain field will be corrected. default=False

  • biasfield_bsplineFitting – Define the initial mesh resolution in mm and the bspline order of the biasfield correction tool. default=[100,3]

  • biasfield_convergence – Define the maximum number of iteration and the convergences threshold of the biasfield correction tool. default=[1000,0.001]

  • starting_state – Manually set which step of the preprocessing to execute first. Could either be None, denoising, gibbs, topup, eddy, biasfield, report or post_report. default=None

  • bet_median_radius – Radius (in voxels) of the applied median filter during brain extraction. default=2

  • bet_numpass – Number of pass of the median filter during brain extraction. default=1

  • bet_dilate – Number of iterations for binary dilation during brain extraction. default=2

  • cuda – If true, eddy will run on cuda with the command name specified in cuda_name. default=False

  • cuda_name – name of the eddy command to run when cuda==True. default=”eddy_cuda10.1”

  • s2v – list of parameters of Eddy for slice-to-volume motion correction (see Eddy FSL documentation): [mporder,s2v_niter,s2v_lambda,s2v_interp]. The slice-to-volume motion correction is performed if mporder>0, cuda is used and a slspec file is provided during the patient_list command. default=[0,5,1,’trilinear’]

  • olrep – list of parameters of Eddy for outlier replacement (see Eddy FSL documentation): [repol,ol_nstd,ol_nvox,ol_type]. The outlier replacement is performed if repol==True. default=[False, 4, 250, ‘sw’]

  • qc_reg – If true, the motion registration step of the quality control will be performed. We do not advise to use this argument as it increases the computation time. default=False

  • niter – Define the number of iterations for eddy volume-to-volume. default=5

  • slspec_gc_path – Path to the folder containing volume specific slice-specification for eddy. If not None, eddy motion correction with gradient cycling will be performed.

  • report – If False, no quality report will be generated. default=True

  • core_count – Number of allocated cpu cores. default=1

elikopy.individual_subject_processing.report_solo(folder_path, patient_path, slices=None, short=False)

Legacy report function.

Parameters

  • folder_path – path to the root directory.

  • patient_path – Name of the subject.

  • slices – Add additional slices cut to specific volumes

  • short – Only output raw data, preprocessed data and FA data.

elikopy.individual_subject_processing.white_mask_solo(folder_path, p, corr_gibbs=True, core_count=1, forceUsePowerMap=False, debug=False)

Computes a white matter mask for a single subject based on the T1 structural image or on the anisotropic power map (obtained from the diffusion images) if the T1 image is not available. The outputs are available in the directories <folder_path>/subjects/<subjects_ID>/masks/. The T1 images can be gibbs ringing corrected.

Parameters

  • folder_path – the path to the root directory.

  • p – The name of the patient.

  • corr_gibbs – If true, Gibbs ringing correction is performed on the T1 image. default=True

  • core_count – Number of allocated cpu cores. default=1

  • forceUsePowerMap – Force the use of an AnisotropicPower map for the white matter mask generation. default=False

  • debug – If true, additional intermediate output will be saved. default=False

elikopy.utils module

elikopy.utils.anonymise_nifti(rootdir, anonymize_json, rename)

Anonymise all nifti present in rootdir by removing the PatientName and PatientBirthDate (only month and day) in the json and renaming the nifti file name to the PatientID.

Parameters

  • rootdir – Folder containing all the nifti to anonimyse.

  • anonymize_json – If true, edit the json to remove the PatientName and replace the PatientBirthDate by the year of birth.

  • rename – If true, rename the nifti to the PatientID.

elikopy.utils.export_files(folder_path, step, patient_list_m=None)

Creates an export folder in the root folder containing the results of ‘step’ for each patient in a single folder

example : export_files(‘user/my_rootfolder’, ‘dMRI/microstructure/dti’)

Parameters

  • folder_path – root folder

  • step – step to export

  • patient_list_m – Define a subset a patient to process instead of all the available subjects.

elikopy.utils.getJobsState(folder_path, job_list, step_name)

Periodically checks the status of all jobs in the job_list. When a job status change to complete or a failing state. Write the status in the log and remove the job from the job_list. This function end when all jobs are completed or failed.

Parameters

  • folder_path – The path to the root dir of the study (used to write the logs.txt file)

  • job_list – The list of job to check for state update

  • step_name – The string value of the prefix to put in the log file

elikopy.utils.get_job_state(job_id)

Retrieve the state of a job through the sacct bash command offered by the lurm Workload Manager. :param job_id: The id of the job to retrieve the state of. :return state: The string value representing the state of the job.

elikopy.utils.get_patient_list_by_types(folder_path, type=None)

Print the list of patient corresponding to a specfic type of patient.

Parameters

  • folder_path – Path to the root folder of the study.

  • type – The selected type

elikopy.utils.inference(T1_path, b0_d_path, model, device)

synb0DISCO adapted from https://github.com/MASILab/Synb0-DISCO

Parameters

  • T1_path – Path to the normalized projected T1.

  • b0_d_path – Path to the b0 atlases.

  • model – DL Model

  • device – Define if cuda or cpu is used.

elikopy.utils.makedir(dir_path, log_path, log_prefix)

Create a directory in the location specified by the dir_path and write the log in the log_path.

Parameters

  • dir_path – The path to the directory to create.

  • log_path – The path to the log file to write verbose data.

  • log_prefix – The prefix to use in the log file.

elikopy.utils.merge_all_reports(folder_path)

Merge all subjects quality control reports into a single report.

Parameters

folder_path – Path to the root folder of the study.

elikopy.utils.merge_all_specific_reports(folder_path, merge_wm_report=False, merge_legacy_report=False)

Merge all selected specific subject’s report into a single big report.

Parameters

  • folder_path – Path to the root folder of the study.

  • merge_wm_report – Select wm report.

  • merge_legacy_report – Select legacy report.

elikopy.utils.randomise_all(folder_path, randomise_numberofpermutation=5000, skeletonised=True, metrics_dic={'FA': 'dti', '_diamond_kappa': 'diamond', '_mf_fvf_tot': 'mf', '_noddi_odi': 'noddi'}, core_count=1, regionWiseMean=True)

Performs tract base spatial statistics (TBSS) between the data in grp1 and grp2 (groups are specified during the call to regall_FA) for each diffusion metric specified in the argument metrics_dic. The mean value of the diffusion metrics across atlases regions can also be reported in CSV files using the regionWiseMean flag. The used atlases are : the Harvard-Oxford cortical and subcortical structural atlases, the JHU DTI-based white-matter atlases and the MNI structural atlas It is mandatory to have performed regall_FA prior to randomise_all.

Parameters

  • folder_path – path to the root directory.

  • randomise_numberofpermutation – Define the number of permutations. default=5000

  • skeletonised – If True, randomize will be using only the white matter skeleton instead of the whole brain. default=True

  • metrics_dic – Dictionnary containing the diffusion metrics to register in a common space. For each diffusion metric, the metric name is the key and the metric’s folder is the value. default={‘_noddi_odi’:’noddi’,’_mf_fvf_tot’:’mf’,’_diamond_kappa’:’diamond’}

  • regionWiseMean – If true, csv containing atlas-based region wise mean will be generated.

  • core_count – Number of allocated cpu core. default=1

elikopy.utils.regall(folder_path, grp1, grp2, core_count=1, metrics_dic={'_diamond_kappa': 'diamond', '_mf_fvf_tot': 'mf', '_noddi_odi': 'noddi'})

Register all the subjects diffusion metrics specified in the argument metrics_dic into a common space using the transformation computed for the FA with the regall_FA function. This is performed based on TBSS of FSL. It is mandatory to have performed regall_FA prior to regall.

Parameters

  • folder_path – path to the root directory.

  • grp1 – List of number corresponding to the type of the subjects to put in the first group.

  • grp2 – List of number corresponding to the type of the subjects to put in the second group.

  • metrics_dic – Dictionnary containing the diffusion metrics to register in a common space. For each diffusion metric, the metric name is the key and the metric’s folder is the value. default={‘_noddi_odi’:’noddi’,’_mf_fvf_tot’:’mf’,’_diamond_kappa’:’diamond’}

  • core_count – Define the number of available core. default=1

elikopy.utils.regall_FA(folder_path, grp1, grp2, starting_state=None, registration_type='-T', postreg_type='-S', prestats_treshold=0.2, core_count=1)

Register all the subjects Fractional Anisotropy into a common space, skeletonisedd and non skeletonised. This is performed based on TBSS of FSL. It is mandatory to have performed DTI prior to regall_FA.

Parameters

  • folder_path – path to the root directory.

  • grp1 – List of number corresponding to the type of the subjects to put in the first group.

  • grp2 – List of number corresponding to the type of the subjects to put in the second group.

  • starting_state – Manually set which step of TBSS to execute first. Could either be None, reg, post_reg, prestats, design or randomise. default=None

  • registration_type – Define the argument used by the tbss command tbss_2_reg. Could either by ‘-T’, ‘-t’ or ‘-n’. If ‘-T’ is used, a FMRIB58_FA standard-space image is used. If ‘-t’ is used, a custom image is used. If ‘-n’ is used, every FA image is align to every other one, identify the “most representative” one, and use this as the target image.

  • postreg_type – Define the argument used by the tbss command tbss_3_postreg. Could either by ‘-S’ or ‘-T’. If you wish to use the FMRIB58_FA mean FA image and its derived skeleton, instead of the mean of your subjects in the study, use the ‘-T’ option. Otherwise, use the ‘-S’ option.

  • prestats_treshold – Thresholds the mean FA skeleton image at the chosen threshold during prestats. default=0.2

  • core_count – Define the number of available core. default=1

elikopy.utils.submit_job(job_info)

Submit a job to the Slurm Workload Manager using a crafted sbatch.

Parameters

job_info – The parameters to use in the sbatch.

Return job_id

The id of the submited job.

elikopy.utils.synb0DisCo(folder_path, topuppath, patient_path, starting_step=None, topup=True, gpu=True)

synb0DISCO adapted from https://github.com/MASILab/Synb0-DISCO

Parameters

  • folder_path – path to the root directory.

  • topuppath – Path to the subject’s topup folder.

  • patient_path – Name of the subject.

  • starting_step – Define the starting step, usefull if previous step had already been run.

  • topup – If true, topup will be perfomed after synb0Disco.

  • gpu – If true, torch will use the gpu.

Return type

object

elikopy.utils.tbss_utils(folder_path, grp1, grp2, starting_state=None, last_state=None, registration_type='-T', postreg_type='-S', prestats_treshold=0.2, randomise_numberofpermutation=5000)

[Legacy] Performs tract base spatial statistics (TBSS) between the data in grp1 and grp2. The data type of each subject is specified by the subj_type.json file generated during the call to the patient_list function. The data type corresponds to the original directory of the subject (e.g. a subject that was originally in the folder data_2 is of type 2). It is mandatory to have performed DTI prior to tbss.

Parameters

  • folder_path – path to the root directory.

  • grp1 – List of number corresponding to the type of the subjects to put in the first group.

  • grp2 – List of number corresponding to the type of the subjects to put in the second group.

  • starting_state – Manually set which step of TBSS to execute first. Could either be None, reg, post_reg, prestats, design or randomise. default=None

  • last_state – Manually set which step of TBSS to execute last. Could either be None, preproc, reg, post_reg, prestats, design or randomise. default=None

  • registration_type – Define the argument used by the tbss command tbss_2_reg. Could either by ‘-T’, ‘-t’ or ‘-n’. If ‘-T’ is used, a FMRIB58_FA standard-space image is used. If ‘-t’ is used, a custom image is used. If ‘-n’ is used, every FA image is align to every other one, identify the “most representative” one, and use this as the target image.

  • postreg_type – Define the argument used by the tbss command tbss_3_postreg. Could either by ‘-S’ or ‘-T’. If you wish to use the FMRIB58_FA mean FA image and its derived skeleton, instead of the mean of your subjects in the study, use the ‘-T’ option. Otherwise, use the ‘-S’ option.

  • prestats_treshold – Thresholds the mean FA skeleton image at the chosen threshold during prestats. default=0.2

  • randomise_numberofpermutation – Define the number of permutations. default=5000

Module contents