toblerone.classes package

Submodules

toblerone.classes.common_parser module

CommonParser: a subclass of the library ArgumentParser object pre-configured to parse arguments that are common to many pvtools functions

class toblerone.classes.common_parser.CommonParser(*args_to_add, **kwargs)

Bases: ArgumentParser

Preconfigured subclass of ArgumentParser to parse arguments that are common across pvtools functions. To use, instantiate an object, then call add_argument to add in the arguments unique to the particular function in which it is being used, then finally call parse_args as normal.

toblerone.classes.image_space module

ImageSpace: image matrix, inc dimensions, voxel size, vox2world matrix and inverse, of an image. Inherits most methods and properties from regtricks.ImageSpace.

class toblerone.classes.image_space.ImageSpace(reference)

Bases: ImageSpace

Voxel grid of an image, ignoring actual image data.

Parameters:

reference – path to image file, or regtricks ImageSpace object

size

array of voxel counts in each dimension

vox_size

array of voxel size in each dimension

vox2world

4x4 affine to transform voxel coords -> world

world2vox

inverse of above

self.offset

private variable used for derived spaces

classmethod minimal_enclosing(surfs, reference)

Return the minimal space required to enclose a set of surfaces. This space will be based upon the reference, sharing its voxel size and i,j,k unit vectors from the voxel2world matrix, but will may have a different FoV. The offset of the voxel coord system relative to reference will be stored as the space.offset attribute

Parameters:

• surfs – singular or list of surface objects

• reference – ImageSpace object or path to image to use

Returns:

ImageSpace object, with a shifted origin and potentially different

FoV relative to the reference. Subtract offset from coords in this space to return them to original reference coords.

derives_from(parent)

Logical test whether this ImageSpace was derived from another. “Derived” means sharing i,j,k unit vectors and having their origins shifted by an integer multiple of voxels relative to each other.

toblerone.classes.image_space.reindexing_filter(src_space, dest_space, as_bool=False)

Filter of voxels in the source space that lie within destination space. Use for extracting PV estimates from index space back to the space from which the index space derives. NB dest_space must derive from the surface’s current index_space

Parameters:

• src_space – ImageSpace data is currently in

• dest_space – ImageSpace data will be mapped into. Must derive from src_space.

• as_bool – output results as logical filters instead of indices (note they will be of different size in this case)

Returns:

(src_inds, dest_inds) arrays of equal length, flat indices into arrays of size src_space.size and dest_space.size respectively, mapping voxels from source to corresponding destination positions

toblerone.classes.surfaces module

Surface-related classes

class toblerone.classes.surfaces.Surface(path, name=None)

Bases: object

Encapsulates a surface’s points, triangles and associations data. Create either by passing a file path (as below) or use the static class method Surface.manual() to directly pass points and triangles.

Parameters:

• path (str) – path to file (GIFTI/FS binary/pyvista compatible)

• name (str) – optional, for progress bars

classmethod manual(ps, ts, name='<manually created surface>')

Manual surface constructor using points and triangles arrays

property n_points

save_metric(data, path)

Save vertex-wise data as a .func.gii at path

save(path)

Save surface as .surf.gii (default), .white/.pial at path.

output_pvs(*args)

Express PVs in the voxel grid of space. Space must derive from that which the surface was indexed with (see ImageSpace.derives_from()).

index_on(space, cores=2)

Index a surface to an ImageSpace. This is a pre-processing step for PV estimation and produces a set of state variables that are specific to the space that the surface has been indexed on. Accordingly, these are all stored on the surface.indexed attribute to keep them clear of the original surface attributes.

Parameters:

• space (ImageSpace) – voxel grid to index against.

• cores (int) – CPU cores for multiprocessing.

Returns:

None, but the attribute self.indexed is set (see notes)

Notes

self.indexed.points_vox: vertices converted into voxel coordinates for the space

self.indexed.assocs: vertex/voxel associations as sparse CSR bool matrix of size (voxs, tris)

self.indexed.assocs_keys: flat voxel indices that intersect surface

self.indexed.xprods: surface triangle cross products in voxel coordinates

self.indexed.space: the minimal enclosing ImageSpace used for indexing associations

(NB this is not necessarily the same as the input space)

voxelise(*args)

Voxelise a surface within an ImageSpace. This requires the surface to have been indexed on the same ImageSpace first.

Parameters:

• space (ImageSpace) – voxel grid to test against surface

• cores (int) – CPU cores to use

Returns

(bool): flat array of voxels contained within surface

reindex_LUT(*args)

Return a copy of LUT indices expressed in another space

find_bridges(*args)

Find voxels within space that are intersected by this surface multiple times

Parameters:

space – ImageSpace, or path to image, in which to find bridge voxels NB the surface must have been indexed in this space already (see Surface.index_on)

Returns:

array of linear voxel indices

transform(transform)

Apply affine transformation to surface vertices, return new Surface

to_patch(vox_idx)

Return a patch object specific to a voxel given by linear index. Look up the triangles intersecting the voxel, and then load and rebase the points / surface normals as required.

to_patches(vox_inds)

Return the patches for the voxels in voxel indices, flattened into a single set of ps, ts and xprods.

If no patches exist for this list of voxels return None.

to_polydata()

Return pyvista polydata object for this surface

adjacency_matrix(distance_weight=0)

Adjacency matrix for the points of this surface, as a scipy sparse matrix of size P x P, with 1 denoting a shared edge between points.

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.

mesh_laplacian(distance_weight=0)

Mesh Laplacian operator for this surface, as a scipy sparse matrix of size n_points x n_points. Elements on the diagonal are negative and off-diagonal elements are positive. All neighbours are weighted with value 1 (ie, equal weighting ignoring distance).

Parameters:

distance_weight (int) – apply inverse distance weighting, default 0 (do not weight, all values are unity), whereas positive values will weight elements by 1 / d^n, where d is geometric distance between vertices.

Returns:

sparse CSR matrix

cotangent_laplacian()

Discrete Laplacian operator with cotangent weights. Elements on the diagonal are the negative sum of each row / column. Taken from:

http://jamesgregson.ca/mesh-processing-in-python-implementing-arap-deformation.html

Returns:

sparse CSR matrix, size (n_points x n_points)

edges()

Edge matrix, sized as follows (tris, 3, 3), where the second dimension contains the edges defined as (v1 - v0), (v2 - v0), (v2 - v1), and the final dimension contains the edge components in XYZ.

class toblerone.classes.surfaces.Patch(points, tris, xprods)

Bases: Surface

Subclass of Surface that represents a small patch of surface. Points, triangles and xprods are all inherited from the parent surface. This class should not be directly created but instead instantiated via the Surface.to_patch() / to_patches() methods.

shrink(fltr)

Return a shrunk copy of the patch by applying the logical filter fltr to the calling objects tris and xprods matrices

class toblerone.classes.surfaces.Hemisphere(insurf, outsurf, side)

Bases: object

The white and pial surfaces of a hemisphere, and a repository to store data when calculating tissue PVs from the fractions of each surface

Parameters:

• inpath – path to white surface

• outpath – path to pial surface

• side – ‘L’ or ‘R’

property surfs

Iterator over the inner/outer surfaces

property surf_dict

Return surfs as dict with appropriate keys (eg LPS)

transform(mat)

Apply affine transformation to each surface. Returns a new Hemisphre.

midsurface()

Midsurface between inner and outer cortex

thickness()

adjacency_matrix(distance_weight=0)

Adjacency matrix of any cortical surface (they necessarily share the same triagulation, which is checked during initialisation).

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.

property n_points

Number of vertices on either cortical surface

mesh_laplacian(distance_weight=0)

Mesh Laplacian on cortical midsurface.

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.

cotangent_laplacian()

Discrete Laplacian operator with cotangent weights on midsurface. Elements on the diagonal are the negative sum of each row / column. Taken from: http://jamesgregson.ca/mesh-processing-in-python-implementing-arap-deformation.html

Returns:

sparse CSR matrix, size (n_points x n_points)

Module contents

Toblerone classes