API

atlas

giga_connectome.atlas.load_atlas_setting(atlas: str | Path | dict)

Load atlas details for templateflow api to fetch. The setting file can be configured for atlases not included in the templateflow collections, but user has to organise their files to templateflow conventions to use the tool.

Parameters:

atlas (str or pathlib.Path or dict) –

Path to atlas configuration json file or a python dictionary. It should contain the following fields:

  • name : name of the atlas.

  • parameters : BIDS entities that fits templateflow conventions except desc.

  • desc : templateflow entities description. Can be a list if user wants to include multiple resolutions of the atlas.

  • templateflow_dir : Path to templateflow director. If null, use the system default.

Returns:

Path to the atlas files.

Return type:

dict

giga_connectome.atlas.resample_atlas_collection(template: str, atlas_config: dict, group_mask_dir: Path, group_mask: Nifti1Image) → List[Path]

Resample a atlas collection to group grey matter mask.

Parameters:

  • template (str) – Templateflow template name. This template should match the template of all_masks.

  • atlas_config (dict) – Atlas name. Currently support Schaefer20187Networks, MIST, DiFuMo.

  • group_mask_dir (pathlib.Path) – Path to where the outputs are saved.

  • group_mask (nibabel.nifti1.Nifti1Image) – EPI (grey matter) mask for the current group of subjects.

Returns:

Paths to atlases sampled to group level grey matter mask.

Return type:

List of pathlib.Path

connectome

giga_connectome.connectome.build_size_roi(mask: ndarray, labels_roi: ndarray) → ndarray

Extract labels and sizes of ROIs given an atlas. The atlas parcels must be discrete segmentations.

Adapted from: https://github.com/SIMEXP/niak/blob/master/commands/SI_processing/niak_build_size_roi.m [SIZE_ROI,LABELS_ROI] = BUILD_SIZE_ROI(MASK)

Parameters:

  • mask (np.ndarray) – Mask of the ROI. Voxels belonging to no region are coded with 0, those belonging to region I are coded with I (I being a positive integer).

  • labels_roi (np.ndarray) – Labels of region I.

Returns:

An array containing the sizes of the ROIs.

Return type:

np.ndarray

giga_connectome.connectome.calculate_intranetwork_correlation(correlation_matrix: array, masker_labels: array, time_series_atlas: array, group_mask: str | Path | Nifti1Image, atlas_image: str | Path | Nifti1Image) → Tuple[ndarray, ndarray]

Calculate the average functional correlation within each parcel. Currently we only support discrete segmentations.

Parameters:

  • correlation_matrix (np.array) – N by N Pearson’s correlation matrix.

  • masker_labels (np.array) – Labels for each parcel in the atlas.

  • time_series_atlas (np.array) – Time series extracted from each parcel.

  • group_mask (Union[str, Path, Nifti1Image]) – The group grey matter mask.

  • atlas_image (Union[str, Path, Nifti1Image]) – 3D atlas image.

Returns:

A tuple containing the modified Pearson’s correlation matrix with the diagonal replaced by the average correlation within each parcel, and an array of the computed average intranetwork correlations for each parcel.

Return type:

Tuple[np.ndarray, np.ndarray]

giga_connectome.connectome.generate_timeseries_connectomes(masker: NiftiMasker, denoised_img: Nifti1Image, group_mask: str | Path, correlation_measure: ConnectivityMeasure, calculate_average_correlation: bool) → Tuple[ndarray, ndarray]

Generate timeseries-based connectomes from functional data.

Parameters:

  • masker (NiftiMasker) – NiftiMasker instance for extracting time series.

  • denoised_img (Nifti1Image) – Denoised functional image.

  • group_mask (Union[str, Path]) – Path to the group grey matter mask.

  • correlation_measure (ConnectivityMeasure) – Connectivity measure for computing correlations.

  • calculate_average_correlation (bool) – Flag indicating whether to calculate average parcel correlations.

Returns:

A tuple containing the correlation matrix and time series atlas.

Return type:

Tuple[np.ndarray, np.ndarray]

denoise

giga_connectome.denoise.denoise_nifti_voxel(strategy: dict, group_mask: str | Path, standardize: str | bool, smoothing_fwhm: float, img: str) → Nifti1Image

Denoise voxel level data per nifti image.

Parameters:

  • strategy (dict) – Denoising strategy parameter to pass to load_confounds_strategy.

  • group_mask (Union[str, Path]) – Path to the group mask.

  • standardize (Union[str, bool]) – Standardize the data. If ‘zscore’, zscore the data. If ‘psc’, convert the data to percent signal change. If False, do not standardize.

  • smoothing_fwhm (float) – Smoothing kernel size in mm.

  • img (str) – Path to the nifti image to denoise.

Returns:

Denoised nifti image.

Return type:

Nifti1Image

giga_connectome.denoise.get_denoise_strategy(strategy: str) → dict

Select denoise strategies and associated parameters. The strategy parameters are designed to pass to load_confounds_strategy.

Parameter

strategystr

Name of the denoising strategy options: simple, simple+gsr, scrubbing.5, scrubbing.5+gsr, scrubbing.2, scrubbing.2+gsr, acompcor50, icaaroma. Or the path to a configuration json file.

returns:

Denosing strategy parameter to pass to load_confounds_strategy.

rtype:

dict

giga_connectome.denoise.is_ica_aroma(strategy: str) → bool

Check if the current strategy is ICA AROMA.

Parameters:

strategy (dict) – Denoising strategy dictionary. See get_denoise_strategy().

Returns:

True if the strategy is ICA AROMA.

Return type:

bool

mask

giga_connectome.mask.generate_group_mask(imgs: list, template: str = 'MNI152NLin2009cAsym', templateflow_dir: Path | None = None, n_iter: int = 2, verbose: int = 1) → Nifti1Image

Generate a group EPI grey matter mask, and overlaid with a MNI grey matter template. The Group EPI mask will ensure the signal extraction is from the most overlapping voxels.

Parameters:

  • imgs (list of string) – List of EPI masks or preprocessed BOLD data.

  • template (str, Default = MNI152NLin2009cAsym) – Template name from TemplateFlow to retrieve the grey matter template. This template should match the template for the EPI mask.

  • templateflow_dir (None or pathlib.Path) – TemplateFlow directory. Default to None to download the directory, otherwise use the templateflow data saved at the given path.

  • n_iter (int, optional, Default = 2) – Number of repetitions of dilation and erosion steps performed in scipy.ndimage.binary_closing function.

  • verbose – Level of verbosity.

Keyword Arguments:

  • cirret (Used to filter the) –

  • module. (See keyword arguments in templateflow.api) –

Returns:

EPI (grey matter) mask for the current group of subjects.

Return type:

nibabel.nifti1.Nifti1Image

postprocess

giga_connectome.postprocess.run_postprocessing_dataset(strategy: dict, resampled_atlases: List[str | Path], images: List[BIDSImageFile], group_mask: str | Path, standardize: str | bool, smoothing_fwhm: float, output_path: Path, analysis_level: str, calculate_average_correlation: bool = False) → None

Generate subject and group level timeseries and connectomes.

The time series data is denoised as follow:

  • Time series extractions through label or map maskers are performed on the denoised nifti file. Denoising steps are performed on the voxel level:

    • spatial smoothing

    • detrend, only if high pass filter is not applied through confounds

    • Regress out confounds

    • standardize

  • Extract time series from atlas

  • Compute correlation matrix

  • Optional: average correlation within each parcel.

  • Save timeseries and correlation matrix to h5 file

  • Optional: Create average correlation matrix across subjects when using group level analysis.

Parameters:

  • strategy (dict) – Parameters for load_confounds_strategy or load_confounds.

  • resampled_atlases (list of str or pathlib.Path) – Atlas niftis resampled to the common space of the dataset.

  • images (list of BIDSImageFile) – Preprocessed Nifti images for post processing

  • group_mask (str or pathlib.Path) – Group level grey matter mask.

  • standardize (str or bool) – Standardization options used in nilearn, passed to nilearn masker. Options: True, False, “psc”

  • smoothing_fwhm (float) – Smoothing kernel size, passed to nilearn masker.

  • output_path – Full path to output file, named in the following format: output_dir / atlas-<atlas>_desc-<strategy_name>.h5

  • analysis_level (str) – Level of analysis, either “participant” or “group”.

  • calculate_average_correlation (bool) – Whether to calculate average correlation within each parcel.

utils

giga_connectome.utils.check_filter(bids_filters: dict) → dict

Should only have bold and mask.

giga_connectome.utils.check_path(path: Path, verbose=True)

Check if given path (file or dir) already exists, and if so returns a new path with _<n> appended (n being the number of paths with the same name that exist already).

giga_connectome.utils.get_bids_images(subjects: List[str], template: str, bids_dir: Path, reindex_bids: bool, bids_filters: dict) → Tuple[dict, BIDSLayout]

Apply BIDS filter to the base filter we are using. Modified from fmripprep

giga_connectome.utils.get_subject_lists(participant_label: List[str] | None = None, bids_dir: Path | None = None) → List[str]

Parse subject list from user options.

Parameters:

  • participant_label – A list of BIDS competible subject identifiers. If the prefix sub- is present, it will be removed.

  • bids_dir – The fMRIPrep derivative output.

Returns:

BIDS subject identifier without sub- prefix.

Return type:

List

giga_connectome.utils.parse_bids_name(img: str) → List[str]

Get subject, session, and specifier for a fMRIPrep output.