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.
