funROI.analysis

class funROI.analysis.EffectEstimator(subjects: List[str], froi: FROIConfig, fill_na_with_zero: bool | None = True, orthogonalization: str | None = 'all-but-one')[source]

Estimate the effect of a ROI on the data.

Parameters:

  • subjects (List[str]) – List of subject labels.

  • froi (FROIConfig) – fROI configuration to estimate the effect of.

  • fill_na_with_zero (Optional[bool]) – Whether to fill NaN values with zero. If False, NaN values will be ignored. Default is True.

  • orthogonalization (Optional[str]) – The orthogonalization method. Options are ‘all-but-one’ and ‘odd-even’. Default is ‘all-but-one’.

run(task: str, effects: List[str]) → Tuple[DataFrame, DataFrame][source]

Run the effect estimation. The results are stored in the analysis output folder.

Parameters:

  • task (str) – Task label.

  • effects (List[str]) – List of effect labels.

Returns:

The results are returned as a tuple of two dataframes: the effect estimates averaged across runs, and the effect estimates detailed by run.

Return type:

Tuple[pd.DataFrame, pd.DataFrame]

class funROI.analysis.FROIGenerator(subjects: List[str], froi: FROIConfig, run_label: str | None = 'all')[source]

Generate fROI maps for a fROI configuration.

Warning

The contrasts and parcels images are assumed to be in the same space and have the same dimensions. Future versions may support generating fROIs to native space, etc.

Parameters:

  • subjects (List[str]) – List of subject labels.

  • froi (FROIConfig) – fROI configuration.

  • run_label (Optional[str]) – Label of the run to generate the fROIs for. Default is “all”, where a contrast map for all runs is used to generate the fROI for each subject. Alternatively, this can be a specific run label, ‘odd’ for odd runs, ‘even’ for even runs, ‘orth<run_label>’ for all-but-one runs.

run(save: bool | None = True) → List[Tuple[str, Nifti1Image]] | None[source]

Run the fROI generation. The results are stored in the analysis output folder.

Parameters:

save (Optional[bool]) – Whether to save the results to the analysis output folder.

Returns:

the results are returned as a list of tuples, where each tuple contains the subject label and the FROI map.

Return type:

Optional[List[Tuple[str, Nifti1Image]]]

select(froi_label: int | str, return_results: bool | None = False) → List[Tuple[str, Nifti1Image]] | None[source]

Select a specific fROI label on the maps. The selected fROI label is kept, while all other labels are set to zero. The results are stored in the analysis output folder.

Returns:

If return_results is True, the results are also returned as a list of tuples, where each tuple contains the subject label and the filtered FROI map.

Return type:

Optional[List[Tuple[str, Nifti1Image]]]

Raises:

ValueError – If the fROI label is not found in the fROI.

class funROI.analysis.OverlapEstimator(kind: str | None = 'overlap', orthogonalization: str | None = 'all-but-one')[source]

Estimate the overlap between two sets of parcels or fROIs.

Parameters:

  • kind (Optional[str]) – Kind of overlap to estimate. Options are ‘overlap’ and ‘dice’. Default is ‘overlap’.

  • orthogonalization (Optional[str]) – Orthogonalization method to use. Options are ‘all-but-one’ and ‘odd-even’. Default is ‘all-but-one’.

run(froi1: FROIConfig | str | ParcelsConfig, froi2: FROIConfig | str | ParcelsConfig, subject1: str | None = None, subject2: str | None = None, run1: str | None = None, run2: str | None = None)[source]

Run the overlap estimation. The results are stored in the analysis output folder.

Parameters:

  • froi1 (Union[FROIConfig, str, ParcelsConfig]) – fROI or parcels configuration for the first set of parcels or fROIs.

  • froi2 (Union[FROIConfig, str, ParcelsConfig]) – fROI or parcels configuration for the second set of parcels or fROIs.

  • subject1 (str) – Subject label for the first set of fROIs. Required if fROIs are used.

  • subject2 (str) – Subject label for the second set of fROIs. Required if fROIs are used.

  • run1 (Optional[str]) – Run label for the first set of parcels or fROIs. If not specified, the run is determined by automatic orthogonalization.

  • run2 (Optional[str]) – Run label for the second set of parcels or fROIs. If not specified, the run is determined by automatic orthogonalization.

Returns:

the results are returned as a tuple of two dataframes: the overlap estimates averaged across runs, and the overlap estimates detailed by run.

Return type:

Optional[Tuple[pd.DataFrame, pd.DataFrame]]

Raises:

ValueError – If the parcels are used and the parcels image is not found.

class funROI.analysis.ParcelsGenerator(parcels_name: str, smoothing_kernel_size: float | List[float] | None = 8, overlap_thr_vox: float | None = 0.1, min_voxel_size: int | None = 0, overlap_thr_roi: float | None = 0, use_spm_smooth: bool | None = True)[source]

Generate parcels using with a set of subject data.

Warning

In order to run parcels generation, all images are required to be in the same space and have the same dimensions. This is assumed throughout the process.

Parameters:

  • parcels_name (str) – Name of the parcels to generate.

  • smoothing_kernel_size (Optional[Union[float, List[float]]]) – Size of the smoothing kernel in mm. If a list, the smoothing is performed with a different kernel size for each dimension. Default is 8.

  • overlap_thr_vox (Optional[float]) – Minimum overlap proportion for a voxel to be included in the parcel formation. Default is 0.1.

  • min_voxel_size (Optional[int]) – Minimum size of the parcels in voxels. Can be used post-hoc to filter out small parcels. Default is 0.

  • overlap_thr_roi (Optional[float]) – Minimum overlap proportion for a parcel to be included in the final set of parcels. Can be used post-hoc to filter out parcels that have low overlap with subject activation data. Default is 0.

  • use_spm_smooth (Optional[bool]) – Whether to use SPM’s smoothing function to smooth the data before parcel generation. If False, the smoothing is done using Nilearn’s Gaussian smoothing. Default is True.

add_subjects(subjects: List[str], task: str, contrasts: List[str], p_threshold_type: str, p_threshold_value: float, conjunction_type: str | None = 'and')[source]

Add subjects to the parcels generation.

Parameters:

  • subjects (List[str]) – List of subject labels.

  • task (str) – Task name.

  • contrasts (List[str]) – List of contrast labels.

  • p_threshold_type (str) – Type of p-value thresholding. One of “none”, “bonferroni”, or “fdr”. Default is “none”.

  • p_threshold_value (float) – P-value threshold. Default is 0.05.

  • conjunction_type (str) – Type of conjunction if multiple contrasts are used. One of “min”, “max”, “sum”, “prod”, “and”, or “or”. Default is “and”.

Raises:

  • ValueError – If any of the subjects are already added.

  • ValueError – If the subjects have different image shapes or affines from the previous data.

filter(overlap_thr_roi: float | None = 0, min_voxel_size: int | None = 0) → Nifti1Image[source]

Filter the parcels with new filtering parameters. The filtered results are stored in the analysis output folder.

Returns:

a labelled image of the filtered parcels is returned.

Return type:

Nifti1Image

Raises:

RuntimeError – If the parcels have not been generated yet.

run() → Nifti1Image[source]

Run the parcels generation. Both the generated parcels and the filtered parcels are stored in the analysis output folder.

Returns:

a labelled image of the parcels is returned.

Return type:

Nifti1Image

class funROI.analysis.SpatialCorrelationEstimator(subjects: List[str], froi: str | ParcelsConfig | FROIConfig, orthogonalization: str | None = 'all-but-one')[source]

Estimate the spatial correlation between two contrasts.

Parameters:

  • subjects (List[str]) – List of subject labels.

  • froi (Union[str, ParcelsConfig, FROIConfig]) – fROI or parcels configuration to estimate the effect of.

  • orthogonalization (Optional[str]) – Orthogonalization method to use. Options are ‘all-but-one’ and ‘odd-even’. Default is ‘all-but-one’.

Raises:

ValueError – If the parcels are specified, but no parcels are found for the given configuration.

run(task1: str, effect1: str, task2: str, effect2: str, run_froi: str | None = None, run1: str | None = None, run2: str | None = None)[source]

Run the spatial correlation estimation. The results are stored in the analysis output folder.

Parameters:

  • task1 (str) – Task label for the first contrast.

  • effect1 (str) – Effect label for the first contrast.

  • task2 (str) – Task label for the second contrast.

  • effect2 (str) – Effect label for the second contrast.

  • run_froi (Optional[str]) – Run fROI label. If not specified, the fROI is determined by automatic orthogonalization.

  • run1 (Optional[str]) – Run label for the first contrast. If not specified, the run is determined by automatic orthogonalization.

  • run2 (Optional[str]) – Run label for the second contrast. If not specified, the run is determined by automatic orthogonalization.

Returns:

the results are returned as a tuple of two dataframes: the spatial correlation estimates averaged across runs, and the spatial correlation estimates detailed by run.

Return type:

Optional[Tuple[pd.DataFrame, pd.DataFrame]]

Raises:

  • ValueError – If run labels are not specified, and fROI, effect1, and effect2 are all non-orthogonal to each other.

  • ValueError – Some but not all necessary run labels are specified.