API

atlas

class giga_connectome.atlas.ATLAS_CONFIG_TYPE
class giga_connectome.atlas.ATLAS_SETTING_TYPE
giga_connectome.atlas.get_atlas_labels() → list[str]

Get the list of available atlas labels.

giga_connectome.atlas.load_atlas_setting(atlas: str | Path | dict[str, Any]) → ATLAS_SETTING_TYPE

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(subject_seg_file_names: list[str], atlas_config: ATLAS_SETTING_TYPE, subject_mask_dir: Path, subject_mask: Nifti1Image) → list[Path]

Resample a atlas collection to group grey matter mask.

Parameters:

  • subject_atlas_file_names (list of str) – File names of subject atlas segmentations.

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

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

  • subject_mask (nibabel.nifti1.Nifti1Image) – EPI (grey matter) mask for the subject.

Returns:

Paths to subject specific segmentations created from atlases sampled to individual grey matter mask.

Return type:

list of pathlib.Path

connectome

giga_connectome.connectome.build_size_roi(mask: ndarray[Any, Any], region_ids: dict[str | int, int | float]) → ndarray[Any, dtype[Any]]

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).

  • region_ids (dict[str | int, int | float]) – 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: ndarray[Any, Any], region_ids: dict[str | int, int | float], time_series_atlas: ndarray[Any, Any], group_mask: str | Path | Nifti1Image, atlas_image: str | Path | Nifti1Image) → tuple[ndarray[Any, Any], ndarray[Any, Any]]

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.

  • region_ids (dict[str | int, int | float]) – Labels for each parcel in the atlas.

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

  • group_mask (str | Path | Nifti1Image) – The group grey matter mask.

  • atlas_image (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: NiftiLabelsMasker, denoised_img: Nifti1Image, group_mask: str | Path, correlation_measure: ConnectivityMeasure, calculate_average_correlation: bool) → tuple[ndarray[Any, Any], ndarray[Any, Any], NiftiLabelsMasker]

Generate timeseries-based connectomes from functional data.

Parameters:

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

  • denoised_img (Nifti1Image) – Denoised functional image.

  • group_mask (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

class giga_connectome.denoise.METADATA_TYPE
class giga_connectome.denoise.STRATEGY_TYPE
giga_connectome.denoise.denoise_meta_data(strategy: STRATEGY_TYPE, img: str) → METADATA_TYPE

Get metadata of the denoising process.

Including: column names of the confound regressors, number of volumes discarded by motion scrubbing, number of volumes discarded by non-steady states detector, mean framewise displacement and place holder for sampling frequency (1/TR).

Parameters:

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

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

Returns:

Metadata of the denoising process.

Return type:

dict

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

Denoise voxel level data per nifti image.

Parameters:

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

  • group_mask (str | Path) – Path to the group mask.

  • standardize (bool) – Standardize the data. If True, zscore the data. 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) → STRATEGY_TYPE

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: STRATEGY_TYPE) → 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_subject_gm_mask(imgs: Sequence[Path | str | Nifti1Image], template: str = 'MNI152NLin2009cAsym', templateflow_dir: Path | None = None, n_iter: int = 2) → Nifti1Image

Generate a subject EPI grey matter mask, and overlaid with a MNI grey matter template. The subject EPI mask will ensure the signal extraction is from the most overlapping voxels for all scans of the subject.

Parameters:

  • imgs (list of Path or str or Nifti1Image) – 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.

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: STRATEGY_TYPE, atlas: ATLAS_SETTING_TYPE, resampled_atlases: Sequence[str | Path], images: Sequence[BIDSImageFile], group_mask: str | Path, standardize: bool, smoothing_fwhm: float, output_path: Path, 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.

  • atlas (dict) – Atlas settings.

  • 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 (bool) – Standardization to zscore or not used in nilearn, passed to nilearn masker.

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

  • output_path – Full path to output directory.

  • analysis_level (str) – Level of analysis, only “participant” is available.

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

utils

giga_connectome.utils.check_filter(bids_filters: None | dict[str, dict[str, str]]) → dict[str, dict[str, str]]

Should only have bold and mask.

giga_connectome.utils.check_path(path: Path) → None

Check if given path (file or dir) already exists.

If so, a warning is logged and the previous file is deleted. If the parent path does not exist, it is created.

giga_connectome.utils.create_ds_description(output_dir: Path) → None

Create a dataset_description.json file.

giga_connectome.utils.create_sidecar(output_path: Path) → None

Create a JSON sidecar for the connectivity data.

giga_connectome.utils.get_bids_images(subjects: list[str], template: str, bids_dir: Path, reindex_bids: bool, bids_filters: None | dict[str, dict[str, str]]) → tuple[dict[str, list[BIDSFile]], BIDSLayout]

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

giga_connectome.utils.get_subject_lists(participant_label: None | list[str] = 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.output_filename(source_file: str, atlas: str, suffix: str, extension: str, strategy: str | None = None, atlas_desc: str | None = None) → str

Generate output filneme.

giga_connectome.utils.parse_bids_filter(value: Path) → None | dict[str, dict[str, str]]

Parse a BIDS filter json file.

Parameters.

valuePath

Path to the BIDS json file.

returns:

Dictionary of BIDS filters.

rtype:

dict

giga_connectome.utils.parse_bids_name(img: str) → tuple[str, str | None, str]

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

giga_connectome.utils.prepare_bidsfilter_and_template(strategy: STRATEGY_TYPE, user_bids_filter: None | dict[str, dict[str, str]]) → tuple[str, dict[str, dict[str, str]]]

Prepare the template and BIDS filters for ICA AROMA. This solution only applies to fMRIPrep version < 23.1.0. For later versions, we will wait for updates in the upstream library nilearn to support the new layoput for ICA AROMA.

Parameters:

  • strategy (str) – The denoising strategy.

  • bids_filter_file (Path) – The path to the BIDS filter file.

Returns:

The template and BIDS filters.

Return type:

tuple[str, None | dict[str, dict[str, str]]]