toblerone package

Subpackages

Submodules

toblerone.commandline module

toblerone.commandline.estimate_cortex()[source]

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

toblerone.commandline.estimate_structure()[source]

CLI for estimating PVs from a single surface

toblerone.commandline.estimate_complete()[source]

CLI for estimating PVs for L/R cortex and subcortex

toblerone.commandline.convert_surface()[source]

CLI for converting surface formats

toblerone.commandline.prepare_projector()[source]

CLI for making a Projector

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.

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

Combine with normalisation the vox_tri and vtx_tri matrices into vol2surf.

toblerone.projection.assemble_surf2vol(vox_tri, vtx_tri)[source]

Combine with normalisation the vox_tri and vtx_tri matrices into surf2vol.

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

Check that dir contains output from FIRST and FAST

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.enforce_and_load_common_arguments(original)[source]
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.is_symmetric(a, tol=1e-09)[source]
toblerone.utils.is_nsd(a)[source]
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_laplacian(lap, mask)[source]
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.

toblerone.utils.space_encloses_surface(space, points_vox)[source]
toblerone.utils.load_surfs_to_hemispheres(**kwargs)[source]

Module contents

Surface-based analysis tools for neuroimaging