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

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.

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)