toblerone package

Subpackages

• toblerone.classes package
  • Submodules
  • toblerone.classes.common_parser module
  • toblerone.classes.image_space module
  • toblerone.classes.surfaces module
  • Module contents
• toblerone.pvestimation package
  • Submodules
  • toblerone.pvestimation.estimators module
  • Module contents

Submodules

toblerone.commandline module

toblerone.commandline.estimate_cortex()

CLI for estimating PVs from cortex (either L,R, or both)

toblerone.commandline.estimate_structure()

CLI for estimating PVs from a single surface

toblerone.commandline.estimate_complete()

CLI for estimating PVs for L/R cortex and subcortex

toblerone.commandline.convert_surface()

CLI for converting surface formats

toblerone.commandline.prepare_projector()

CLI for making a Projector

toblerone.core module

toblerone.core.form_associations(points_vox, tris, space, cores=2)

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)

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)

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)

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)

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)

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_subcortical_nodes

Number of subcortical ROIs

property roi_names

List of names for subcortical ROIs

adjacency_matrix(distance_weight=0)

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)

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()

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()

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()

Flattened 3D array of interior/exterior PVs for all ROIs.

Returns

np.array, same shape as self.ref_spc

pvs()

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.

vol2surf_matrix(edge_scale)

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)

Returns

sparse CSR matrix, sized (surface vertices x voxels). Surface vertices

are arranged L then R.

vol2hybrid_matrix(edge_scale)

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)

Returns

sparse CSR matrix, sized ((surface vertices + voxels) x voxels)

surf2vol_matrix(edge_scale)

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).

Returns

sparse CSC matrix, sized (surface vertices x voxels)

hybrid2vol_matrix(edge_scale)

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).

Returns

sparse CSR matrix, sized (voxels x (surface vertices + voxels))

vol2surf(vdata, edge_scale)

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)

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)

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)

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.projection.assemble_vol2surf(vox_tri, vtx_tri)

Combine with normalisation the vox_tri and vtx_tri matrices into vol2surf.

toblerone.projection.assemble_surf2vol(vox_tri, vtx_tri)

Combine with normalisation the vox_tri and vtx_tri matrices into surf2vol.

toblerone.utils module

Toblerone utility functions

toblerone.utils.cascade_attributes(decorator)

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.check_anat_dir(dir)

Check that dir contains output from FIRST and FAST

toblerone.utils.affine_transform(points, affine)

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.enforce_and_load_common_arguments(original)

toblerone.utils.sparse_normalise(mat, axis, threshold=1e-06)

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.is_symmetric(a, tol=1e-09)

toblerone.utils.is_nsd(a)

toblerone.utils.calc_midsurf(in_surf, out_surf)

Midsurface between two Surfaces

toblerone.utils.calculateXprods(points, tris)

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)

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.rebase_triangles(points, tris, tri_inds)

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.

toblerone.utils.space_encloses_surface(space, points_vox)

toblerone.utils.load_surfs_to_hemispheres(**kwargs)

Module contents

Surface-based analysis tools for neuroimaging