nimare.decode.continuous.CorrelationDecoder

class CorrelationDecoder(feature_group=None, features=None, frequency_threshold=0.001, meta_estimator=None, target_image='z_desc-association', n_cores=1)

Bases: Decoder

Decode an unthresholded image by correlating the image with meta-analytic maps.

Changed in version 0.1.0:

• New method: load_imgs. Load pre-generated meta-analytic maps for decoding.

• New attribute: results_. MetaResult object containing masker, meta-analytic maps, and tables. This attribute replaces masker, features_, and images_.

Changed in version 0.0.13:

• New parameter: n_cores. Number of cores to use for parallelization.

Changed in version 0.0.12:

• Remove low-memory option in favor of sparse arrays.

Parameters:

• feature_group (str, optional) – Feature group

• features (list, optional) – Features

• frequency_threshold (float, optional) – Frequency threshold

• meta_estimator (CBMAEstimator, optional) – Meta-analysis estimator. Default is MKDAChi2.

• target_image (str, optional) – Name of meta-analysis results image to use for decoding.

• n_cores (int, optional) – Number of cores to use for parallelization. If <=0, defaults to using all available cores. Default is 1.

Warning

Coefficients from correlating two maps have very large degrees of freedom, so almost all results will be statistically significant. Do not attempt to evaluate results based on significance.

Methods

fit(dataset[, drop_invalid])	Fit Decoder to Dataset.
get_params([deep])	Get parameters for this estimator.
load(filename[, compressed])	Load a pickled class instance from file.
load_imgs(features_imgs[, mask])	Load pregenerated maps from disk.
save(filename[, compress])	Pickle the class instance to the provided file.
set_params(**params)	Set the parameters of this estimator.
transform(img)	Correlate target image with each feature-specific meta-analytic map.

fit(dataset, drop_invalid=True)

Fit Decoder to Dataset.

Parameters:

• dataset (Dataset) – Dataset object to analyze.

• drop_invalid (bool, default=True) – Whether to automatically ignore any studies without the required data or not. Default is True.

Notes

The fit method is a light wrapper that runs input validation and preprocessing before fitting the actual model. Decoders’ individual “fitting” methods are implemented as _fit, although users should call fit.

Selection of features based on requested features and feature group is performed in Decoder._preprocess_input.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

params – Parameter names mapped to their values.

Return type:

dict

classmethod load(filename, compressed=True)

Load a pickled class instance from file.

Parameters:

• filename (str) – Name of file containing object.

• compressed (bool, default=True) – If True, the file is assumed to be compressed and gzip will be used to load it. Otherwise, it will assume that the file is not compressed. Default = True.

Returns:

obj – Loaded class object.

Return type:

class object

load_imgs(features_imgs, mask=None)

Load pregenerated maps from disk.

New in version 0.1.0.

Parameters:

• features_imgs (dict, or str) – Dictionary with feature names as keys and paths to images as values. If a string is provided, it is assumed to be a path to a folder with NIfTI images, where the file’s name (without the extension .nii.gz) will be considered as the feature name by the decoder.

• mask (str, nibabel.nifti1.Nifti1Image, or any nilearn Masker) – Mask to apply to pre-generated maps.

Variables:

results (MetaResult) – MetaResult with meta-analytic maps and masker added.

save(filename, compress=True)

Pickle the class instance to the provided file.

Parameters:

• filename (str) – File to which object will be saved.

• compress (bool, optional) – If True, the file will be compressed with gzip. Otherwise, the uncompressed version will be saved. Default = True.

set_params(**params)

Set the parameters of this estimator.

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

Return type:

self

transform(img)

Correlate target image with each feature-specific meta-analytic map.

Parameters:

img (Nifti1Image) – Image to decode. Must be in same space as dataset.

Returns:

out_df – DataFrame with one row for each feature, an index named “feature”, and one column: “r”.

Return type:

pandas.DataFrame