Multivariate Pattern Analysis in Python

# 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: |

  `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.

  `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)