9.4.1. Nilearn

Custom objects adapted from nilearn.

class junifer.external.nilearn.JuniferConnectivityMeasure(cov_estimator=EmpiricalCovariance(store_precision=False), kind='correlation', vectorize=False, discard_diagonal=False, standardize='zscore_sample')

Class for custom ConnectivityMeasure.

Differs from nilearn.connectome.ConnectivityMeasure in the following ways:

  • default cov_estimator is sklearn.covariance.EmpiricalCovariance instead of sklearn.covariance.LedoitWolf, and cov_estimator=None is not supported

  • default kind is "correlation" instead of "covariance"

  • supports Spearman’s correlation via kind="spearman correlation"

  • supports Chatterjee’s xi correlation via kind="xi correlation"

  • kind is validated when computing the matrices instead of when fitting

  • no verbose parameter, so nothing is logged while fitting

  • inverse_transform() only knows the diagonal of "correlation" and "partial correlation" matrices, so with discard_diagonal=True the other kinds (including "spearman correlation") need the diagonal to be passed

Parameters:
cov_estimatorestimator object, optional

The covariance estimator (default EmpiricalCovariance(store_precision=False)).

kind{“covariance”, “correlation”, “spearman correlation”, “partial correlation”, “xi correlation”, “tangent”, “precision”}, optional

The matrix kind. The default value uses Pearson’s correlation. If "spearman correlation" is used, the data will be ranked before estimating the covariance. For "xi correlation", the coefficient is not symmetric and should be interpreted as a measure of dependence [2] ; cov_estimator and standardize are not used, mean_ is symmetrized and, if vectorize=True, only the lower triangular part is kept. For the use of "tangent" see [1] (default “correlation”).

vectorizebool, optional

If True, connectivity matrices are reshaped into 1D arrays and only their flattened lower triangular parts are returned (default False).

discard_diagonalbool, optional

If True, vectorized connectivity coefficients do not include the matrices diagonal elements. Used only when vectorize is set to True (default False).

standardize{“zscore_sample”, “psc”} or None, optional

The strategy to standardize the signals before estimating the covariance. "zscore_sample" sets them to zero mean and unit variance (using the sample standard deviation), "psc" converts them to percent signal change and None does not standardize them. Only used for "correlation" and "spearman correlation" (default “zscore_sample”).

Attributes:
cov_estimator_estimator object

A new covariance estimator with the same parameters as cov_estimator.

mean_numpy.ndarray

The mean connectivity matrix across subjects. For "tangent" kind, it is the geometric mean of covariances (a group covariance matrix that captures information from both correlation and partial correlation matrices). For other values for kind, it is the mean of the corresponding matrices.

whitening_numpy.ndarray

The inverted square-rooted geometric mean of the covariance matrices.

References

[1]

Varoquaux, G., Baronnet, F., Kleinschmidt, A. et al. Detection of brain functional-connectivity difference in post-stroke patients using group-level covariance modeling. In Tianzi Jiang, Nassir Navab, Josien P. W. Pluim, and Max A. Viergever, editors, Medical image computing and computer-assisted intervention - MICCAI 2010, Lecture notes in computer science, Pages 200-208. Berlin, Heidelberg, 2010. Springer. doi:10/cn2h9c.

[2]

Chatterjee, S. A new coefficient of correlation. Journal of the American Statistical Association 116.536 (2021): 2009-2022. doi:10.1080/01621459.2020.1758115.

set_inverse_transform_request(*, connectivities='$UNCHANGED$', diagonal='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the inverse_transform method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to inverse_transform if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to inverse_transform.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
connectivitiesstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for connectivities parameter in inverse_transform.

diagonalstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for diagonal parameter in inverse_transform.

Returns:
selfobject

The updated object.

set_transform_request(*, confounds='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the transform method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to transform if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to transform.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
confoundsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for confounds parameter in transform.

Returns:
selfobject

The updated object.

class junifer.external.nilearn.JuniferNiftiSpheresMasker(seeds, radius=None, mask_img=None, agg_func=<function mean>, allow_overlap=False, dtype=None, **kwargs)

Class for custom NiftiSpheresMasker.

Differs from nilearn.maskers.NiftiSpheresMasker in the following ways:

  • it allows to pass any callable as the agg_func parameter.

  • empty spheres do not create an error. Instead, agg_func is applied to an empty array and the result is passed.

  • only the signals of the voxels of the spheres are read, a few volumes at a time (markers.spheres.chunksize), so the whole data is never in memory.

  • reports is False by default, as the data for the reports (e.g., the middle volume of the resampled images) needs the whole data in memory.

Parameters:
seedslist of float

Seed definitions. List of coordinates of the seeds in the same space as the images (typically MNI or TAL).

radiusfloat, optional

Indicates, in millimeters, the radius for the sphere around the seed. If None, signal is extracted on a single voxel (default None).

mask_imgNiimg-like object, optional

Mask to apply to regions before extracting signals (default None).

agg_funccallable(), optional

The function to aggregate signals using (default numpy.mean).

allow_overlapbool, optional

If False, an error is raised if the maps overlap (default None).

dtypenumpy.dtype or “auto”, optional

The dtype for the extraction. If “auto”, the data will be converted to int32 if dtype is discrete and float32 if it is continuous (default None).

**kwargs

Keyword arguments are passed to the nilearn.maskers.NiftiSpheresMasker.

inverse_transform(region_signals)

Compute voxel signals from spheres signals.

Parameters:
region_signals1D/2D numpy.ndarray

Signal for each region. If a 1D array is provided, then the shape should be (number of elements,), and a 3D img will be returned. If a 2D array is provided, then the shape should be (number of scans, number of elements), and a 4D img will be returned.

Returns:
voxel_signalsnibabel.nifti1.Nifti1Image

Signal for each sphere. shape: (mask_img, number of scans).

set_fit_request(*, imgs='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
imgsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for imgs parameter in fit.

Returns:
selfobject

The updated object.

set_inverse_transform_request(*, region_signals='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the inverse_transform method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to inverse_transform if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to inverse_transform.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
region_signalsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for region_signals parameter in inverse_transform.

Returns:
selfobject

The updated object.

set_transform_request(*, confounds='$UNCHANGED$', imgs='$UNCHANGED$', sample_mask='$UNCHANGED$')

Configure whether metadata should be requested to be passed to the transform method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to transform if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to transform.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:
confoundsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for confounds parameter in transform.

imgsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for imgs parameter in transform.

sample_maskstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for sample_mask parameter in transform.

Returns:
selfobject

The updated object.

transform_single_imgs(imgs, confounds=None, sample_mask=None)

Extract signals from a single 4D niimg.

Parameters:
imgs3D/4D Niimg-like object

Images to process. If a 3D niimg is provided, a singleton dimension will be added to the output to represent the single scan in the niimg.

confoundspandas.DataFrame, optional

This parameter is passed to nilearn.signal.clean(). Please see the related documentation for details. shape: (number of scans, number of confounds)

sample_masknp.ndarray, list or tuple, optional

Masks the niimgs along time/fourth dimension to perform scrubbing (remove volumes with high motion) and/or non-steady-state volumes. This parameter is passed to nilearn.signal.clean(). shape: (number of scans - number of volumes removed, )

Returns:
region_signals2D numpy.ndarray

Signal for each sphere. shape: (number of scans, number of spheres)

Warns:
DeprecationWarning

If a 3D niimg input is provided, the current behavior (adding a singleton dimension to produce a 2D array) is deprecated. Starting in version 0.12, a 1D array will be returned for 3D inputs.