toblerone package¶
Subpackages¶
- toblerone.classes package
- Submodules
- toblerone.classes.common_parser module
- toblerone.classes.image_space module
- toblerone.classes.surfaces module
Surface
Surface.manual()
Surface.n_points
Surface.save_metric()
Surface.save()
Surface.output_pvs()
Surface.index_on()
Surface.voxelise()
Surface.reindex_LUT()
Surface.find_bridges()
Surface.transform()
Surface.to_patch()
Surface.to_patches()
Surface.to_polydata()
Surface.adjacency_matrix()
Surface.mesh_laplacian()
Surface.cotangent_laplacian()
Surface.edges()
Patch
Hemisphere
- Module contents
- toblerone.pvestimation package
Submodules¶
toblerone.commandline module¶
- toblerone.commandline.estimate_cortex()[source]¶
CLI for estimating PVs from cortex (either L,R, or both)
toblerone.core module¶
- toblerone.core.form_associations(points_vox, tris, space, cores=2)[source]¶
Identify which triangles of a surface intersect each voxel. This reduces the number of operations that need be performed later. The results will be stored on the surface object (ie, self)
- Returns:
None, but associations (sparse CSR matrix of size (voxs, tris) and assocs_keys (array of voxel indices containint the surface) will be set on the calling object.
- toblerone.core.vox_tri_weights(in_surf, out_surf, spc, factor, cores=2, descriptor='', ones=False)[source]¶
Form matrix of size (n_vox x n_tris), in which element (I,J) is the fraction of samples from voxel I that are in triangle prism J.
- Parameters:
in_surf – Surface object, inner surface of cortical ribbon
out_surf – Surface object, outer surface of cortical ribbon
spc – ImageSpace object within which to project
factor – voxel subdivision factor
cores – number of cpu cores
descriptor – string for tqdm progress bar
- Returns:
- a scipy.sparse CSR matrix of shape
(n_voxs, n_tris), in which each entry at index [I,J] gives the number of samples from triangle prism J that are in voxel I. NB this matrix is not normalised in any way!
- Return type:
vox_tri_weights
- toblerone.core.vtx_tri_weights(surf, cores=2)[source]¶
Form a matrix of size (n_vertices x n_tris) where element (I,J) corresponds to the area of triangle J belonging to vertex I.
Areas are calculated according to the definition of A_mixed in “Discrete Differential-Geometry Operators for Triangulated 2-Manifolds”, M. Meyer, M. Desbrun, P. Schroder, A.H. Barr.
With thanks to Jack Toner for the original code from which this is adapted.
- Parameters:
surf – Surface object
cores – number of CPU cores to use, default max
- Returns:
- sparse CSR matrix, size (n_points, n_tris) where element I,J is the
area of triangle J belonging to vertx I
toblerone.ctoblerone module¶
toblerone.ctoblerone module¶
toblerone.projection module¶
Projection between surface, volume and hybrid spaces
- class toblerone.projection.Projector(hemispheres, spc, rois=None, factor=None, cores=2, ones=False)[source]¶
Bases:
object
Use to perform projection between volume, surface and node space. Creating a projector object may take some time whilst the consituent matrices are prepared; once created any of the individual projections may be calculated directly from the object.
Node space ordering: L hemisphere surface, R hemisphere surface, subcortical voxels in linear index order, subcortical ROIs in alphabetical order according to their dictionary key (see below)
- Parameters:
hemispheres (list/Hemisphere) – single or list (L/R) of Hemisphere objects. Note that the surfaces of the hemispheres must be in alignment with the reference space (ie, apply any transformations beforehand).
spc (str/ImageSpace) – path for, or ImageSpace object, for voxel grid to project from/to
rois (dict) – subcortical ROIs; keys are ROI name and values are paths to surfaces or Surface objects for the ROIs themselves.
factor (int) – voxel subdivision factor (default 3x voxel size)
cores (int) – number of processor cores to use (default max)
ones (bool) – debug tool, whole voxel PV assignment.
- save(path)[source]¶
Save Projector in HDF5 format.
A projector can be re-used for multiple analyses, assuming the reference image space and cortical surfaces remain in alignment for all data.
- Parameters:
path (str) – path to write out with .h5 extension
- classmethod load(path)[source]¶
Load Projector from path in HDF5 format.
This is useful for performing repeated analyses with the same voxel grid and cortical surfaces.
- Parameters:
path (str) – path to load from
- property iter_hemis¶
Iterator over hemispheres of projector, in L/R order
- property n_hemis¶
Number of hemispheres (1/2) in projector
- property n_surf_nodes¶
Number of surface vertices in projector (one or both hemis)
- property n_nodes¶
Number of nodes in projector (surface, voxels, subcortical ROIs)
- property n_vox¶
Number of voxels in reference ImageSpace
- property n_subcortical_nodes¶
Number of subcortical ROIs
- property roi_names¶
List of names for subcortical ROIs
- adjacency_matrix(distance_weight=0)[source]¶
Adjacency matrix for all surface vertices of projector.
If there are two hemispheres present, the matrix indices will be arranged L,R.
- Parameters:
distance_weight (int) – apply inverse distance weighting, default 0 (do not weight, all egdes are unity), whereas positive values will weight edges by 1 / d^n, where d is geometric distance between vertices.
- Returns:
sparse CSR matrix, square sized (n vertices)
- mesh_laplacian(distance_weight=0)[source]¶
Mesh Laplacian matrix for all surface vertices of projector.
If there are two hemispheres present, the matrix indices will be arranged L/R.
- Parameters:
distance_weight (int) – apply inverse distance weighting, default 0 (do not weight, all egdes are unity), whereas positive values will weight edges by 1 / d^n, where d is geometric distance between vertices.
- Returns:
sparse CSR matrix
- cotangent_laplacian()[source]¶
Cotangent Laplacian matrix for all surface vertices of projector.
If there are two hemispheres present, the matrix indices will be arranged L/R.
- Returns:
sparse CSR matrix, square with size (n_vertices)
- cortex_pvs()[source]¶
Single Vx3 array of cortex PVs for all hemispheres of Projector.
- Returns:
- np.array, same shape as reference space, arranged GM, WM,
non-brain in 4th dim.
- subcortex_pvs()[source]¶
Flattened 3D array of interior/exterior PVs for all ROIs.
- Returns:
np.array, same shape as
self.ref_spc
- pvs()[source]¶
Flattened 4D array of PVs for cortex, subcortex and ROIs.
- Returns:
- np.array, same shape as reference space, arranged GM, WM,
non-brain in 4th dim.
- brain_mask(pv_threshold=0.1)[source]¶
Boolean mask of brain voxels, in reference ImageSpace
- Parameters:
pv_threshold (float) – minimum brain PV (WM+GM) to include
- Returns:
np.array, same shape as reference space, boolean dtype
- vol2surf_matrix(edge_scale, vol_mask=None, surf_mask=None)[source]¶
Volume to surface projection matrix.
- Parameters:
edge_scale (bool) – upweight signal from voxels that are not 100% brain to account for ‘missing’ signal. Set True for quantities that scale with PVE (eg perfusion), set False otherwise (eg time quantities)
vol_mask (np.array,bool) – bool mask of voxels to include
surf_mask (np.array,bool) – bool mask of surface vertices to include
- Returns:
- sparse CSR matrix, sized (surface vertices x voxels). Surface vertices
are arranged L then R.
- vol2hybrid_matrix(edge_scale, vol_mask=None, node_mask=None)[source]¶
Volume to node space projection matrix.
- Parameters:
edge_scale (bool) – upweight signal from voxels that are not 100% brain to account for ‘missing’ signal. Set True for quantities that scale with PVE (eg perfusion), set False otherwise (eg time quantities)
vol_mask (np.array,bool) – bool mask of voxels to include
node_mask (np.array,bool) – bool mask of nodes to include
- Returns:
sparse CSR matrix, sized (nodes x voxels)
- surf2vol_matrix(edge_scale, vol_mask=None, surf_mask=None)[source]¶
Surface to volume projection matrix.
- Parameters:
edge_scale (bool) – downweight signal in voxels that are not 100% brain: set True for data that scales with PVE (eg perfusion), set False for data that does not (eg time quantities).
vol_mask (np.array,bool) – bool mask of voxels to include
surf_mask (np.array,bool) – bool mask of surface vertices to include
- Returns:
sparse CSC matrix, sized (surface vertices x voxels)
- hybrid2vol_matrix(edge_scale, vol_mask=None, node_mask=None)[source]¶
Node space to volume projection matrix.
- Parameters:
edge_scale (bool) – downweight signal in voxels that are not 100% brain: set True for data that scales with PVE (eg perfusion), set False for data that does not (eg time quantities).
vol_mask (np.array,bool) – bool mask of voxels to include
node_mask (np.array,bool) – bool mask of nodes to include
- Returns:
sparse CSR matrix, sized (voxels x nodes)
- vol2surf(vdata, edge_scale)[source]¶
Project data from volum to surface.
- Parameters:
vdata (np.array) – sized n_voxels in first dimension
edge_scale (bool) – upweight signal from voxels that are not 100% brain to account for ‘missing’ signal. Set True for quantities that scale with PVE (eg perfusion), set False otherwise (eg time quantities)
- Returns:
np.array, sized n_vertices in first dimension
- surf2vol(sdata, edge_scale)[source]¶
Project data from surface to volume.
- Parameters:
sdata (np.array) – sized n_vertices in first dimension (arranged L,R)
edge_scale (bool) – downweight signal in voxels that are not 100% brain: set True for data that scales with PVE (eg perfusion), set False for data that does not (eg time quantities).
- Returns:
np.array, sized n_voxels in first dimension
- vol2hybrid(vdata, edge_scale)[source]¶
Project data from volume to node space.
- Parameters:
vdata (np.array) – sized n_voxels in first dimension
edge_scale (bool) – upweight signal from voxels that are not 100% brain to account for ‘missing’ signal. Set True for quantities that scale with PVE (eg perfusion), set False otherwise (eg time quantities)
- Returns:
np.array, sized (n_vertices + n_voxels) in first dimension. Surface vertices are arranged L then R.
- hybrid2vol(ndata, edge_scale)[source]¶
Project data from node space to volume.
- Parameters:
ndata (np.array) – sized (n_vertices + n_voxels) in first dimension, Surface data should be arranged L, R in the first dim.
edge_scale (bool) – downweight signal in voxels that are not 100% brain: set True for data that scales with PVE (eg perfusion), set False for data that does not (eg time quantities).
- Returns:
np.array, sized n_voxels in first dimension
toblerone.utils module¶
Toblerone utility functions
- toblerone.utils.cascade_attributes(decorator)[source]¶
Overrride default decorator behaviour to preserve docstrings etc of decorated functions - functools.wraps didn’t seem to work. See https://stackoverflow.com/questions/6394511/python-functools-wraps-equivalent-for-classes
- toblerone.utils.affine_transform(points, affine)[source]¶
Apply affine transformation to set of points.
- Parameters:
points – n x 3 matrix of points to transform
affine – 4 x 4 matrix for transformation
- Returns:
transformed copy of points
- toblerone.utils.sparse_normalise(mat, axis, threshold=1e-06)[source]¶
Normalise a sparse matrix so that all rows (axis=1) or columns (axis=0) sum to either 1 or zero. NB any rows or columns that sum to less than threshold will be rounded to zeros.
- Parameters:
mat – sparse matrix to normalise
axis – dimension for which sum should equal 1 (1 for row, 0 for col)
threshold – any row/col with sum < threshold will be set to zero
- Returns:
sparse matrix, same format as input.
- toblerone.utils.calculateXprods(points, tris)[source]¶
Normal vectors for points,triangles array. For triangle vertices ABC, this is calculated as (C - A) x (B - A).
- toblerone.utils.slice_sparse(mat, slice0, slice1)[source]¶
Slice a block out of a sparse matrix, ie mat[slice0,slice1]. Scipy sparse matrices do not support slicing in this manner (unlike numpy)
- Parameters:
mat (sparse) – of any form
slice0 (bool,array) – mask to apply on axis 0 (rows)
slice1 (bool,array) – mask to apply on axis 1 (columns)
- Returns:
CSR matrix
- toblerone.utils.mask_projection_matrix(matrix, row_mask, col_mask)[source]¶
Mask a sparse projection matrix, whilst preserving total signal intensity. For example, if the mask implies discarding voxels from a vol2surf matrix, upweight the weights of the remaining voxels to account for the discarded voxels. Rows represent the target domain and columns the source.
- Parameters:
matrix (sparse) – of any form, shape (N,M)
row_mask (np.array,bool) – flat vector of size N, rows to retain in matrix
col_mask (np.array,bool) – flat vector of size M, cols to retain in matrix
- Returns:
CSR matrix, shape (sum(row_mask), sum(col_mask))
- toblerone.utils.rebase_triangles(points, tris, tri_inds)[source]¶
Re-express a patch of a larger surface as a new points and triangle matrix pair, indexed from 0. Useful for reducing computational complexity when working with a small patch of a surface where only a few nodes in the points array are required by the triangles matrix.
- Parameters:
points (np.array) – surface vertices, P x 3
tris (np.array) – surface triangles, T x 3
tri_inds (np.array) – row indices into triangles array, to rebase
- Returns:
(points, tris) tuple of re-indexed points/tris.
Module contents¶
Surface-based analysis tools for neuroimaging