mvpa2.support.nibabel.surf.Surface¶

class mvpa2.support.nibabel.surf.Surface(v, f=None, check=True)¶

Cortical surface mesh

A surface consists of a set of vertices (each with an x, y, and z coordinate) and a set of faces (triangles; each has three indices referring to the vertices that make up a triangle).

In the present implementation new surfaces should be made using the __init__ constructor; internal fields should not be changed manually

Parameters:

vertices : numpy.ndarray (float)

Px3 array with coordinates for P vertices.

faces : numpy.ndarray (int)

Qx3 array with vertex indices for Q faces (triangles).

check: boolean (default=True)

Do some sanity checks to ensure that vertices and faces have proper size and values.

Returns:

s : Surface

a surface specified by vertices and faces

Attributes

average_node_edge_length Average length of edges associated with each face

center_of_mass Computes the center of mass

edge2face A mapping from edges to the face that contains that edge

face_areas

face_edge_length Length of edges associated with each face

face_normals

faces

Returns:

nanmean_face_normal

neighbors Finds the neighbours for each node and their (Euclidean) distance.

nfaces

Returns:

node2faces A mapping from node indices to the faces that contain those nodes.

node_areas

node_normals

nvertices

Returns:

vertices

Returns:

Methods

`circlearound_n2d`(src, radius[, metric])	Finds the distances from a center node to surrounding nodes.
`connected_components`()
`connected_components_slow`()
`coordinates_to_box_indices`(box_size[, ...])	‘Boxes’ coordinates into triples
`dijkstra_distance`(src[, maxdistance])	Computes Dijkstra distance from one node to surrounding nodes
`dijkstra_shortest_path`(src[, maxdistance])	Computes Dijkstra shortest path from one node to surrounding nodes.
`dijkstra_shortest_path_visiting`(to_visit)	Computes a list of paths that visit specific nodes
`euclidean_distance`(src[, trg])	Computes Euclidean distance from one node to other nodes
`map_to_high_resolution_surf`(highres[, ...])	Finds a mapping to a higher resolution (denser) surface.
`map_to_high_resolution_surf_slow`(highres[, ...])	Finds a mapping to a higher resolution (denser) surface.
`merge`(\*others)	Merges the present surface with other surfaces
`nearest_node_index`(src_coords[, ...])	Computes index of nearest node to src
`nodes_on_border`([node_indices])	Determines which nodes are on the border of the surface
`nodes_on_border_paths`()	Find paths of nodes on the border
`pairwise_near_nodes`([max_distance, src, trg])	Finds the distances between pairs of nodes
`project_vertices`(n[, v])	Projects vertex coordinates onto a vector
`rotate`(theta[, center, unit])	Rotates the surface
`same_topology`(other)	Returns whether another surface has the same topology
`split_by_connected_components`()	Splits a surface by its connected components
`sub_surface`(src, radius)	Makes a smaller surface consisting of nodes around a center node
`vonoroi_map_to_high_resolution_surf`(highres_surf)	Computes a Vonoroi mapping for the current (low-res) surface
`write`(fn)

average_node_edge_length¶

Average length of edges associated with each face

Returns:

n2el: np.ndarray

P-valued vector where P==self.nvertices, where n2el[i] is the average length of the edges that contain node i.

center_of_mass¶

Computes the center of mass

Returns:

np.array

3-value vector with x,y,z coordinates of center of mass

circlearound_n2d(src, radius, metric='euclidean')¶

Finds the distances from a center node to surrounding nodes.

Parameters:

src : int

Index of center node

radius : float

Maximum distance for other nodes to qualify as a ‘surrounding’ node.

metric : string (default: euclidean)

‘euclidean’ or ‘dijkstra’: distance metric

Returns:

n2d : dict

A dict “n2d” so that n2d[j]=d” is the distance “d” from node “src” to node “j”.

connected_components()¶

connected_components_slow()¶

coordinates_to_box_indices(box_size, min_coord=None, master=None)¶

‘Boxes’ coordinates into triples

Parameters:

box_sizes:

min_coord: triple or ndarray

Minimum coordinates; maps to (0,0,0). If omitted, it defaults to the mininum coordinates in this surface.

max_coord: triple or ndarray

Minimum coordinates; maps to (nboxes[0]-1,nboxes[1]-1,nboxes[2]-1)). If omitted, it defaults to the maximum coordinates in this surface.

master: Surface.surf (default: None)

If provided, then min_coord and max_coord are taken from master.

Returns:

boxes_indices: np.ndarray of float

Array of size Px3, where P is the number of vertices

dijkstra_distance(src, maxdistance=None)¶

Computes Dijkstra distance from one node to surrounding nodes

Parameters:

src : int

Index of center (source) node

maxdistance: float (default: None)

Maximum distance for a node to qualify as a ‘surrounding’ node. If ‘maxdistance is None’ then the distances to all nodes is returned/

dijkstra_shortest_path(src, maxdistance=None)¶

Computes Dijkstra shortest path from one node to surrounding nodes.

Parameters:

src : int

Index of center (source) node

maxdistance: float (default: None)

Maximum distance for a node to qualify as a ‘surrounding’ node. If ‘maxdistance is None’ then the shortest path to all nodes is returned.

dijkstra_shortest_path_visiting(to_visit)¶

Computes a list of paths that visit specific nodes

Parameters:

to_visit: list of int

P indices of nodes to visit

Returns:

path_distances: list of tuple (int, list of int)

List with (P-1) elements, where the i-th element is a tuple (d_i, q_i) with distance d_i between nodes i and (i+1), and q_i a list of node indices on the path between nodes i and (i+1) so that q_i[0]==i and q_i[-1]==(i+1)

edge2face¶

A mapping from edges to the face that contains that edge

Returns:

e2f: dict

a mapping from edges to faces. e2f[(i,j)]==f means that the edge connecting nodes i and j contains node f. It is assumed that faces are consistent with respect to the direction of their normals: if self.faces[j,:]==[p,q,r] then the normal of vectors pq and pr should all either point ‘inwards’ or ‘outwards’.

euclidean_distance(src, trg=None)¶

Computes Euclidean distance from one node to other nodes

Parameters:

src : int or numpy.ndarray

Index of center (source) node, or a 1x3 array with coordinates of the center (source) node.

trg : int

Target node(s) to which the distance is computed. If ‘trg is None’ then distances to all nodes are computed

face_areas¶

face_edge_length¶

Length of edges associated with each face

Returns:

f2el: np.ndarray

Px3 array where P==self.nfaces. f2el[i,:] contains the length of the (three) edges that make up face i.

face_normals¶

faces¶

Returns:

faces: numpy.ndarray (float)

Qx3 coordinates for Q vertices

map_to_high_resolution_surf(highres, epsilon=0.001, accept_only_icosahedron=False)¶

Finds a mapping to a higher resolution (denser) surface. A typical use case is mappings between surfaces generated by MapIcosahedron, where the lower resolution surface defines centers in a searchlight whereas the higher resolution surfaces is used to delineate the grey matter for voxel selection. This function implements an optimization which in most cases yields solutions much faster than map_to_high_resolution_surf_exact, but may fail to find the correct solution for larger values of epsilon.

Parameters:

highres: surf.Surface

high resolution surface

epsilon: float

maximum margin (distance) between nodes mapped from low to high resolution surface. Default None, which implies .001.

accept_only_icosahedron: bool

if True, then this function raises an error if the number of nodes does not match those which would be expected from MapIcosahedorn.

Returns:

low2high: dict

mapping so that low2high[i]==j means that node i in the current (low-resolution) surface is mapped to node j in the highres surface.

map_to_high_resolution_surf_slow(highres, epsilon=0.001, accept_only_icosahedron=False)¶

Finds a mapping to a higher resolution (denser) surface. A typical use case is mappings between surfaces generated by MapIcosahedron, where the lower resolution surface defines centers in a searchlight whereas the higher resolution surfaces is used to delineate the grey matter for voxel selection. Unlike the function named “map_to_high_resolution_surf”, this function is both slow and exact—and is actually used in case the former function does not find a solution.

Parameters:

highres: surf.Surface

high resolution surface

epsilon: float

maximum margin (distance) between nodes mapped from low to high resolution surface

accept_only_icosahedron: bool

if True, then this function raises an error if the number of nodes does not match those which would be expected from MapIcosahedorn.

Returns:

low2high: dict

mapping so that low2high[i]==j means that node i in the current (low-resolution) surface is mapped to node j in the highres surface.

merge(*others)¶

Merges the present surface with other surfaces

Parameters:

others: list of surf.Surface

List of other surfaces to be merged with present one

Returns:

surf.Surface

A surface that has all the nodes of the current surface and the surfaces in others, and has the topologies combined from these surfaces as well. If the current surface has v_0 vertices and f_0 faces, and the i-th surface has v_i and f_i faces, then the output has sum_j (v_j) vertices and sum_j (f_j) faces.

nanmean_face_normal¶

nearest_node_index(src_coords, node_mask_indices=None)¶

Computes index of nearest node to src

Parameters:

src_coords: numpy.ndarray (Px3 array)

Coordinates of center

node_mask_idxs numpy.ndarray (default: None):

Indices of nodes to consider. By default all nodes are considered

Returns:

idxs: numpy.ndarray (P-valued vector)

Indices of nearest nodes

neighbors¶

Finds the neighbours for each node and their (Euclidean) distance.

Returns:

nbrs : dict

A dict “nbrs” so that “nbrs[i]=n2d” contains the distances from node i to the neighbours of node “i” in “n2d”. “n2d” is, in turn, a dict so that “n2d[k]=d” is the distance “d” from node “i” to node “j”. In other words, nbrs[i][j]=d means that the distance from node i to node j is d. It holds that nbrs[i][j]=nbrs[j][i].

nfaces¶

Returns:

nfaces: int

Number of faces

node2faces¶

A mapping from node indices to the faces that contain those nodes.

Returns:

n2v : dict

A dict “n2v” so that “n2v[i]=faceidxs” contains a list of the faces (indexed by faceidxs) that contain node “i”.

node_areas¶

node_normals¶

nodes_on_border(node_indices=None)¶

Determines which nodes are on the border of the surface

Parameters:

node_indices: np.ndarray or None

Vector with node indices for which their bordership status is to be deteremined. None means all node indices

Returns:

on_border: np.ndarray

Boolean array of shape (len(node_indices),). A node i is considered on the border if there is a face that contains node i and another node j so that no other face contains both i and j. In other words a node i is not on the border if there is a path of nodes p1,...pN so that N>1, p1==pN, pj!=pk if j!=k<N, and each node pk (and no other node) is a neighbor of node i.

nodes_on_border_paths()¶

Find paths of nodes on the border

Returns:

paths: list of lists

paths[i]=[k_0,...k_N] means that there is path of N+1 edges [(k_0,k_1),(k_1,...,k_N),(k_N,k_0)] where each k_i is on the border of the surface

nvertices¶

Returns:

nvertices: int

Number of vertices

pairwise_near_nodes(max_distance=None, src=None, trg=None)¶

Finds the distances between pairs of nodes

Parameters:

max_distance: None or float

maximum distance (None: no maximum distance)

src: array of int or None

source indices

trg: array of int or None

target indices

Returns:

source_target2distance: dict

A dictionary so that source_target2distance[i,j]=d means that the Euclidean distance between nodes i and j is d, where i in src and j in trg.

Notes

If src and trg are both None, then this function checks if the surface has two components; if so they are taken as source and target. A use case for this behaviour is a surface consisting of two hemispheres

project_vertices(n, v=None)¶

Projects vertex coordinates onto a vector

Parameters:

n: np.ndarray

Vector with 3 elements

v: np.ndarray or None

coordinates to be projected. If None then the vertices of the current instance are used.

Returns:

p: np.ndarray

Vector with coordinates projected onto n

rotate(theta, center=None, unit='rad')¶

Rotates the surface

Parameters:

theta:

np.array with 3 values for rotation along x, y, z axes

center:

np.array with center around which surface is rotated. If None, then rotation is around the origin (0,0,0).

unit:

‘rad’ or ‘deg’ for angles in theta in either radians or degrees.

Returns:

surf.Surface

the result after rotating with angles theta around center.

same_topology(other)¶

Returns whether another surface has the same topology

Parameters:

other: surf.Surface

another surface

Returns:

bool

True iff the current surface has the same number of coordinates and the same faces as ‘other’.

split_by_connected_components()¶

Splits a surface by its connected components

Returns:

splits: list of surf.Surface

A list of all surfaces that make up the original surface, split when they are not connected to each other. (If all nodes in the original surface are connected then a list is returned with a single surface that is identical to the input). The output is sorted by the number of vertices.

sub_surface(src, radius)¶

Makes a smaller surface consisting of nodes around a center node

Parameters:

src : int

Index of center (source) node

radius : float

Lower bound of (Euclidean) distance to ‘src’ in order to be part of the smaller surface. In other words, if a node ‘j’ is within ‘radius’ from ‘src’, then ‘j’ is also part of the resulting surface.

Returns:

small_surf: Surface

a smaller surface containing nodes surrounding ‘src’

nsel: np.array (int)

indices of nodes selected from the original surface

fsel: np.array (int)

indices of faces selected from the original surface

orig_src: int

index of ‘src’ in the original surface

vertices¶

Returns:

vertices: numpy.ndarray (int)

Px3 coordinates for P vertices

vonoroi_map_to_high_resolution_surf(highres_surf, highres_indices=None, epsilon=0.001, accept_only_icosahedron=False)¶

Computes a Vonoroi mapping for the current (low-res) surface

Parameters:

highres_surf: Surface

High-resolution surface.

highres_indices: np.ndarray

List of indices in high-res surface that have to be mapped.

epsilon: float

maximum margin (distance) between nodes mapped from low to high resolution surface. Default None, which implies .001.

accept_only_icosahedron: bool

if True, then this function raises an error if the number of nodes does not match those which would be expected from MapIcosahedorn.

Returns:

high2high_in_low: dict

A mapping so that high2high_in_low[high_idx]=(high_in_low_idx,d) means that the node on the high-res surface indexed by high_idx is nearest (in a Dijsktra distance sense) distance d to the node on the high-res surface high_in_low_idx that has a corresponding node on the low-res surface

write(fn)¶