Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the user guide for the big picture.

nilearn.regions.ReNA

class nilearn.regions.ReNA(mask_img=None, n_clusters=2, scaling=False, n_iter=10, threshold=1e-07, memory=None, memory_level=1, verbose=0)

Recursive Neighbor Agglomeration (ReNA).

Recursively merges the pair of clusters according to 1-nearest neighbors criterion. See Hoyos-Idrobo et al.[1].

Parameters:

mask_imgNiimg-like object or SurfaceImage or SurfaceMasker object or None, default=None

Object used for masking the data. If None is passed a dummy nifti image will be created to match the array passed at fit time.

n_clustersint, default=2

The number of clusters to find.

scalingbool, default=False

If scaling is True, each cluster is scaled by the square root of its size, preserving the l2-norm of the image.

n_iterint, default=10

Number of iterations of the recursive neighbor agglomeration.

thresholdfloat in the open interval (0., 1.), default=1e-7

Threshold used to handle eccentricities.

memoryNone, instance of joblib.Memory, str, or pathlib.Path

Used to cache the masking process. By default, no caching is done. If a str is given, it is the path to the caching directory.

memory_levelint, default=1

Rough estimator of the amount of memory used by caching. Higher value means more memory for caching. Zero means no caching.

verboseint, default=0

Verbosity level (0 means no message).

Attributes:

labels_numpy.ndarray, shape = [n_features]

Cluster labels for each feature.

n_clusters_int

Number of clusters.

sizes_numpy.ndarray, shape = [n_features]

It contains the size of each cluster.

References

[1]

Andres Hoyos-Idrobo, Gael Varoquaux, Jonas Kahn, and Bertrand Thirion. Recursive nearest agglomeration (rena): fast clustering for approximation of structured signals. IEEE Trans. Pattern Anal. Mach. Intell., 41(3):669–681, 3 2019. doi:10.1109/TPAMI.2018.2815524.

__init__(mask_img=None, n_clusters=2, scaling=False, n_iter=10, threshold=1e-07, memory=None, memory_level=1, verbose=0)

fit(X, y=None)

Compute clustering of the data.

Parameters:

Xnumpy.ndarray, shape = [n_samples, n_features]

Training data.

yNone

This parameter is unused. It is solely included for scikit-learn compatibility.

Returns:

selfReNA object

fit_predict(X, y=None, **kwargs)

Perform clustering on X and returns cluster labels.

Parameters:

Xarray-like of shape (n_samples, n_features)

Input data.

yIgnored

Not used, present for API consistency by convention.

**kwargsdict

Arguments to be passed to fit.

Added in version 1.4.

Returns:

labelsndarray of shape (n_samples,), dtype=np.int64

Cluster labels.

fit_transform(X, y=None, **fit_params)

Fit to data, then transform it.

Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.

Parameters:

Xarray-like of shape (n_samples, n_features)

Input samples.

yarray-like of shape (n_samples,) or (n_samples, n_outputs), default=None

Target values (None for unsupervised transformations).

**fit_paramsdict

Additional fit parameters.

Returns:

X_newndarray array of shape (n_samples, n_features_new)

Transformed array.

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest

A MetadataRequest encapsulating routing information.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deepbool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict

Parameter names mapped to their values.

inverse_transform(X_red)

Send the reduced 2D data matrix back to the original feature space (voxels).

Parameters:

X_rednumpy.ndarray, shape = [n_samples, n_clusters]

Data reduced with agglomerated signal for each cluster.

Returns:

X_invnumpy.ndarray, shape = [n_samples, n_features]

Data reduced expanded to the original feature space.

set_inverse_transform_request(*, X_red='$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:

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

Metadata routing for X_red parameter in inverse_transform.

Returns:

selfobject

The updated object.

set_output(*, transform=None)

Set the output container when "transform" is called.

Warning

This has not been implemented yet.

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict

Estimator parameters.

Returns:

selfestimator instance

Estimator instance.

transform(X, y=None)

Apply clustering, reduce the dimensionality of the data.

Parameters:

Xnumpy.ndarray, shape = [n_samples, n_features]

Data to transform with the fitted clustering.

yNone

This parameter is unused. It is solely included for scikit-learn compatibility.

Returns:

X_rednumpy.ndarray, shape = [n_samples, n_clusters]

Data reduced with agglomerated signal for each cluster.