mvpa2.misc.surfing.queryengine.disc_surface_queryengine

mvpa2.misc.surfing.queryengine.disc_surface_queryengine(radius, volume, white_surf, pial_surf, source_surf=None, source_surf_nodes=None, volume_mask=False, distance_metric='dijkstra', start_mm=0, stop_mm=0, start_fr=0.0, stop_fr=1.0, nsteps=10, eta_step=1, add_fa=None, nproc=None, outside_node_margin=None, results_backend=None, tmp_prefix='tmpvoxsel', output_modality='surface', node_voxel_mapping='maximal')

Voxel selection wrapper for multiple center nodes on the surface

WiP XXX currently the last parameter ‘output_modality’ determines what kind of query engine is returned - is that bad?

XXX: have to decide whether to use minimal_voxel_mapping=True as default

Parameters:

radius: int or float

Size of searchlight. If an integer, then it indicates the number of voxels. If a float, then it indicates the radius of the disc

volume: Dataset or NiftiImage or volgeom.Volgeom

Volume in which voxels are selected.

white_surf: str of surf.Surface

Surface of white-matter to grey-matter boundary, or filename of file containing such a surface.

pial_surf: str of surf.Surface

Surface of grey-matter to pial-matter boundary, or filename of file containing such a surface.

source_surf: surf.Surface or None

Surface used to compute distance between nodes. If omitted, it is the average of the gray and white surfaces.

source_surf_nodes: list of int or numpy array or None

Indices of nodes in source_surf that serve as searchlight center. By default every node serves as a searchlight center.

volume_mask: None (default) or False or int

Mask from volume to apply from voxel selection results. By default no mask is applied. If volume_mask is an integer k, then the k-th volume from volume is used to mask the data. If volume is a Dataset and has a property volume.fa.voxel_indices, then these indices are used to mask the data, unless volume_mask is False or an integer.

distance_metric: str

Distance metric between nodes. ‘euclidean’ or ‘dijksta’ (default)

start_fr: float (default: 0)

Relative start position of line in gray matter, 0.=white surface, 1.=pial surface

stop_fr: float (default: 1)

Relative stop position of line (as in start_fr)

start_mm: float (default: 0)

Absolute start position offset (as in start_fr)

stop_mm: float (default: 0)

Absolute start position offset (as in start_fr)

nsteps: int (default: 10)

Number of steps from white to pial surface

eta_step: int (default: 1)

After how many searchlights an estimate should be printed of the remaining time until completion of all searchlights

add_fa: None or list of strings

Feature attributes from a dataset that should be returned if the queryengine is called with a dataset.

nproc: int or None

Number of parallel threads. None means as many threads as the system supports. The pprocess is required for parallel threads; if it cannot be used, then a single thread is used.

outside_node_margin: float or None (default)

By default nodes outside the volume are skipped; using this parameters allows for a marign. If this value is a float (possibly np.inf), then all nodes within outside_node_margin Dijkstra distance from any node within the volume are still assigned associated voxels. If outside_node_margin is True, then a node is always assigned voxels regardless of its position in the volume.

results_backend : ‘native’ or ‘hdf5’ or None (default).

Specifies the way results are provided back from a processing block in case of nproc > 1. ‘native’ is pickling/unpickling of results by pprocess, while ‘hdf5’ would use h5save/h5load functionality. ‘hdf5’ might be more time and memory efficient in some cases. If None, then ‘hdf5’ if used if available, else ‘native’.

tmp_prefix : str, optional

If specified – serves as a prefix for temporary files storage if results_backend == ‘hdf5’. Thus can specify the directory to use (trailing file path separator is not added automagically).

output_modality: ‘surface’ or ‘volume’ (default: ‘surface’)

Indicates whether the output is surface-based

node_voxel_mapping: ‘minimal’ or ‘maximal’

If ‘minimal’ then each voxel is associated with at most one node. If ‘maximal’ it is associated with as many nodes that contain the voxel (default: ‘maximal’)

Returns:

qe: SurfaceVerticesQueryEngine

Query-engine that maps center nodes to indices of features (voxels) that are near each center node. If output_modality==’volume’ then qe is of type subclass SurfaceVoxelsQueryEngine.