diff --git a/docs/conf.py b/docs/conf.py index 60dd2eb..5922cef 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,6 +47,7 @@ # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', 'sphinx_rtd_theme', ] diff --git a/docs/img_png/pyrelimri_logo.psd b/docs/img_png/pyrelimri_logo.psd index d37a1c2..9e9f249 100644 Binary files a/docs/img_png/pyrelimri_logo.psd and b/docs/img_png/pyrelimri_logo.psd differ diff --git a/pyrelimri/brain_icc.py b/pyrelimri/brain_icc.py index e431ba7..46fb485 100644 --- a/pyrelimri/brain_icc.py +++ b/pyrelimri/brain_icc.py @@ -21,43 +21,35 @@ def voxelwise_icc(multisession_list: list, mask: str, icc_type: str = 'icc_3') -> dict: """ - voxelwise_icc: Calculate the Intraclass Correlation Coefficient (ICC) along with lower and upper bound confidence intervals + Calculate the Intraclass Correlation Coefficient (ICC) along with lower and upper bound confidence intervals by voxel for specified input files using manual sum of squares calculations. - Parameters - ---------- - multisession_list : list of list of str - List of lists containing paths to subject 3D volumes for each session. - - Example: - dat_ses1 = ["./ses1/sub-00_Contrast-A_bold.nii.gz", "./ses1/sub-01_Contrast-A_bold.nii.gz", "./ses1/sub-03_Contrast-A_bold.nii.gz"] - dat_ses2 = ["./ses2/sub-00_Contrast-A_bold.nii.gz", "./ses2/sub-01_Contrast-A_bold.nii.gz", "./ses2/sub-03_Contrast-A_bold.nii.gz"] - dat_ses3 = ["./ses3/sub-00_Contrast-A_bold.nii.gz", "./ses3/sub-01_Contrast-A_bold.nii.gz", "./ses3/sub-03_Contrast-A_bold.nii.gz"] - The order of the subjects in each list has to be the same. - - mask : str - Path to 3D mask in NIfTI format. - - icc_type : str, optional - Type of ICC to compute, default is 'icc_3'. - Options: 'icc_1', 'icc_2', 'icc_3'. - - Returns - ------- - dict - Dictionary containing the following 3D images: - 'est' : nibabel.Nifti1Image - Estimated ICC values. - 'lowbound' : nibabel.Nifti1Image - Lower bound of ICC confidence intervals. - 'upbound' : nibabel.Nifti1Image - Upper bound of ICC confidence intervals. - 'btwn_sub' : nibabel.Nifti1Image - Between-subject variance. - 'wthn_sub' : nibabel.Nifti1Image - Within-subject variance. - 'btwn_meas' : nibabel.Nifti1Image - Between-measurement variance. + Args: + multisession_list (list of list of str): + List of lists containing paths to subject 3D volumes for each session. + + Example: + dat_ses1 = ["./ses1/sub-00_Contrast-A_bold.nii.gz", "./ses1/sub-01_Contrast-A_bold.nii.gz", "./ses1/sub-03_Contrast-A_bold.nii.gz"] + dat_ses2 = ["./ses2/sub-00_Contrast-A_bold.nii.gz", "./ses2/sub-01_Contrast-A_bold.nii.gz", "./ses2/sub-03_Contrast-A_bold.nii.gz"] + dat_ses3 = ["./ses3/sub-00_Contrast-A_bold.nii.gz", "./ses3/sub-01_Contrast-A_bold.nii.gz", "./ses3/sub-03_Contrast-A_bold.nii.gz"] + The order of the subjects in each list has to be the same. + + mask (str): + Path to 3D mask in NIfTI format. + + icc_type (str, optional): + Type of ICC to compute, default is 'icc_3'. + Options: 'icc_1', 'icc_2', 'icc_3'. + + Returns: + dict: + Dictionary containing the following 3D images: + 'est' (nibabel.Nifti1Image): Estimated ICC values. + 'lowbound' (nibabel.Nifti1Image): Lower bound of ICC confidence intervals. + 'upbound' (nibabel.Nifti1Image): Upper bound of ICC confidence intervals. + 'btwn_sub' (nibabel.Nifti1Image): Between-subject variance. + 'wthn_sub' (nibabel.Nifti1Image): Within-subject variance. + 'btwn_meas' (nibabel.Nifti1Image): Between-measurement variance. """ session_lengths = [len(session) for session in multisession_list] session_all_same = all(length == session_lengths[0] for length in session_lengths) @@ -123,24 +115,20 @@ def setup_atlas(name_atlas: str, **kwargs) -> nib.Nifti1Image: Setup & fetch a brain atlas based on the provided atlas name & optional parameters via kwargs associated with documentation from Nilearn. - Parameters - ---------- - name_atlas : str - Name of the atlas to fetch. Available options are: - 'aal', 'destrieux_2009', 'difumo', 'harvard_oxford', 'juelich', - 'msdl', 'pauli_2017', 'schaefer_2018', 'talairach'. - - **kwargs : keyword arguments, optional - Additional parameters to customize the fetching process. Examples: - - 'data_dir': str, default='/tmp/' - Directory where the fetched atlas data will be stored. - - 'verbose': int, default=0 - Verbosity level of process. - - Returns - ------- - fetched_atlas : Nifti1Image - Fetched brain atlas in NIfTI format. + Args: + name_atlas (str): + Name of the atlas to fetch. Available options are: + 'aal', 'destrieux_2009', 'difumo', 'harvard_oxford', 'juelich', + 'msdl', 'pauli_2017', 'schaefer_2018', 'talairach'. + + **kwargs: + Additional parameters to customize the fetching process. Examples: + - 'data_dir' (str): Directory where the fetched atlas data will be stored. Default is '/tmp/'. + - 'verbose' (int): Verbosity level of the process. Default is 0. + + Returns: + nib.Nifti1Image: + Fetched brain atlas in NIfTI format. """ default_params = { 'data_dir': '/tmp/', @@ -177,23 +165,20 @@ def prob_atlas_scale(nifti_map, estimate_array): """ Rescales a probabilistic 3D Nifti map to match the range of estimated values. - Parameters - ---------- - nifti_map : Nifti1Image - Input 3D Nifti image to be rescaled. + Args: + nifti_map (Nifti1Image): + Input 3D Nifti image to be rescaled. - estimate_array : ndarray - 1D NumPy array containing the estimates used for scaling. + estimate_array (ndarray): + 1D NumPy array containing the estimates used for scaling. - Returns - ------- - Nifti1Image - Rescaled 3D image where non-zero values are scaled to match the range of `estimate_array`. + Returns: + Nifti1Image: + Rescaled 3D image where non-zero values are scaled to match the range of `estimate_array`. - Notes - ----- - This function rescales the non-zero values in the input Nifti image `nifti_map` using the minimum and maximum - values of `estimate_array`. The spatial/header info from `nifti_map` is preserved. + Notes: + This function rescales the non-zero values in the input Nifti image `nifti_map` using the minimum and maximum + values of `estimate_array`. The spatial/header info from `nifti_map` is preserved. """ temp_img_array = nifti_map.get_fdata().flatten() non_zero_mask = temp_img_array != 0 @@ -211,26 +196,25 @@ def prob_atlas_scale(nifti_map, estimate_array): return image.new_img_like(nifti_map, new_img_shape) -def roi_icc(multisession_list: str, type_atlas: str, - atlas_dir: str, icc_type='icc_3', **kwargs): +def roi_icc(multisession_list: list, type_atlas: str, atlas_dir: str, icc_type='icc_3', **kwargs): """ - roi_icc: Calculate the Intraclass Correlation Coefficient (ICC) for each ROI in a specified atlas - (+lower bound & upper bound CI) for input files using manual sum of squares calculations. It also provides - associated between subject variance, within subject variance and between measure variance estimates. - + Calculate the Intraclass Correlation Coefficient (ICC) for each ROI in a specified atlas + (+lower bound & upper bound CI) for input files using manual sum of squares calculations. + It also provides associated between subject variance, within subject variance and between + measure variance estimates. The function expects the subject's data paths to be provided as a list of lists for sessions: - Example: - dat_ses1 = ["./ses1/sub-00_Contrast-A_bold.nii.gz", "./ses1/sub-01_Contrast-A_bold.nii.gz", "./ses1/sub-03_Contrast-A_bold.nii.gz"] - dat_ses2 = ["./ses2/sub-00_Contrast-A_bold.nii.gz", "./ses2/sub-01_Contrast-A_bold.nii.gz", "./ses2/sub-03_Contrast-A_bold.nii.gz"] - dat_ses3 = ["./ses3/sub-00_Contrast-A_bold.nii.gz", "./ses3/sub-01_Contrast-A_bold.nii.gz", "./ses3/sub-03_Contrast-A_bold.nii.gz"] - ** The order of the subjects in each list has to be the same ** + Example: + dat_ses1 = ["./ses1/sub-00_Contrast-A_bold.nii.gz", "./ses1/sub-01_Contrast-A_bold.nii.gz", "./ses1/sub-03_Contrast-A_bold.nii.gz"] + dat_ses2 = ["./ses2/sub-00_Contrast-A_bold.nii.gz", "./ses2/sub-01_Contrast-A_bold.nii.gz", "./ses2/sub-03_Contrast-A_bold.nii.gz"] + dat_ses3 = ["./ses3/sub-00_Contrast-A_bold.nii.gz", "./ses3/sub-01_Contrast-A_bold.nii.gz", "./ses3/sub-03_Contrast-A_bold.nii.gz"] + ** The order of the subjects in each list has to be the same ** Examples: - # Two-session example: - multisession_list = [dat_ses1, dat_ses2] - # Three-session example: - multisession_list = [dat_ses1, dat_ses2, dat_ses3] + # Two-session example: + multisession_list = [dat_ses1, dat_ses2] + # Three-session example: + multisession_list = [dat_ses1, dat_ses2, dat_ses3] Inter-subject variance corresponds to variance between subjects across all sessions (1, 2, 3). Intra-subject variance corresponds to variance within subjects across all sessions (1, 2, 3). @@ -238,65 +222,35 @@ def roi_icc(multisession_list: str, type_atlas: str, The atlas name should be one of the probabilistic and ROI parcellations listed: https://nilearn.github.io/dev/modules/datasets.html#atlases - Parameters - ---------- - multisession_list : list of list of str - List of lists containing paths to subject 3D volumes for each session. - - type_atlas : str - Name of the atlas type provided within Nilearn atlases. - - atlas_dir : str - Location to download/store downloaded atlas. Recommended: '/tmp/'. - - icc_type : str, optional - Type of ICC to compute, default is 'icc_3'. - Options: 'icc_1', 'icc_2', 'icc_3'. - - **kwargs : keyword arguments, optional - Additional parameters to customize the atlas fetching process and masker settings. - Default options: - - 'data_dir': str, default='/tmp/' - Directory where the fetched atlas data will be stored. - - 'verbose': int, default=0 - Verbosity level of the fetching process. - - Returns - ------- - dict - Dictionary containing the following arrays and values: - 'roi_labels' : list - Labels of the ROIs in the atlas. - 'est' : ndarray - Estimated ICC values for each ROI. - 'lowbound' : ndarray - Lower bound of ICC confidence intervals for each ROI. - 'upbound' : ndarray - Upper bound of ICC confidence intervals for each ROI. - 'btwnsub' : ndarray - Between-subject variance for each ROI. - 'wthnsub' : ndarray - Within-subject variance for each ROI. - 'btwnmeas' : ndarray - Between-measurement variance for each ROI. - 'est_3d' : nibabel.Nifti1Image - Estimated ICC values for each ROI. - 'lowbound_3d' : nibabel.Nifti1Image - Lower bound of ICC confidence intervals for each ROI. - 'upbound_3d' : nibabel.Nifti1Image - Upper bound of ICC confidence intervals for each ROI. - 'btwnsub_3d' : nibabel.Nifti1Image - Between-subject variance for each ROI. - 'wthnsub_3d' : nibabel.Nifti1Image - Within-subject variance for each ROI. - 'btwnmeas_3d' : nibabel.Nifti1Image - Between-measurement variance for each ROI. - - Example - ------- - # Calculate ICC for ROIs using multisession data and AAL atlas - result = roi_icc(multisession_list=multisession_list, type_atlas='aal', - atlas_dir='/tmp/', icc_type='icc_2') + Args: + multisession_list (list of list of str): List of lists containing paths to subject 3D volumes for each session. + type_atlas (str): Name of the atlas type provided within Nilearn atlases. + atlas_dir (str): Location to download/store downloaded atlas. Recommended: '/tmp/'. + icc_type (str, optional): Type of ICC to compute, default is 'icc_3'. Options: 'icc_1', 'icc_2', 'icc_3'. + **kwargs (optional): Additional parameters to customize the atlas fetching process and masker + settings. + - data_dir (str): Directory where the fetched atlas data will be stored. Default is '/tmp/'. + - verbose (int): Verbosity level of the fetching process. Default is 0. + + Returns: + dict: Dictionary containing the following arrays and values: + - roi_labels (list): Labels of the ROIs in the atlas. + - est (ndarray): Estimated ICC values for each ROI. + - lowbound (ndarray): Lower bound of ICC confidence intervals for each ROI. + - upbound (ndarray): Upper bound of ICC confidence intervals for each ROI. + - btwnsub (ndarray): Between-subject variance for each ROI. + - wthnsub (ndarray): Within-subject variance for each ROI. + - btwnmeas (ndarray): Between-measurement variance for each ROI. + - est_3d (nibabel.Nifti1Image): Estimated ICC values for each ROI. + - lowbound_3d (nibabel.Nifti1Image): Lower bound of ICC confidence intervals for each ROI. + - upbound_3d (nibabel.Nifti1Image): Upper bound of ICC confidence intervals for each ROI. + - btwnsub_3d (nibabel.Nifti1Image): Between-subject variance for each ROI. + - wthnsub_3d (nibabel.Nifti1Image): Within-subject variance for each ROI. + - btwnmeas_3d (nibabel.Nifti1Image): Between-measurement variance for each ROI. + + Example: + # Calculate ICC for ROIs using multisession data and AAL atlas + result = roi_icc(multisession_list=multisession_list, type_atlas='aal', atlas_dir='/tmp/', icc_type='icc_2') """ # combine brain data session_lengths = [len(session) for session in multisession_list] diff --git a/pyrelimri/masked_timeseries.py b/pyrelimri/masked_timeseries.py index 1ba06de..0075415 100644 --- a/pyrelimri/masked_timeseries.py +++ b/pyrelimri/masked_timeseries.py @@ -254,68 +254,64 @@ def extract_time_series(bold_paths: list, roi_type: str, high_pass_sec: int = No """ Extracts time series data from BOLD images for specified regions of interest (ROI) or coordinates. For each BOLD path, extracts time series either using a mask or ROI coordinates, leveraging - Nilearn's NiftiLabelsMasker (for mask) or NiftiSpheresMasker (for coordinates). + Nilearn's NiftiLabelsMasker (for mask) or nifti_spheres_masker (for coordinates). Parameters ---------- - bold_paths : list - List of paths to BOLD image files for subjects/runs/tasks. The order should match the order of events or - conditions for each subject. + bold_paths : list + List of paths to BOLD image files for subjects/runs/tasks. The order should match the order of events or + conditions for each subject. - roi_type : str - Type of ROI ('mask' or 'coords'). + roi_type : str + Type of ROI ('mask' or 'coords'). - high_pass_sec : int, optional - High-pass filter cutoff in seconds. If provided, converted to frequency (1/high_pass_sec). Default is None. + high_pass_sec : int, optional + High-pass filter cutoff in seconds. If provided, converted to frequency (1/high_pass_sec). Default is None. - roi_mask : str or None, optional - Path to the ROI mask image. Required if roi_type is 'mask'. Default is None. + roi_mask : str or None, optional + Path to the ROI mask image. Required if roi_type is 'mask'. Default is None. - roi_coords : tuple or None, optional - Coordinates (x, y, z) for the center of the sphere ROI. *Required if* roi_type is 'coords'. Default is None. + roi_coords : tuple or None, optional + Coordinates (x, y, z) for the center of the sphere ROI. *Required if* roi_type is 'coords'. Default is None. - radius_mm : int or None, optional - Radius of the sphere in millimeters. Required if roi_type is 'coords'. Default is None. + radius_mm : int or None, optional + Radius of the sphere in millimeters. Required if roi_type is 'coords'. Default is None. - detrend : bool, optional - Whether to detrend the BOLD signal using Nilearn's detrend function. Default is False. + detrend : bool, optional + Whether to detrend the BOLD signal using Nilearn's detrend function. Default is False. - fwhm_smooth : float or None, optional - Full-width at half-maximum (FWHM) value for Gaussian smoothing of the BOLD data. Default is None. + fwhm_smooth : float or None, optional + Full-width at half-maximum (FWHM) value for Gaussian smoothing of the BOLD data. Default is None. - n_jobs : int, optional - Number of CPUs to use for parallel processing. Default is 1. + n_jobs : int, optional + Number of CPUs to use for parallel processing. Default is 1. Returns ------- - list or tuple - - If roi_type is 'mask': - - List of numpy arrays containing the time series data for each subject/run. - - List of subject information strings formatted as 'sub-{sub_id}_run-{run_id}'. - - If roi_type is 'coords': - - List of numpy arrays containing the averaged time series data for each subject/run. - - Nifti1Image object representing the coordinate mask used. - - List of subject information strings formatted as 'sub-{sub_id}_run-{run_id}'. + list or tuple + - If roi_type is 'mask': + - List of numpy arrays containing the time series data for each subject/run. + - List of subject information strings formatted as 'sub-{sub_id}_run-{run_id}'. + - If roi_type is 'coords': + - List of numpy arrays containing the averaged time series data for each subject/run. + - Nifti1Image object representing the coordinate mask used. + - List of subject information strings formatted as 'sub-{sub_id}_run-{run_id}'. Example ------- - # Extract time series for BOLD data using a mask ROI - roi_type = 'mask' - bold_paths = ['./sub-01_ses-01_task-lit_bold.nii.gz', './sub-02_ses-01_task-lit_bold.nii.gz'] - roi_mask = './siq-roi_mask.nii.gz' - time_series_list, sub_info_list = extract_time_series(bold_paths, roi_type, roi_mask=roi_mask, - high_pass_sec=100, detrend=True, fwhm_smooth=5.0) - - # Extract time series for BOLD data using coordinates ROI - roi_type = 'coords' - bold_paths = ['./sub-01_ses-01_task-lit_bold.nii.gz', './sub-02_ses_1_task-lit_bold.nii.gz'] - roi_coords = (30, -15, 0) - time_series_list, coord_mask, sub_info_list = extract_time_series(bold_paths, roi_type, roi_coords=roi_coords, - radius_mm=5, high_pass_sec=100, - detrend=True, fwhm_smooth=5.0) + # Extract time series for BOLD data using a mask ROI + roi_type = 'mask' + bold_paths = ['./sub-01_ses-01_task-lit_bold.nii.gz', './sub-02_ses-01_task-lit_bold.nii.gz'] + roi_mask = './siq-roi_mask.nii.gz' + time_series_list, sub_info_list = extract_time_series(bold_paths, roi_type, roi_mask=roi_mask, high_pass_sec=100, detrend=True, fwhm_smooth=5.0) + + # Extract time series for BOLD data using coordinates ROI + roi_type = 'coords' + bold_paths = ['./sub-01_ses-01_task-lit_bold.nii.gz', './sub-02_ses_1_task-lit_bold.nii.gz'] + roi_coords = (30, -15, 0) + time_series_list, coord_mask, sub_info_list = extract_time_series(bold_paths, roi_type, roi_coords=roi_coords, radius_mm=5, high_pass_sec=100, detrend=True, fwhm_smooth=5.0) """ - roi_options = ['mask', 'coords'] if roi_type not in roi_options: