Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

issue usage docs, fix #7

Merged
merged 1 commit into from
Jun 22, 2024
Merged

issue usage docs, fix #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx_rtd_theme',
]

Expand Down
Binary file modified docs/img_png/pyrelimri_logo.psd
View file
Open in desktop
Binary file not shown.
236 changes: 95 additions & 141 deletions pyrelimri/brain_icc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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/',
Expand Down Expand Up @@ -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
Expand All @@ -211,92 +196,61 @@ 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).

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]
Expand Down
82 changes: 39 additions & 43 deletions pyrelimri/masked_timeseries.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading