KernelTransformers and CBMA

KernelTransformer classes are tools for converting individual studies’ coordinates into images.

For coordinate-based meta-analyses, individual studies’ statistical maps are mimicked by generating “modeled activation” (MA) maps from the coordinates. These MA maps are used in the CBMA algorithms, although the specific method used to generate the MA maps differs by algorithm.

This example provides an introduction to the KernelTransformer class and a tour of available types.

import os

import matplotlib.pyplot as plt
from nilearn.plotting import plot_stat_map

Load Dataset

from nimare.dataset import Dataset
from nimare.utils import get_resource_path

dset_file = os.path.join(get_resource_path(), "nidm_pain_dset.json")
dset = Dataset(dset_file)

# First, let us reduce this Dataset to only two studies
dset = dset.slice(dset.ids[2:4])

Kernels ingest Datasets and can produce a few types of outputs

from nimare.meta.kernel import MKDAKernel

# First, the kernel should be initialized with any parameters.
kernel = MKDAKernel()

# Then, the ``transform`` method takes in the Dataset and produces the MA maps.
output = kernel.transform(dset)

return_type="image" returns a list of 3D niimg objects.

This is the default option.

image_output = kernel.transform(dset, return_type="image")
print(type(image_output))
print(type(image_output[0]))
print(image_output[0].shape)

Out:

<class 'list'>
<class 'nibabel.nifti1.Nifti1Image'>
(91, 109, 91)

return_type="array" returns a 2D numpy array

array_output = kernel.transform(dset, return_type="array")
print(type(array_output))
print(array_output.shape)

Out:

<class 'numpy.ndarray'>
(2, 228483)

There is also an option to return an updated Dataset (return_type="dataset"), with the MA maps saved as nifti files and references in the Dataset’s images attribute. However, this will only work if the Dataset has a location set for its images.

try:
    dataset_output = kernel.transform(dset, return_type="dataset")
except ValueError as error:
    print(error)

Out:

Dataset output path is not set. Set the path with Dataset.update_path().

Each kernel can accept certain parameters that control behavior

You can see what options are available via the API documentation or through the help string.

help(MKDAKernel)

Out:

Help on class MKDAKernel in module nimare.meta.kernel:

class MKDAKernel(KDAKernel)
 |  MKDAKernel(r=10, value=1)
 |
 |  Generate MKDA modeled activation images from coordinates.
 |
 |  .. versionchanged:: 0.0.12
 |
 |      * Remove low-memory option in favor of sparse arrays for kernel transformers.
 |
 |  Parameters
 |  ----------
 |  r : :obj:`int`, optional
 |      Sphere radius, in mm.
 |  value : :obj:`int`, optional
 |      Value for sphere.
 |
 |  Method resolution order:
 |      MKDAKernel
 |      KDAKernel
 |      KernelTransformer
 |      nimare.base.NiMAREBase
 |      builtins.object
 |
 |  Data and other attributes defined here:
 |
 |  __abstractmethods__ = frozenset()
 |
 |  __slotnames__ = []
 |
 |  ----------------------------------------------------------------------
 |  Methods inherited from KDAKernel:
 |
 |  __init__(self, r=10, value=1)
 |      Initialize self.  See help(type(self)) for accurate signature.
 |
 |  ----------------------------------------------------------------------
 |  Methods inherited from KernelTransformer:
 |
 |  transform(self, dataset, masker=None, return_type='image')
 |      Generate modeled activation images for each Contrast in dataset.
 |
 |      Parameters
 |      ----------
 |      dataset : :obj:`~nimare.dataset.Dataset` or :obj:`pandas.DataFrame`
 |          Dataset for which to make images. Can be a DataFrame if necessary.
 |      masker : img_like or None, optional
 |          Mask to apply to MA maps. Required if ``dataset`` is a DataFrame.
 |          If None (and ``dataset`` is a Dataset), the Dataset's masker attribute will be used.
 |          Default is None.
 |      return_type : {'sparse', 'array', 'image', 'dataset'}, optional
 |          Whether to return a numpy array ('array'), a list of niimgs ('image'),
 |          or a Dataset with MA images saved as files ('dataset').
 |          Default is 'image'.
 |
 |      Returns
 |      -------
 |      imgs : (C x V) :class:`numpy.ndarray` or :obj:`list` of :class:`nibabel.Nifti1Image`                or :class:`~nimare.dataset.Dataset`
 |          If return_type is 'sparse', a 4D sparse array (E x S), where E is
 |          the number of unique experiments, and the remaining 3 dimensions are
 |          equal to `shape` of the images.
 |          If return_type is 'array', a 2D numpy array (C x V), where C is
 |          contrast and V is voxel.
 |          If return_type is 'image', a list of modeled activation images
 |          (one for each of the Contrasts in the input dataset).
 |          If return_type is 'dataset', a new Dataset object with modeled
 |          activation images saved to files and referenced in the
 |          Dataset.images attribute.
 |
 |      Attributes
 |      ----------
 |      filename_pattern : str
 |          Filename pattern for MA maps that will be saved by the transformer.
 |      image_type : str
 |          Name of the corresponding column in the Dataset.images DataFrame.
 |
 |  ----------------------------------------------------------------------
 |  Methods inherited from nimare.base.NiMAREBase:
 |
 |  __repr__(self)
 |      Show basic NiMARE class representation.
 |
 |      Specifically, this shows the name of the class, along with any parameters
 |      that are **not** set to the default.
 |
 |  get_params(self, deep=True)
 |      Get parameters for this estimator.
 |
 |      Parameters
 |      ----------
 |      deep : :obj:`bool`, optional
 |          If True, will return the parameters for this estimator and
 |          contained subobjects that are estimators.
 |
 |      Returns
 |      -------
 |      params : :obj:`dict`
 |          Parameter names mapped to their values.
 |
 |  save(self, filename, compress=True)
 |      Pickle the class instance to the provided file.
 |
 |      Parameters
 |      ----------
 |      filename : :obj:`str`
 |          File to which object will be saved.
 |      compress : :obj:`bool`, optional
 |          If True, the file will be compressed with gzip. Otherwise, the
 |          uncompressed version will be saved. Default = True.
 |
 |  set_params(self, **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.
 |
 |      Returns
 |      -------
 |      self
 |
 |  ----------------------------------------------------------------------
 |  Class methods inherited from nimare.base.NiMAREBase:
 |
 |  load(filename, compressed=True) from abc.ABCMeta
 |      Load a pickled class instance from file.
 |
 |      Parameters
 |      ----------
 |      filename : :obj:`str`
 |          Name of file containing object.
 |      compressed : :obj:`bool`, optional
 |          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 : class object
 |          Loaded class object.
 |
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from nimare.base.NiMAREBase:
 |
 |  __dict__
 |      dictionary for instance variables (if defined)
 |
 |  __weakref__
 |      list of weak references to the object (if defined)

For example, MKDAKernel kernel accepts an r argument to control the radius of the kernel.

RADIUS_VALUES = [4, 8, 12]
fig, axes = plt.subplots(ncols=3, figsize=(20, 10))

for i, radius in enumerate(RADIUS_VALUES):
    kernel = MKDAKernel(r=radius)
    ma_maps = kernel.transform(dset, return_type="image")

    plot_stat_map(
        ma_maps[0],
        display_mode="z",
        cut_coords=[-2],
        title=f"r={radius}mm",
        axes=axes[i],
        draw_cross=False,
        annotate=False,
        colorbar=False,
        cmap="RdBu_r",
    )
03 plot kernel transformers

There are several kernels available

MKDAKernel convolves coordinates with a sphere and takes the union across voxels.

kernel = MKDAKernel(r=10)
ma_maps = kernel.transform(dset, return_type="image")

plot_stat_map(
    ma_maps[0],
    cut_coords=[-2, -10, -4],
    title="MKDA",
    draw_cross=False,
    cmap="RdBu_r",
)
03 plot kernel transformers

Out:

<nilearn.plotting.displays._slicers.OrthoSlicer object at 0x7fba227744d0>

KDAKernel convolves coordinates with a sphere as well, but takes the sum across voxels.

from nimare.meta.kernel import KDAKernel

kernel = KDAKernel(r=10)
ma_maps = kernel.transform(dset, return_type="image")

plot_stat_map(
    ma_maps[0],
    cut_coords=[-2, -10, -4],
    title="KDA",
    draw_cross=False,
    cmap="RdBu_r",
)
03 plot kernel transformers

Out:

/home/docs/checkouts/readthedocs.org/user_builds/nimare/checkouts/latest/nimare/meta/kernel.py:209: FutureWarning: Image data has type int64, which may cause incompatibilities with other tools. This will error in NiBabel 5.0. This warning can be silenced by passing the dtype argument to Nifti1Image().
  img = nib.Nifti1Image(kernel_data, mask.affine)

<nilearn.plotting.displays._slicers.OrthoSlicer object at 0x7fba20a0cc10>

ALEKernel convolves coordinates with a 3D Gaussian, for which the FWHM is determined by the sample size of each study. This sample size will be inferred automatically, if that information is available in the Dataset, or it can be set as a constant value across all studies in the Dataset with the sample_size argument.

from nimare.meta.kernel import ALEKernel

kernel = ALEKernel(sample_size=20)
ma_maps = kernel.transform(dset, return_type="image")

plot_stat_map(
    ma_maps[0],
    cut_coords=[-2, -10, -4],
    title="ALE",
    draw_cross=False,
    cmap="RdBu_r",
)
03 plot kernel transformers

Out:

<nilearn.plotting.displays._slicers.OrthoSlicer object at 0x7fba20cc89d0>

Total running time of the script: ( 0 minutes 9.957 seconds)

Gallery generated by Sphinx-Gallery