API Reference

This section provides an overview of the classes and functions available in the AnatSearchlight package.

Searchlight Module

Searchlight familiy class for creating searchlight structures and running searchlight analyses within the defined structures.

created on 2024-05-16

Author: Diedrichsenlab

class AnatSearchlight.searchlight.Searchlight

Bases: object

Base class for searchlight analyses. This class implements the basic behaviors of a searchlight.

Attributes:

classname (str): Name of the class structure (str): Structure name for the cifti file (e.g. ‘cerebellum’, ‘left_hem’, etc.) affine (ndarray): Affine transformation matrix of data and output space shape (tuple): Shape of the data and output space center_indx (ndarray): Voxel / vertex indices of the searchlight centers n_cent (int): Number of searchlight centers maxradius (float): Maximum distance from each searchlight center maxvoxels (int): Maximum number of voxels in the searchlight voxel_indx (ndarray): 3 x P array of voxel indices in functional space (i,j,k) voxlist (list): List of voxel numbers (index into voxel_indx) for each searchlight center voxmin (ndarray): Minimum voxel indices for each searchlight center voxmax (ndarray): Maximum voxel indices for each searchlight center radius (ndarray): Effective radius for each searchlight center nvoxels (ndarray): Number of voxels in the searchlight

define()

Computes the voxel list for a searchlight. Needs to be implemented by the child class.

load(hf)

Loads all obligatory fields from the h5 file

Args:

hf (h5py.file): h5 file object (opened in read mode)

load_single(hf, idx)

Loads a single searchlight (idx) from HDF5 file

run(inputfiles, mvpa_function, function_args={}, verbose=True)

Conducts a searchlight analysis for all the searchlights defined in vox_list.

Args:

inputfiles (list):

List of filenames

mvpa_fumction (fcn):

Function that takes input data (N x n_voxels) and returns a scalar or vector as result. Function should be defined as: def mvpa_function(data, **kwargs):

function_args (dictionary):

Additional arguments to be passed to the mvpa_function as keyword arguments.

Returns:

results (ndarray):

Either one-dimensional or two-dimensional ndarray. First dimension is the number of centers.

run_parallel(inputfiles, mvpa_function, function_args={}, nargout=1, verbose=True, n_jobs=8)

Run searchlight parallel not serial.

save(fname)

Saves the defined searchlight definition to hd5 file Args:

fname (str): Filename

class AnatSearchlight.searchlight.SearchlightSet(list_of_searchlights)

Bases: object

class AnatSearchlight.searchlight.SearchlightSurface(structure='none', depths=[0, 0.2, 0.4, 0.6, 0.8, 1])

Bases: Searchlight

Surface-based searchlights for a single hemisphere, given a individual surface. Voxels we picked from the mask_img, for each vertex on the surface.

data_to_cifti(data, outfilename=None, row_names=None)

Returns a CIFTI file with the results of the searchlight analysis. Args:

results (np.array):

Results of the searchlight analysis (ncenters,n_results). Can either be one-dimensional or two-dimensional

define(surfs, mask_img, roi=None, maxradius=10, maxvoxels=numpy.inf, verbose=True)

Calculates the voxel_list for a Volume-based searchlight .

Args:

surfs (list of strs):

List of surface gifti file names used to define the searchlight centers.

mask_img (filename or NiftiImage):

Mask image to define input space (voxels to be used in the searchlight)

roi (filename, GiftiImage, ndrarray):

Define searchlight centers. If not given, the searchlight centers are calculated for all vertices.

radius (float):

Maximum searchlight radius - set to a large value if you only want a fixed number of voxels

nvoxels (int):

Number of voxels in the searchlight. set , the searchlight will be defined by a constant radius.

verbose (bool):

If True, print progress messages.

class AnatSearchlight.searchlight.SearchlightVolume(structure='none')

Bases: Searchlight

Anatomically informed searchlights for 3d volumes, given an ROI image. Voxels we picked from the mask_img, if an extra mask_image is provided.

data_to_nifti(results, outfilename=None)

Returns as nifti file with the results of the searchlight analysis. Args:

results (np.array):

Results of the searchlight analysis Can either be one-dimensional (n_centers,) -> 3d nifti Or two-dimensional (n_centers,n_results) -> 4d nifti

outfilename (str):

Filename to save the nifti image to. If None, the image is returned, but not saved.

Returns

img (nb.Nifti1Image):

Nifti image with the results of the searchlight analysis.

define(roi_img, mask_img=None, maxradius=5, maxvoxels=numpy.inf, verbose=True)

Calculates the voxel_list for a Volume-based searchlight .

Args:

roi_img (filename or NiftiImage):

ROI binary mask image to define searchlight centers. Same space as the later input data.

mask_img (filename or NiftiImage):

Mask image to define input space (voxels to be used in the searchlight), By default (None) the ROI image is used here as well. Should be in the same space as the later input data.

maxradius (float):

Maximum searchlight radius - set to np.inf if you only want a fixed number of voxels

maxvoxels (float):

Max number of voxels in the searchlight - set to np.inf if you want a fixed radius

verbose (bool):

If True, print progress messages.

AnatSearchlight.searchlight.load(fname, single=False, idx=None)

Loads a searchlight definition from an HDF5 file

Args:

fname (str): Filename

Returns:

Searchlight: Searchlight object