From 656e3b0be9a6c2c9ae6ff267cc3d4b59caaaad15 Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Wed, 1 Feb 2023 15:13:17 -0800 Subject: [PATCH] Small documentation fixes, to improve auto-rendering of API docs. --- AFQ/api/bundle_dict.py | 153 +++++++++++++++++++++-------------------- AFQ/models/dti.py | 21 ++++-- 2 files changed, 92 insertions(+), 82 deletions(-) diff --git a/AFQ/api/bundle_dict.py b/AFQ/api/bundle_dict.py index 801e3d245..0b0be0ba7 100644 --- a/AFQ/api/bundle_dict.py +++ b/AFQ/api/bundle_dict.py @@ -62,88 +62,89 @@ def append_l_r(bundle_list, no_lr_list): class BundleDict(MutableMapping): + """ + Create a bundle dictionary, needed for the segmentation. + + Parameters + ---------- + bundle_info : list or dict, optional + A list of the bundles to be used, or a dictionary defining + custom bundles. See `Defining Custom Bundle Dictionaries` + in the `usage` section of pyAFQ's documentation for details. + Default: AFQ.api.bundle_dict.BUNDLES + + seg_algo: One of {"afq", "reco", "reco16", "reco80"} + The bundle segmentation algorithm to use. + "afq" : Use waypoint ROIs + probability maps, as described + in [Yeatman2012]_ + "reco" / "reco16" : Use Recobundles [Garyfallidis2017]_ + with a 16-bundle set. + "reco80": Use Recobundles with an 80-bundle set. + + resample_to : Nifti1Image or bool, optional + If there are bundles in bundle_info with the 'space' attribute + set to 'template', or with no 'space' attribute, + their images (all ROIs and probability maps) + will be resampled to the affine and shape of this image. + If None, the MNI template will be used. + If False, no resampling will be done. + Default: None + + resample_subject_to : Nifti1Image or bool, optional + If there are bundles in bundle_info with the 'space' attribute + set to 'subject', their images (all ROIs and probability maps) + will be resampled to the affine and shape of this image. + If False, no resampling will be done. + Default: None + + keep_in_memory : bool, optional + Whether, once loaded, all ROIs and probability maps will stay + loaded in memory within this object. By default, ROIs are loaded + into memory on demand and no references to ROIs are kept, other + than their paths. The default 18 bundles use ~6GB when all loaded. + Default: False + + Examples + -------- + # import OR ROIs and create a custom bundle dict + # from them + import AFQ.data.fetch as afd + or_rois = afd.read_or_templates() + + bundles = BundleDict({ + "L_OR": { + "include": [ + or_rois["left_OR_1"], # these can be paths to Nifti files + or_rois["left_OR_2"]], # or they can Nifti images + "exclude": [ + or_rois["left_OP_MNI"], + or_rois["left_TP_MNI"], + or_rois["left_pos_thal_MNI"]], + "start": or_rois['left_thal_MNI'], + "end": or_rois['left_V1_MNI'], + "cross_midline": False, + }, + "R_OR": { + "include": [ + or_rois["right_OR_1"], + or_rois["right_OR_2"]], + "exclude": [ + or_rois["right_OP_MNI"], + or_rois["right_TP_MNI"], + or_rois["right_pos_thal_MNI"]], + "start": or_rois['right_thal_MNI'], + "end": or_rois['right_V1_MNI'], + "cross_midline": False + } + }) + """ + def __init__(self, bundle_info=BUNDLES, seg_algo="afq", resample_to=None, resample_subject_to=False, keep_in_memory=False): - """ - Create a bundle dictionary, needed for the segmentation - - Parameters - ---------- - bundle_info : list or dict, optional - A list of the bundles to be used, or a dictionary defining - custom bundles. See `Defining Custom Bundle Dictionaries` - in the `usage` section of pyAFQ's documentation for details. - Default: AFQ.api.bundle_dict.BUNDLES - - seg_algo: One of {"afq", "reco", "reco16", "reco80"} - The bundle segmentation algorithm to use. - "afq" : Use waypoint ROIs + probability maps, as described - in [Yeatman2012]_ - "reco" / "reco16" : Use Recobundles [Garyfallidis2017]_ - with a 16-bundle set. - "reco80": Use Recobundles with an 80-bundle set. - - resample_to : Nifti1Image or bool, optional - If there are bundles in bundle_info with the 'space' attribute - set to 'template', or with no 'space' attribute, - their images (all ROIs and probability maps) - will be resampled to the affine and shape of this image. - If None, the MNI template will be used. - If False, no resampling will be done. - Default: None - - resample_subject_to : Nifti1Image or bool, optional - If there are bundles in bundle_info with the 'space' attribute - set to 'subject', their images (all ROIs and probability maps) - will be resampled to the affine and shape of this image. - If False, no resampling will be done. - Default: None - - keep_in_memory : bool, optional - Whether, once loaded, all ROIs and probability maps will stay - loaded in memory within this object. By default, ROIs are loaded - into memory on demand and no references to ROIs are kept, other - than their paths. The default 18 bundles use ~6GB when all loaded. - Default: False - - Examples - -------- - # import OR ROIs and create a custom bundle dict - # from them - import AFQ.data.fetch as afd - or_rois = afd.read_or_templates() - - bundles = BundleDict({ - "L_OR": { - "include": [ - or_rois["left_OR_1"], # these can be paths to Nifti files - or_rois["left_OR_2"]], # or they can Nifti images - "exclude": [ - or_rois["left_OP_MNI"], - or_rois["left_TP_MNI"], - or_rois["left_pos_thal_MNI"]], - "start": or_rois['left_thal_MNI'], - "end": or_rois['left_V1_MNI'], - "cross_midline": False, - }, - "R_OR": { - "include": [ - or_rois["right_OR_1"], - or_rois["right_OR_2"]], - "exclude": [ - or_rois["right_OP_MNI"], - or_rois["right_TP_MNI"], - or_rois["right_pos_thal_MNI"]], - "start": or_rois['right_thal_MNI'], - "end": or_rois['right_V1_MNI'], - "cross_midline": False - } - }) - """ if not (isinstance(bundle_info, dict) or isinstance(bundle_info, list)): raise TypeError(( diff --git a/AFQ/models/dti.py b/AFQ/models/dti.py index 844901d77..a9ad5a583 100644 --- a/AFQ/models/dti.py +++ b/AFQ/models/dti.py @@ -85,7 +85,7 @@ def _fit(gtab, data, mask=None, sigma=None): def fit_dti(data_files, bval_files, bvec_files, mask=None, out_dir=None, file_prefix=None, b0_threshold=50): """ - Fit the DTI model using default settings, save files with derived maps + Fit the DTI model using default settings, save files with derived maps. Parameters ---------- @@ -107,11 +107,12 @@ def fit_dti(data_files, bval_files, bvec_files, mask=None, Returns ------- - file_paths : a dict with the derived maps that were computed and full-paths - to the files containing these maps. + file_paths : dict + A dict with the derived maps that were computed and full-paths + to the files containing these maps. - Note - ---- + Notes + ----- Maps that are calculated: FA, MD, AD, RD """ img, data, gtab, mask = ut.prepare_data(data_files, bval_files, @@ -147,8 +148,10 @@ def fit_dti(data_files, bval_files, bvec_files, mask=None, def predict(params_file, gtab, S0_file=None, out_dir=None): """ - Create a signal prediction from DTI params + Create a signal prediction from DTI params. + Parameters + ---------- params_file : str Full path to a file with parameters saved from a DKI fit @@ -159,6 +162,12 @@ def predict(params_file, gtab, S0_file=None, out_dir=None): Full path to a nifti file that contains S0 measurements to incorporate into the prediction. If the file contains 4D data, the volumes that contain the S0 data must be the same as the gtab.b0s_mask. + + Returns + ------- + fname : str + The name of the nifti file with saved predictions. + """ if out_dir is None: out_dir = op.join(op.split(params_file)[0])