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 (lowres) surface write
(fn)
average_node_edge_length
¶ Average length of edges associated with each face
Returns: n2el: np.ndarray :
Pvalued 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 :
3value 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 (P1) elements, where the ith 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 (lowresolution) 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 (lowresolution) 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 ith 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 (Pvalued 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 (lowres) surface
Parameters: highres_surf: Surface :
Highresolution surface.
highres_indices: np.ndarray :
List of indices in highres 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 highres surface indexed by high_idx is nearest (in a Dijsktra distance sense) distance d to the node on the highres surface high_in_low_idx that has a corresponding node on the lowres surface

write
(fn)¶
